API reference

@searsuite/sear-foundation-platform

Injectable timing, events, view geometry, identifiers, and host diagnostics.

Search exports in this package

28 exportsderived from source

Concept 1

Supply an environment through Platform

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.

Concept 2

Keep host effects at the boundary

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.

classBrowserPlatform source ↗

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.

constructorconstructor

BrowserPlatform(): BrowserPlatform

propertysymbolstatic

readonly symbol: symbol

DI token for resolving BrowserPlatform.

methodaddEventListener

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

Registers a host event listener and returns an idempotent disposer.

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

methodcancelAnimationFrame

cancelAnimationFrame(handle: number): void

Cancels a previously scheduled host animation frame.

handle: number

methodclearInterval

clearInterval(handle: number): void

Cancels a repeating host timer.

handle: number

methodclearTimeout

clearTimeout(handle: number): void

Cancels a one-shot host timer.

handle: number

methodcreateId

createId(prefix?: string): string

Creates a Web-platform client/runtime identifier.

prefix: string

methodcurrentDateTime

currentDateTime(): number

Returns the host wall-clock time as Unix milliseconds.

methodnow

now(): number

Returns the host's monotonic time in milliseconds.

methodobserveResize

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

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

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

methodqueueMicrotask

queueMicrotask(callback: (): void): void

Schedules a callback in the host microtask queue.

callback: (): void

methodreadViewOffset

readViewOffset(target: unknown): PlatformViewOffset

Reads an element's document-relative viewport offset.

target: unknown

methodrequestAnimationFrame

requestAnimationFrame(callback: PlatformFrameRequestCallback): number

Schedules a callback for the next host animation frame.

callback: PlatformFrameRequestCallback

methodsetInterval

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

Updates the interval.

callback: (): void
ms: number

methodsetTimeout

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

Updates the timeout.

callback: (): void
ms: number

methodwarn

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

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

message: string
details: unknown[]

Inherited members 1

Inherited from Platform.

toLowerCase

classFileDownload source ↗

class FileDownload

Replaceable host capability for saving generated files.

constructorconstructor

FileDownload(): FileDownload

propertysymbolstatic

readonly symbol: typeof symbol

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

methoddestroy

destroy(): void

Releases pending host resources, idempotently.

methoddownload

download(request: FileDownloadRequest): void

Initiates one host file save.

request: FileDownloadRequest

classHeadlessPlatform source ↗

class HeadlessPlatform extends Platform

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

constructorconstructor

HeadlessPlatform(): HeadlessPlatform

propertysymbolstatic

readonly symbol: symbol

DI token for resolving HeadlessPlatform.

methodaddEventListener

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

Registers a host event listener and returns an idempotent disposer.

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

methodcancelAnimationFrame

cancelAnimationFrame(handle: number): void

Cancels a previously scheduled host animation frame.

handle: number

methodclearInterval

clearInterval(handle: number): void

Cancels a repeating host timer.

handle: number

methodclearTimeout

clearTimeout(handle: number): void

Cancels a one-shot host timer.

handle: number

methodcreateId

createId(prefix?: string): string

Creates a deterministic process-local runtime identifier.

prefix: string

methodcurrentDateTime

currentDateTime(): number

Returns the host wall-clock time as Unix milliseconds.

methodnow

now(): number

Returns the host's monotonic time in milliseconds.

methodobserveResize

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

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

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

methodqueueMicrotask

queueMicrotask(callback: (): void): void

Schedules a callback in the host microtask queue.

callback: (): void

methodreadViewOffset

readViewOffset(_target: unknown): PlatformViewOffset

Headless targets have no host-space offset.

_target: unknown

methodrequestAnimationFrame

requestAnimationFrame(callback: PlatformFrameRequestCallback): number

Schedules a callback for the next host animation frame.

callback: PlatformFrameRequestCallback

methodsetInterval

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

Updates the interval.

callback: (): void
ms: number

methodsetTimeout

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

Updates the timeout.

callback: (): void
ms: number

methodwarn

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

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

message: string
details: unknown[]

Inherited members 1

Inherited from Platform.

toLowerCase

classHeadlessWebServiceClient source ↗

class HeadlessWebServiceClient extends WebServiceClient

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

constructorconstructor

HeadlessWebServiceClient(): HeadlessWebServiceClient

propertysymbolstatic

readonly symbol: symbol

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

methodrequest

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

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

url: string
options: WebServiceRequestOptions

classPlatform source ↗

class Platform

constructorconstructor

Platform(): Platform

propertysymbolstatic

readonly symbol: symbol

DI token for resolving Platform.

methodaddEventListener

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

Adds a platform event listener and returns its disposer.

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

methodcancelAnimationFrame

cancelAnimationFrame(handle: number): void

Cancels a previously scheduled host animation frame.

handle: number

methodclearInterval

clearInterval(handle: number): void

Cancels a repeating host timer.

handle: number

methodclearTimeout

clearTimeout(handle: number): void

Cancels a one-shot host timer.

handle: number

methodcreateId

createId(prefix?: string): string

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

prefix: string

methodcurrentDateTime

currentDateTime(): number

Returns the host wall-clock time as Unix milliseconds.

methodnow

now(): number

Returns the host's monotonic time in milliseconds.

methodobserveResize

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

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

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

methodqueueMicrotask

queueMicrotask(callback: (): void): void

Schedules a callback in the host microtask queue.

callback: (): void

methodreadViewOffset

readViewOffset(target: unknown): PlatformViewOffset

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

target: unknown

methodrequestAnimationFrame

requestAnimationFrame(callback: PlatformFrameRequestCallback): number

Schedules a callback for the next host animation frame.

callback: PlatformFrameRequestCallback

