SearSuite
← All packages

@searsuite/sear-foundation-platform

Host platforms

Platform is the injected contract for timing, events, view offsets, identifiers, and diagnostics. Reusable packages depend on this contract so the same editor state and command logic can run in different hosts. BrowserPlatform and HeadlessPlatform are concrete choices for their respective environments.

Use when: assembling an editor for a host or implementing a new host adapter. Supply one Platform instance to the editor-local composition root. Event listeners and timers acquired through it must be released when the editor is destroyed; a child editor must not dispose services borrowed from its parent.

File downloads, web requests, and XML evaluation are separate capabilities with abstract contracts and concrete Web or headless implementations. A feature receives the capability it needs; it does not read browser globals or choose the application's credentials, transport, and file-saving policy.

FileDownload illustrates the relationship: an export feature prepares data, while the host-provided adapter decides how a file is saved. A headless host can use an unavailable implementation when saving is intentionally unsupported. The document state does not change merely because a host performs this effect.

classPlatform
constructorPlatform(): Platform
propertyreadonly symbol: symbolstatic

DI token for resolving Platform.

methodaddEventListener(target: unknown, type: string, listener: (event: unknown): void, options?: PlatformEventListenerOptions): (): void

Adds a platform event listener and returns its disposer.

methodcancelAnimationFrame(handle: number): void

Cancels a previously scheduled host animation frame.

methodclearInterval(handle: number): void

Cancels a repeating host timer.

methodclearTimeout(handle: number): void

Cancels a one-shot host timer.

methodcreateId(prefix?: string): string

Creates a process- or session-unique identifier for runtime protocols.

methodcurrentDateTime(): number

Returns the host wall-clock time as Unix milliseconds.

methodnow(): number

Returns the host's monotonic time in milliseconds.

methodobserveResize(target: unknown, callback: (size: { height: number; width: number }): void): (): void

Observes the CSS-pixel size of a platform render target.

methodqueueMicrotask(callback: (): void): void

Schedules a callback in the host microtask queue.

methodreadViewOffset(target: unknown): PlatformViewOffset

Reads a render target's offset in host view coordinates.

methodrequestAnimationFrame(callback: PlatformFrameRequestCallback): number

Schedules a callback for the next host animation frame.

methodsetInterval(callback: (): void, ms: number): number

Updates the interval.

methodsetTimeout(callback: (): void, ms: number): number

Updates the timeout.

methodtoLowerCase(value: string): string

Converts text to lowercase without consulting the host's locale.

methodwarn(message: string, ...details: unknown[]): void

Reports a non-fatal platform warning.

classBrowserPlatform
class BrowserPlatform extends Platform

Browser platform implementation that delegates to window / performance / queueMicrotask global APIs.

Instantiate only in browser environments. Other platforms such as Node, mini apps, and React Native should provide their own Platform implementations.

constructorBrowserPlatform(): BrowserPlatform
propertyreadonly symbol: symbolstatic

DI token for resolving BrowserPlatform.

methodaddEventListener(target: unknown, type: string, listener: (event: unknown): void, options?: PlatformEventListenerOptions): (): void

Registers a host event listener and returns an idempotent disposer.

methodcancelAnimationFrame(handle: number): void

Cancels a previously scheduled host animation frame.

methodclearInterval(handle: number): void

Cancels a repeating host timer.

methodclearTimeout(handle: number): void

Cancels a one-shot host timer.

methodcreateId(prefix?: string): string

Creates a Web-platform client/runtime identifier.

methodcurrentDateTime(): number

Returns the host wall-clock time as Unix milliseconds.

methodnow(): number

Returns the host's monotonic time in milliseconds.

methodobserveResize(target: unknown, callback: (size: { height: number; width: number }): void): (): void

Observes host-view size changes and returns an idempotent disposer.

methodqueueMicrotask(callback: (): void): void

Schedules a callback in the host microtask queue.

methodreadViewOffset(target: unknown): PlatformViewOffset

Reads an element's document-relative viewport offset.

methodrequestAnimationFrame(callback: PlatformFrameRequestCallback): number

Schedules a callback for the next host animation frame.

methodsetInterval(callback: (): void, ms: number): number

Updates the interval.

methodsetTimeout(callback: (): void, ms: number): number

