# @embedpdf/core — ./testing Gate [InterfaceDeclaration]: export interface Gate{ readonly engine: Engine; readonly held: GatedChange[]; holding: boolean; release(): Promise; refuse(error: unknown): void; } GatedChange [InterfaceDeclaration]: export interface GatedChange{ readonly change: Change; readonly options: unknown; resolve(value: unknown): void; reject(error: unknown): void; } LOCAL_ENGINE_BRAND [VariableDeclaration] (from packages/engine/core/src/engine/localEngineBrand.ts): LOCAL_ENGINE_BRAND: unique symbol = Symbol.for('@embedpdf/engine/local') ManualClock [InterfaceDeclaration]: export interface ManualClock{ readonly clock: HostClock; readonly now: number; readonly pending:{ readonly timers: number; readonly frames: number} ; advance(ms: number): void; frame(timeMs?: number): void; } TestContext [InterfaceDeclaration]: export interface TestContext extends PluginContext{ readonly capabilities: Map, unknown>; subscribe(listener: () => void): Unsubscribe; connect(instance:{ api: C; connect?: () => void} ): C; emitDocumentEvent(event: DocumentEvent): void; settle(signal?: AbortSignal): Promise; download(read: () => Promise): Promise; print(print: () => Promise): Promise; destroy(): Promise; } TestContextOptions [InterfaceDeclaration]: export interface TestContextOptions{ readonly id?: string; readonly state?: S; readonly settings?: SettingsDeclaration; readonly pages?: readonly TestPage[]; readonly pageLabels?: readonly PageLabelSection[]; readonly documentId?: string; readonly capabilities?: ReadonlyArray, unknown]>; readonly doc?: Partial | null; readonly engine?: Partial; readonly clock?: HostClock; readonly measurer?: HostTextMeasurer; } TestPage [InterfaceDeclaration]: export interface TestPage{ readonly ref: PageRef; readonly size?:{ readonly width: number; readonly height: number} ; readonly crop?: PdfRect; readonly rotation?: PageLayout['rotation']; readonly userUnit?: number; readonly label?: string | null; readonly tabOrder?: PageLayout['tabOrder']; readonly viewports?: PageLayout['viewports']; } createTestCommandContext [FunctionDeclaration]: export function createTestCommandContext( capabilities: Iterable, unknown]> = [], options:{ documentId?: string | null; appState?: unknown} ={ } , ): CommandContext{ const byToken = new Map, unknown>(capabilities); const tryGet = (token: CapabilityToken): C | null => (byToken.get(token as CapabilityToken) as C | undefined) ?? null; return{ documentId: options.documentId === undefined ? 'doc' : options.documentId, appState: options.appState, tryGet, get: (token: CapabilityToken): C =>{ const capability = tryGet(token); if (!capability) throw new Error(`no ${ token.name} `); return capability; } , } ; } createTestContext [FunctionDeclaration]: export function createTestContext( options: TestContextOptions ={ } , ): TestContext{ const id = options.id ?? 'test'; const documentId = options.documentId ?? 'doc'; const report = (error: unknown) => console.error(`[${ id} ]`, error); const store = createStore(report); const instanceId = `${ documentId} :${ id} `; const lease = store.lease(id, options.state as S, instanceId); const cleanups: Array<() => void | Promise> = []; const lifetime = new AbortController(); const settleFlushes = new Set(); const downloadWraps: DownloadWrap[] = []; const printWraps: PrintWrap[] = []; const pages = (options.pages ?? []).map(layoutOf); const capabilities = new Map, unknown>(options.capabilities ?? []); const documentEvents = createEventHook(report); const isRealHandle = options.doc != null && Object.getPrototypeOf(options.doc) !== Object.prototype; const doc = options.doc === null ? null : isRealHandle ? (options.doc as DocumentHandle) : fakeDocument({ id: documentId, events:{ subscribe: documentEvents.on, on: (type: DocumentEvent['type'], listener: (event: DocumentEvent) => void) => subscribeToType(documentEvents.on, type, listener), lastServerSequence: () => null, } , security:{ allows: () => true, allowsAnnotation: () => true, allowsField: () => true} , ...options.doc, } ); const requireDoc = (): DocumentHandle =>{ if (!doc) throw new PluginError('not-ready', id, 'the test context has no document'); return doc; } ; const changes = createDocumentChanges({ handle: () => doc, notify: () =>{ showPages(); store.notify(); } , report, } ); settleFlushes.add(() => changes.settle()); cleanups.push(() => changes.close()); const pageView = createPageView({ changes, report} ); pageView.setEnginePages({ pages, labels: options.pageLabels ?? []} ); pageView.refresh(); const bursts = createBurstGate(store); const mirrors: MirrorController[] = []; const mirrorEnvironment = (): MirrorEnvironment => ({ doc: requireDoc(), changes, notify: store.notify, lifetime: lifetime.signal, cell(name, initial){ const cell = store.lease(`${ id} /${ name} `, initial, instanceId); lifetime.signal.addEventListener('abort', () => cell.revoke(), { once: true} ); return cell; } , onDocumentEvent(listener){ cleanups.push(requireDoc().events.subscribe(listener)); } , pages: pageView, report, } ); let meta: DocumentMeta ={ id: documentId, instanceId, pageCount: pages.length, pages: pageView.current().pages, pageLabels: pageView.current().labels, pendingPages: NO_PENDING_PAGES, pagesSequence: 1, renderPolicy:{ kind: 'continuous'} , hasUnsavedChanges: false, } ; function showPages(): boolean{ const view = pageView.refresh(); if (!view) return false; const moved = view.pages !== meta.pages; meta ={ ...meta, pageCount: view.pages.length, pages: view.pages, pageLabels: view.labels, pendingPages: view.pending, pagesSequence: moved ? meta.pagesSequence + 1 : meta.pagesSequence, } ; return true; } if (doc){ cleanups.push( doc.events.subscribe((event) =>{ const layout = layoutFromEvent(event); if (layout) pageView.setEnginePages(layout); pageView.fold(event); if (showPages()) store.notify(); } ), ); } if (!capabilities.has(DocumentsToken as CapabilityToken)){ capabilities.set( DocumentsToken as CapabilityToken, testDocuments(() => meta), ); } const notFound = (ref: PageRef) => new PluginError('not-found', id, `page ${ ref.objectNumber} is not in this document`); const resolve = (token: CapabilityToken): T | null => capabilities.has(token as CapabilityToken) ? (capabilities.get(token as CapabilityToken) as T) : null; const require = (token: CapabilityToken): T =>{ const capability = resolve(token); if (capability === null){ throw new PluginError('not-found', id, `no capability for ${ token.name} in the test context`); } return capability; } ; const queues = new Map(); const lanes = new Map(); const settingsStore = options.settings ? createSettingsStore(options.settings, store.notify, report) : null; if (settingsStore) cleanups.push(() => settingsStore.destroy()); const settings = settingsStore?.forInstance((teardown) => cleanups.push(teardown)) ?? null; const context: TestContext ={ id, instanceId: meta.instanceId, engine: (options.engine ??{ } ) as Engine, documentId, get doc(){ return doc as DocumentHandle; } , documentHandle: () => doc, subscribe: store.subscribe, state:{ get: () => lease.read(), update: (transition, ...args) =>{ lease.write(transition(lease.read(), ...args)); } , onChange: lease.onChange, } , settings: () =>{ if (!settings) throw new Error(`[${ id} ] the test context declares no settings`); return settings; } , notify: store.notify, storeChangeCount: store.changeCount, watch: (select, handler, isEqual = Object.is) =>{ let previous = select(); const off = store.subscribe(() =>{ const next = select(); if (isEqual(previous, next)) return; const prior = previous; previous = next; handler(next, prior); } ); cleanups.push(off); return off; } , mirror: (spec) =>{ const controller = createMirror(spec, mirrorEnvironment()); mirrors.push(controller as MirrorController); return controller.mirror; } , pageMirror: (spec) => createPageMirror(spec, mirrorEnvironment()), changes: changes.forPlugin(id), document: () => meta, get: require, tryGet: resolve, forDocument: (token) => require(token), tryForDocument: (token) => resolve(token), cleanup: (fn) =>{ cleanups.push(fn); } , clock: instanceClock(options.clock ?? timerClock, lifetime.signal), measurer: options.measurer ? instanceMeasurer(options.measurer, lifetime.signal) : null, onSettle: (flush) =>{ settleFlushes.add(flush); cleanups.push(() =>{ settleFlushes.delete(flush); } ); } , aroundDownload: (wrap) =>{ downloadWraps.push(wrap); cleanups.push(() =>{ const index = downloadWraps.indexOf(wrap); if (index >= 0) downloadWraps.splice(index, 1); } ); } , aroundPrint: (wrap) =>{ printWraps.push(wrap); cleanups.push(() =>{ const index = printWraps.indexOf(wrap); if (index >= 0) printWraps.splice(index, 1); } ); } , events:{ source: () =>{ const hook = createEventHook((error) => console.error(`[${ id} ] listener failed:`, error), ); cleanups.push(() => hook.destroy()); return hook; } , } , listen: (source, listener) =>{ const off = typeof source === 'function' ? source(listener) : source.subscribe(listener); cleanups.push(off); } , waitFor: (predicate, waitOptions?: OperationOptions) => new Promise((resolveWait, reject) =>{ if (predicate()) return resolveWait(); const off = context.subscribe(() =>{ if (!predicate()) return; off(); resolveWait(); } ); waitOptions?.signal?.addEventListener('abort', () =>{ off(); reject(new PluginError('operation-cancelled', id, 'waitFor cancelled')); } ); } ), serialQueue: (key = 'default') =>{ let queue = queues.get(key); if (!queue){ queue = createSerialQueue(id); queues.set(key, queue); } return queue; } , latest: (key) =>{ let lane = lanes.get(key); if (!lane){ lane = createLatestLane(lifetime.signal, id, key); lanes.set(key, lane); } return lane; } , acquire: async (get, dispose) =>{ const resource = await get(lifetime.signal); if (lifetime.signal.aborted){ await dispose(resource); throw new PluginError('instance-closed', id, 'acquired after close'); } cleanups.push(() => dispose(resource)); return resource; } , assertPageRef: (ref) =>{ if (!meta.pages.some((pageInfo) => pageRefsEqual(pageInfo.ref, ref))) throw notFound(ref); } , getPage: (page) => findPage(meta.pages, page), pageOf: (page) => pageOf(meta.pages, page, id), allows: (permission) => sessionAllows(requireDoc().security, permission), assertAllowed: (permission, operation) =>{ if (!sessionAllows(requireDoc().security, permission)){ throw permissionDenied(id, permission, operation); } } , allowsField: (action, field) => requireDoc().security.allowsField(action, { groupId: field.groupId} ), assertAllowedField: (action, field, operation) =>{ if (!requireDoc().security.allowsField(action, { groupId: field.groupId} )){ throw fieldPermissionDenied(id, action, field, operation); } } , cancellable: (signal, task) => cancellable(id, signal, task), capabilities, connect: (instance) =>{ instance.connect?.(); for (const mirror of mirrors.splice(0)) mirror.start(); return instance.api; } , emitDocumentEvent: (event) =>{ bursts.first(event); documentEvents.emit(event); bursts.last(event); } , settle: (signal) => settle(settleFlushes, [signal, lifetime.signal], report), download: (read) => runWrapped(downloadWraps, read), print: (print) => runWrapped(printWraps, print), destroy: async () =>{ lifetime.abort(); for (const fn of cleanups.splice(0).reverse()) await fn(); } , } ; return context; } gate [FunctionDeclaration]: export function gate(engine: Engine): Gate{ const held: GatedChange[] = []; let inner: DocumentHandle | null = null; const state: Gate ={ engine: null as unknown as Engine, held, holding: false, async release(){ const next = held.shift(); if (!next || !inner) throw new Error('nothing is held'); await inner.apply(next.change, next.options as never).then(next.resolve, next.reject); } , refuse(error){ const next = held.shift(); if (!next) throw new Error('nothing is held'); next.reject(error); } , } ; const wrap = (doc: DocumentHandle): DocumentHandle => new Proxy(doc, { get(target, prop){ if (prop === 'apply'){ return (change: Change, options: unknown) => state.holding ? new Promise((resolve, reject) => held.push({ change, options, resolve, reject} )) : target.apply(change, options as never); } const value = Reflect.get(target, prop, target) as unknown; if (prop === 'with' && typeof value === 'function'){ return (...args: unknown[]) => wrap(value.apply(target, args) as DocumentHandle); } return typeof value === 'function' ? value.bind(target) : value; } , } ); (state as{ engine: Engine} ).engine = new Proxy(engine, { get(target, prop){ if (prop === 'open'){ return async (...args: Parameters) =>{ const doc = await target.open(...args); inner = doc; return wrap(doc); } ; } const value = Reflect.get(target, prop, target) as unknown; return typeof value === 'function' ? value.bind(target) : value; } , } ); return state; } manualClock [FunctionDeclaration]: export function manualClock(options:{ frames?: boolean} ={ } ): ManualClock{ let now = 0; let order = 0; const timers = new Map void} >(); const frames = new Map void>(); const nextDue = (until: number): number | undefined =>{ let found: number | undefined; for (const [id, timer] of timers){ if (timer.due > until) continue; if (found === undefined || timer.due < timers.get(found)!.due) found = id; } return found; } ; const advanceTo = (target: number): void =>{ if (target < now) throw new Error(`manualClock: time does not go back (${ target} < ${ now} )`); for (let id = nextDue(target); id !== undefined; id = nextDue(target)){ const timer = timers.get(id)!; timers.delete(id); now = timer.due; timer.run(); } now = target; } ; const clock: HostClock ={ now: () => now, after(ms, run): Cancel{ const id = ++order; timers.set(id, { due: now + Math.max(0, ms), run} ); return () => void timers.delete(id); } , ...(options.frames === false ?{ } :{ nextFrame(run: (timeMs: number) => void): Cancel{ const id = ++order; frames.set(id, run); return () => void frames.delete(id); } , } ), } ; return{ clock, get now(){ return now; } , get pending(){ return{ timers: timers.size, frames: frames.size} ; } , advance: (ms) => advanceTo(now + ms), frame(timeMs = now){ advanceTo(timeMs); const due = [...frames.values()]; frames.clear(); for (const run of due) run(now); } , } ; }