donobu
Version:
Create browser automations with an LLM agent and replay them as Playwright scripts.
111 lines • 5 kB
TypeScript
import type { DonobuExtendedPage } from '../../page/DonobuExtendedPage';
import type { AssertCacheEntry, AssertCacheEntryWithRunner, AssertCacheKey, LocateCacheEntry, LocateCacheEntryWithRunner, LocateCacheKey } from './assertCache';
/**
* Cache key used to identify a unique `page.ai.act(...)` or `device.ai(...)` invocation.
* Keep this structure aligned with the code generator so replayed runs remain deterministic.
*
* Note: `pageUrl` typically stores the hostname (e.g., "example.com") extracted from the full URL,
* allowing cache hits across different paths and query parameters on the same domain.
* For mobile entries, `pageUrl` is the sentinel `"mobile://app"`.
*/
export type PageAiCacheKey = {
/** Discriminator for web vs mobile cache entries. Defaults to `'web'` for backwards compat. */
deviceType?: 'web' | 'android' | 'ios';
pageUrl: string;
instruction: string | null;
schema: Record<string, unknown> | null;
allowedTools: string[];
maxToolCalls: number | null;
envVars: string[] | null;
};
/**
* Serialized cache entry stored on disk.
*/
export type PageAiCacheEntry = PageAiCacheKey & {
runSource: string;
};
/**
* Entry hydrated with an executable runner.
*/
export type PageAiCacheEntryWithRunner = PageAiCacheEntry & {
run: PageAiCacheExecutor;
};
/**
* JSON structure used by tooling (e.g., code generator) to emit cache files.
*/
export type PageAiCacheContents = {
caches: PageAiCacheEntry[];
assertions?: AssertCacheEntry[];
locators?: LocateCacheEntry[];
};
export type PageAiCacheExecutionContext = {
page?: DonobuExtendedPage;
/** Plugin-provided device (e.g. mobile). Typed as `unknown` — callers cast as needed. */
device?: unknown;
};
export type PageAiCacheExecutor = (context: PageAiCacheExecutionContext) => Promise<unknown>;
/**
* Minimal interface for cache clients. Implementations can be file-backed,
* in-memory (useful for tests), or even remote services.
*/
export interface PageAiCache {
get(key: PageAiCacheKey): Promise<PageAiCacheEntryWithRunner | null>;
put(entry: PageAiCacheEntry): Promise<void>;
delete(key: PageAiCacheKey): Promise<boolean>;
snapshot(): Promise<PageAiCacheContents>;
getAssert(key: AssertCacheKey): Promise<AssertCacheEntryWithRunner | null>;
putAssert(entry: AssertCacheEntry): Promise<void>;
deleteAssert(key: AssertCacheKey): Promise<boolean>;
getLocate(key: LocateCacheKey): Promise<LocateCacheEntryWithRunner | null>;
putLocate(entry: LocateCacheEntry): Promise<void>;
deleteLocate(key: LocateCacheKey): Promise<boolean>;
}
export declare const renderCacheModule: (entries: PageAiCacheEntry[], assertions?: AssertCacheEntry[], locators?: LocateCacheEntry[]) => string;
/**
* File-backed implementation used by the Playwright fixture. Protects reads and
* writes with an OS-level lock so concurrent processes do not corrupt the file.
*
* Both page.ai flow caches and assertion caches live in the same file to avoid
* a separate file and lock for assertions.
*/
export declare class FilePageAiCache implements PageAiCache {
private readonly cacheFilepath;
constructor(cacheFilepath: string);
get(key: PageAiCacheKey): Promise<PageAiCacheEntryWithRunner | null>;
put(entry: PageAiCacheEntry): Promise<void>;
delete(key: PageAiCacheKey): Promise<boolean>;
snapshot(): Promise<PageAiCacheContents>;
getAssert(key: AssertCacheKey): Promise<AssertCacheEntryWithRunner | null>;
putAssert(entry: AssertCacheEntry): Promise<void>;
deleteAssert(key: AssertCacheKey): Promise<boolean>;
getLocate(key: LocateCacheKey): Promise<LocateCacheEntryWithRunner | null>;
putLocate(entry: LocateCacheEntry): Promise<void>;
deleteLocate(key: LocateCacheKey): Promise<boolean>;
private ensureCacheFileExists;
private loadCacheModule;
private readCacheFile;
private writeCacheFile;
private withCacheLock;
}
/**
* Lightweight in-memory cache implementation that stays within the current
* process. Useful for unit tests that want deterministic cache behaviour
* without touching the filesystem.
*/
export declare class InMemoryPageAiCache implements PageAiCache {
private cache;
private assertions;
private locators;
constructor(initialContents?: PageAiCacheEntry[] | PageAiCacheContents);
get(key: PageAiCacheKey): Promise<PageAiCacheEntryWithRunner | null>;
put(entry: PageAiCacheEntry): Promise<void>;
delete(key: PageAiCacheKey): Promise<boolean>;
snapshot(): Promise<PageAiCacheContents>;
getAssert(key: AssertCacheKey): Promise<AssertCacheEntryWithRunner | null>;
putAssert(entry: AssertCacheEntry): Promise<void>;
deleteAssert(key: AssertCacheKey): Promise<boolean>;
getLocate(key: LocateCacheKey): Promise<LocateCacheEntryWithRunner | null>;
putLocate(entry: LocateCacheEntry): Promise<void>;
deleteLocate(key: LocateCacheKey): Promise<boolean>;
}
//# sourceMappingURL=cache.d.ts.map