Updates the timeout.

methodwarn(message: string, ...details: unknown[]): void

Reports a non-fatal diagnostic through the host warning channel.

Inherited members 1

Inherited from Platform.

classHeadlessPlatform
class HeadlessPlatform extends Platform

Platform adapter for Node and other environments without a UI surface.

constructorHeadlessPlatform(): HeadlessPlatform
propertyreadonly symbol: symbolstatic

DI token for resolving HeadlessPlatform.

methodaddEventListener(_target: unknown, _type: string, _listener: (event: unknown): void): (): void

Registers a host event listener and returns an idempotent disposer.

methodcancelAnimationFrame(handle: number): void

Cancels a previously scheduled host animation frame.

methodclearInterval(handle: number): void

Cancels a repeating host timer.

methodclearTimeout(handle: number): void

Cancels a one-shot host timer.

methodcreateId(prefix?: string): string

Creates a deterministic process-local runtime identifier.

methodcurrentDateTime(): number

Returns the host wall-clock time as Unix milliseconds.

methodnow(): number

Returns the host's monotonic time in milliseconds.

methodobserveResize(_target: unknown, _callback: (size: { height: number; width: number }): void): (): void

Observes host-view size changes and returns an idempotent disposer.

methodqueueMicrotask(callback: (): void): void

Schedules a callback in the host microtask queue.

methodreadViewOffset(_target: unknown): PlatformViewOffset

Headless targets have no host-space offset.

methodrequestAnimationFrame(callback: PlatformFrameRequestCallback): number

Schedules a callback for the next host animation frame.

methodsetInterval(callback: (): void, ms: number): number

Updates the interval.

methodsetTimeout(callback: (): void, ms: number): number

Updates the timeout.

methodwarn(message: string, ...details: unknown[]): void

Reports a non-fatal diagnostic through the host warning channel.

Inherited members 1

Inherited from Platform.

interfacePlatformEventListenerOptions

Event-routing options supported by host adapters.

propertyreadonly capture?: boolean

Receives propagated events before target handlers can consume them.

typePlatformFrameRequestCallback
type PlatformFrameRequestCallback = (time: number): void

Platform abstraction that narrows browser-specific APIs into injectable capabilities.

Each platform (browser, Node, mini app, React Native, etc.) provides its own implementation. Application code injects Platform through DI instead of calling global APIs directly.

variablePlatformEventName
PlatformEventName: { Click: "click"; MouseDown: "mousedown"; MouseMove: "mousemove"; MouseUp: "mouseup" }

Canonical event names understood by platform event adapters.

Network services

classHeadlessWebServiceClient
class HeadlessWebServiceClient extends WebServiceClient

Node/headless fetch adapter. Hosts remain responsible for SSRF and network policy.

constructorHeadlessWebServiceClient(): HeadlessWebServiceClient
propertyreadonly symbol: symbolstatic

DI token for resolving the editor-local web-service adapter.

methodrequest(url: string, options?: WebServiceRequestOptions): Promise<WebServiceResponse>

Performs one request; callers own caching, cancellation, and invalidation.

classWebFetchServiceClient
class WebFetchServiceClient extends WebServiceClient

Browser fetch adapter. CORS and host security policy remain browser-owned concerns.

constructorWebFetchServiceClient(): WebFetchServiceClient
propertyreadonly symbol: symbolstatic

DI token for resolving the editor-local web-service adapter.

methodrequest(url: string, options?: WebServiceRequestOptions): Promise<WebServiceResponse>

Performs one request; callers own caching, cancellation, and invalidation.

classWebServiceClient

Platform-neutral asynchronous HTTP boundary for service-backed formulas.

constructorWebServiceClient(): WebServiceClient
propertyreadonly symbol: symbolstatic

DI token for resolving the editor-local web-service adapter.

methodrequest(url: string, options?: WebServiceRequestOptions): Promise<WebServiceResponse>

Performs one request; callers own caching, cancellation, and invalidation.

classWebServiceError
class WebServiceError extends SearError

Public error raised by a web-service adapter.

constructorWebServiceError(message: string, details?: Readonly<Record<string, unknown>>): WebServiceError
propertyreadonly code: "WEB_SERVICE_REQUEST_FAILED"

