From b0274aef56a4bd2e95abf512e57ddd54afcfb627 Mon Sep 17 00:00:00 2001 From: Jure Rotar Date: Wed, 21 Jan 2026 12:52:51 +0100 Subject: [PATCH] feat: added Worker1 Promiser types --- src/index.d.ts | 231 ++++++++++++++++++++++++++++++++++++++++++++++--- src/index.js | 5 +- 2 files changed, 222 insertions(+), 14 deletions(-) diff --git a/src/index.d.ts b/src/index.d.ts index 015e7bc..7361991 100644 --- a/src/index.d.ts +++ b/src/index.d.ts @@ -485,14 +485,16 @@ declare type ExecOptions = { * but clients must also refrain from using any lower-level (C-style) APIs * which might modify the statement. */ - callback?: ( - row: - | SqlValue[] - | { [columnName: string]: SqlValue } - | PreparedStatement - | SqlValue, - stmt: PreparedStatement, - ) => void | false; + callback?: + | (( + row: + | SqlValue[] + | { [columnName: string]: SqlValue } + | PreparedStatement + | SqlValue, + stmt: PreparedStatement, + ) => void | false) + | string; /** * If this is an array, the column names of the result set are stored in this @@ -744,7 +746,7 @@ declare type WindowFunctionOptions = FunctionOptions & { * using `sqlite3_open` or equivalent. * * @example - * ```typescript + * ```ts * const db = new sqlite3.DB(); * try { * db.exec([ @@ -1570,6 +1572,206 @@ declare class SQLite3Error extends Error { /** A pointer to a location in WASM heap memory. */ declare type WasmPointer = number; +/** Common envelope for all Worker API #1 messages. */ +interface Worker1MessageBusEnvelope { + /** One of: 'open', 'close', 'exec', 'export', 'config-get' */ + type: string; + + /** + * Optional arbitrary value. The worker will copy it as-is into response + * messages to assist in client-side dispatching. + */ + messageId?: any; + + /** + * A db identifier string (returned by 'open') which tells the operation which + * database instance to work on. If not provided, the first-opened db is + * used. + */ + dbId?: string; +} + +/** Worker API #1 input message envelope. */ +interface Worker1InputEnvelope< + T extends string, + Args = any, +> extends Worker1MessageBusEnvelope { + type: T; + args: Args; +} + +/** Worker API #1 output message envelope. */ +interface Worker1OutputEnvelope< + T extends string, + Result = any, +> extends Worker1MessageBusEnvelope { + type: T; + result: Result; +} + +/** Worker API #1 error response result. */ +interface Worker1ErrorResult { + /** Type of the triggering operation: 'open', 'close', ... */ + operation: string; + /** Error message text */ + message: string; + /** The ErrorClass.name property from the thrown exception. */ + errorClass: string; + /** The message object which triggered the error. */ + input: any; + /** If available, a stack trace array. */ + stack?: string[]; +} + +/** Worker API #1 error response envelope. */ +interface Worker1ErrorEnvelope extends Worker1MessageBusEnvelope { + type: 'error'; + result: Worker1ErrorResult; +} + +/** Worker API #1 'open' arguments. */ +interface Worker1OpenArgs { + /** The db filename. */ + filename?: string; + /** Sqlite3_vfs name. */ + vfs?: string; +} + +/** Worker API #1 'open' result. */ +interface Worker1OpenResult { + /** Db filename, possibly differing from the input. */ + filename: string; + /** Opaque ID value for the opened db. */ + dbId: string; + /** True if the given filename resides in the known-persistent storage. */ + persistent: boolean; + /** Name of the VFS the "main" db is using. */ + vfs: string; +} + +/** Worker API #1 'close' arguments. */ +interface Worker1CloseArgs { + /** If truthy, the database will be unlinked (deleted) after closing it. */ + unlink?: boolean; +} + +/** Worker API #1 'close' result. */ +interface Worker1CloseResult { + /** Filename of closed db, or undefined if no db was closed. */ + filename?: string; +} + +/** Worker API #1 'exec' result. */ +interface Worker1ExecResult extends ExecOptions { + /** Number of changes made by the SQL. (v3.43+) */ + changeCount?: number | bigint; + /** Result of sqlite3_last_insert_rowid(). (v3.50.0+) */ + lastInsertRowId?: bigint; +} + +/** Worker API #1 'export' result. */ +interface Worker1ExportResult { + /** The exported database as a byte array. */ + byteArray: Uint8Array; + /** The db filename. */ + filename: string; + /** "application/x-sqlite3" */ + mimetype: string; +} + +/** Worker API #1 'config-get' result. */ +interface Worker1ConfigGetResult { + /** Sqlite3.version object */ + version: { + libVersion: string; + libVersionNumber: number; + sourceId: string; + downloadVersion: number; + }; + /** True if BigInt support is enabled. */ + bigIntEnabled: boolean; + /** Result of sqlite3.capi.sqlite3_js_vfs_list() */ + vfsList: string[]; +} + +/** Map of Worker API #1 operation types to their argument types. */ +interface Worker1ArgsMap { + open: Worker1OpenArgs; + close: Worker1CloseArgs | undefined; + exec: ExecOptions | string; + export: undefined; + 'config-get': undefined; +} + +/** Map of Worker API #1 operation types to their result types. */ +interface Worker1ResultMap { + open: Worker1OpenResult; + close: Worker1CloseResult; + exec: Worker1ExecResult; + export: Worker1ExportResult; + 'config-get': Worker1ConfigGetResult; +} + +/** Function type returned by Worker1PromiserFactory. */ +interface Worker1Promiser { + /** + * Sends a message to the worker and returns a Promise which resolves to the + * response message. + */ + ( + type: T, + args: Worker1ArgsMap[T], + ): Promise>; + + /** + * Sends a message to the worker and returns a Promise which resolves to the + * response message. + */ + ( + msg: Worker1InputEnvelope, + ): Promise>; +} + +/** Configuration for Worker1PromiserFactory. */ +interface Worker1PromiserConfig { + /** A Worker instance or a function which returns one. */ + worker?: Worker | (() => Worker); + + /** Callback called when the worker is ready. */ + onready?: (promiser: Worker1Promiser) => void; + + /** Callback for unhandled worker messages. */ + onunhandled?: (event: MessageEvent) => void; + + /** Optional function to generate unique message IDs. */ + generateMessageId?: (msg: any) => string; + + /** Optional debug logging function. */ + debug?: (...args: any[]) => void; + + /** Optional error logging function (undocumented). */ + onerror?: (...args: any[]) => void; +} + +/** Factory for creating Worker1Promiser instances. */ +interface Worker1PromiserFactory { + /** Creates a Worker1Promiser. */ + (config?: Worker1PromiserConfig): Worker1Promiser; + + /** Creates a Worker1Promiser from a ready callback. */ + (onready: (promiser: Worker1Promiser) => void): Worker1Promiser; + + /** Default configuration. */ + defaultConfig: Worker1PromiserConfig; + + /** V2 variant which returns a Promise that resolves to the promiser. */ + v2: { + (config?: Worker1PromiserConfig): Promise; + (onready: (promiser: Worker1Promiser) => void): Promise; + defaultConfig: Worker1PromiserConfig; + }; +} + declare type NullPointer = 0 | null | undefined; declare type StructPtrMapper = { @@ -2094,6 +2296,9 @@ declare type Sqlite3Static = { */ initWorker1API(): void; + /** Promise-based proxy for the sqlite3 Worker API #1. */ + Worker1Promiser: Worker1PromiserFactory; + installOpfsSAHPoolVfs(opts: { /** * If truthy (default=false) contents and filename mapping are removed from @@ -2158,10 +2363,10 @@ declare type Sqlite3Static = { SQLite3Error: typeof SQLite3Error; /** - * The options with which the API was configured. Whether or not modifying - * them after the bootstrapping process will have any useful effect is - * unspecified and may change with any given version. Clients must not rely on - * that capability. + * The options with which the API was configured. Whether modifying them after + * the bootstrapping process will have any useful effect is unspecified and + * may change with any given version. Clients must not rely on that + * capability. */ config: { exports: any; diff --git a/src/index.js b/src/index.js index b791f4b..30f0075 100644 --- a/src/index.js +++ b/src/index.js @@ -1,6 +1,9 @@ import { default as sqlite3InitModule } from './bin/sqlite3-bundler-friendly.mjs'; import { default as sqlite3Worker1Promiser } from './bin/sqlite3-worker1-promiser.mjs'; +/** @type {import('./index.d.ts').Worker1PromiserFactory} */ +const typedWorker1Promiser = sqlite3Worker1Promiser; + export default sqlite3InitModule; -export { sqlite3Worker1Promiser }; +export { typedWorker1Promiser as sqlite3Worker1Promiser };