methodsetInterval

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

Updates the interval.

callback: (): void
ms: number

methodsetTimeout

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

Updates the timeout.

callback: (): void
ms: number

methodtoLowerCase

toLowerCase(value: string): string

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

value: string

methodwarn

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

Reports a non-fatal platform warning.

message: string
details: unknown[]

classUnavailableFileDownload source ↗

class UnavailableFileDownload extends FileDownload

Explicit fallback for hosts that do not provide file saving.

constructorconstructor

UnavailableFileDownload(): UnavailableFileDownload

methoddestroy

destroy(): void

Releases pending host resources, idempotently.

methoddownload

download(_request: FileDownloadRequest): void

Initiates one host file save.

_request: FileDownloadRequest

Inherited members 1

Inherited from FileDownload.

symbol

classWebFetchServiceClient source ↗

class WebFetchServiceClient extends WebServiceClient

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

constructorconstructor

WebFetchServiceClient(): WebFetchServiceClient

propertysymbolstatic

readonly symbol: symbol

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

methodrequest

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

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

url: string
options: WebServiceRequestOptions

classWebFileDownload source ↗

class WebFileDownload extends FileDownload

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

constructorconstructor

WebFileDownload(platform: Platform): WebFileDownload

Receives the owning host's timer adapter explicitly.

platform: Platform

methoddestroy

destroy(): void

Cancels pending release callbacks and revokes every retained object URL.

methoddownload

download(request: FileDownloadRequest): void

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

request: FileDownloadRequest

Inherited members 1

Inherited from FileDownload.

symbol

classWebServiceClient source ↗

class WebServiceClient

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

constructorconstructor

WebServiceClient(): WebServiceClient

propertysymbolstatic

readonly symbol: symbol

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

methodrequest

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

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

url: string
options: WebServiceRequestOptions

classWebServiceError source ↗

class WebServiceError extends SearError

Public error raised by a web-service adapter.

constructorconstructor

WebServiceError(message: string, details?: Readonly<Record<string, unknown>>): WebServiceError

message: string
details: Readonly<Record<string, unknown>>

propertycode

readonly code: "WEB_SERVICE_REQUEST_FAILED"

Stable machine-readable identifier for this error category.

Inherited members 9

Inherited from SearError.

classWebXmlXPathEvaluator source ↗

class WebXmlXPathEvaluator extends XmlXPathEvaluator

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

constructorconstructor

WebXmlXPathEvaluator(): WebXmlXPathEvaluator

propertysymbolstatic

readonly symbol: symbol

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

Inherited members 1

Inherited from XmlXPathEvaluator.

evaluate

classXmlXPathError source ↗

class XmlXPathError extends SearError

Public failure raised by XML/XPath adapters.

constructorconstructor

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

code: XmlXPathErrorCode
message: string
details: Readonly<Record<string, unknown>>

Inherited members 10

Inherited from SearError.

classXmlXPathEvaluator source ↗

class XmlXPathEvaluator

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

constructorconstructor

XmlXPathEvaluator(): XmlXPathEvaluator

propertysymbolstatic

readonly symbol: symbol

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

methodevaluate

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

Evaluates an XPath expression against one XML document.

xml: string
xpath: string
options: XmlXPathOptions

interfaceFileDownloadRequest source ↗

interface FileDownloadRequest

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

propertydata

readonly data: string | Uint8Array<ArrayBufferLike>

Text or binary file contents.

propertymediaType

readonly mediaType: string

File media type.

propertyname

readonly name: string

Suggested file name.

interfacePlatformEventListenerOptions source ↗

interface PlatformEventListenerOptions

Event-routing options supported by host adapters.

propertycapture

readonly capture?: boolean

Receives propagated events before target handlers can consume them.

interfacePlatformViewOffset source ↗

interface PlatformViewOffset

propertyx

readonly x: number

propertyy

readonly y: number

interfaceWebServiceCancellation source ↗

interface WebServiceCancellation

Host-neutral request cancellation.

propertycancelled

readonly cancelled: boolean

interfaceWebServiceRequestOptions source ↗

interface WebServiceRequestOptions

propertycancellation

readonly cancellation?: WebServiceCancellation

propertyheaders

readonly headers?: Readonly<Record<string, string>>

interfaceWebServiceResponse source ↗

interface WebServiceResponse

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

propertyok

readonly ok: boolean

propertystatus

readonly status: number

propertytext

readonly text: string

interfaceXmlXPathEvaluation source ↗

interface XmlXPathEvaluation

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

propertyvalues

readonly values: readonly string[]

interfaceXmlXPathOptions source ↗

interface XmlXPathOptions

Explicit prefix bindings used by an XPath expression.

propertynamespaces

readonly namespaces?: Readonly<Record<string, string>>

typePlatformFrameRequestCallback source ↗

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.

typeWebServiceErrorCode source ↗

type WebServiceErrorCode = typeof WebServiceErrorCode[keyof typeof WebServiceErrorCode]

typeXmlXPathErrorCode source ↗

type XmlXPathErrorCode = typeof XmlXPathErrorCode[keyof typeof XmlXPathErrorCode]

variablePlatformEventName source ↗

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

Canonical event names understood by platform event adapters.

variableWebServiceErrorCode source ↗

WebServiceErrorCode: { RequestFailed: "WEB_SERVICE_REQUEST_FAILED" }

variableXmlXPathErrorCode source ↗

XmlXPathErrorCode: { InvalidXml: "XML_INVALID"; InvalidXPath: "XPATH_INVALID"; UnsupportedResult: "XPATH_UNSUPPORTED_RESULT" }

functionisHttpWebServiceUrl source ↗

isHttpWebServiceUrl(url: string): boolean

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

url: string