Stable machine-readable identifier for this error category.

Inherited members 9

Inherited from SearError.

interfaceWebServiceCancellation

Host-neutral request cancellation.

propertyreadonly cancelled: boolean
methodsubscribe(listener: (): void): (): void
interfaceWebServiceResponse

Fully consumed response; platform-native response objects never escape an adapter.

propertyreadonly ok: boolean
propertyreadonly status: number
propertyreadonly text: string
typeWebServiceErrorCode
type WebServiceErrorCode = typeof WebServiceErrorCode[keyof typeof WebServiceErrorCode] WebServiceErrorCode: { RequestFailed: "WEB_SERVICE_REQUEST_FAILED" }
functionisHttpWebServiceUrl
isHttpWebServiceUrl(url: string): boolean

Validates absolute HTTP(S) URL syntax without enforcing host-owned network access policy.

XML evaluation

classWebXmlXPathEvaluator
class WebXmlXPathEvaluator extends XmlXPathEvaluator

Browser-native XML/XPath adapter backed by DOMParser and XPathEvaluator.

constructorWebXmlXPathEvaluator(): WebXmlXPathEvaluator
propertyreadonly symbol: symbolstatic

DI token for resolving the editor-local XML/XPath adapter.

Inherited members 1

Inherited from XmlXPathEvaluator.

classXmlXPathError
class XmlXPathError extends SearError

Public failure raised by XML/XPath adapters.

constructorXmlXPathError(code: XmlXPathErrorCode, message: string, details?: Readonly<Record<string, unknown>>): XmlXPathError
Inherited members 10

Inherited from SearError.

classXmlXPathEvaluator

Platform-neutral XML/XPath execution boundary used by formula adapters.

constructorXmlXPathEvaluator(): XmlXPathEvaluator
propertyreadonly symbol: symbolstatic

DI token for resolving the editor-local XML/XPath adapter.

methodevaluate(xml: string, xpath: string, options?: XmlXPathOptions): XmlXPathEvaluation

Evaluates an XPath expression against one XML document.

interfaceXmlXPathEvaluation

Result values in document order; selected nodes contribute their string values.

propertyreadonly values: readonly string[]
interfaceXmlXPathOptions

Explicit prefix bindings used by an XPath expression.

propertyreadonly namespaces?: Readonly<Record<string, string>>
typeXmlXPathErrorCode
type XmlXPathErrorCode = typeof XmlXPathErrorCode[keyof typeof XmlXPathErrorCode] XmlXPathErrorCode: { InvalidXml: "XML_INVALID"; InvalidXPath: "XPATH_INVALID"; UnsupportedResult: "XPATH_UNSUPPORTED_RESULT" }

File downloads

FileDownload lets an export feature request a download without owning browser APIs.

classFileDownload

Replaceable host capability for saving generated files.

constructorFileDownload(): FileDownload
propertyreadonly symbol: typeof symbolstatic

Token for host composition roots that register the capability through DI.

methoddestroy(): void

Releases pending host resources, idempotently.

methoddownload(request: FileDownloadRequest): void

Initiates one host file save.

classUnavailableFileDownload
class UnavailableFileDownload extends FileDownload

Explicit fallback for hosts that do not provide file saving.

constructorUnavailableFileDownload(): UnavailableFileDownload
methoddestroy(): void

Releases pending host resources, idempotently.

methoddownload(_request: FileDownloadRequest): void

Initiates one host file save.

Inherited members 1

Inherited from FileDownload.

classWebFileDownload
class WebFileDownload extends FileDownload

Web file-save adapter; native elements and object URLs never enter the neutral contract.

constructorWebFileDownload(platform: Platform): WebFileDownload

Receives the owning host's timer adapter explicitly.

methoddestroy(): void

Cancels pending release callbacks and revokes every retained object URL.

methoddownload(request: FileDownloadRequest): void

Initiates a native file save and tracks its delayed resource release.

Inherited members 1

Inherited from FileDownload.

interfaceFileDownloadRequest

Host-neutral request to save an in-memory file.

propertyreadonly data: string | Uint8Array<ArrayBufferLike>

Text or binary file contents.

propertyreadonly mediaType: string

File media type.

propertyreadonly name: string

Suggested file name.