feat: added Worker1 Promiser types (#137)

* feat: added Worker1 Promiser types

* feat: added missing promiser types

* feat: added stricter types

Author: jurerotar

src/index.d.ts

@@ -483,10 +483,16 @@ export type ExecOptions = {
    * but clients must also refrain from using any lower-level (C-style) APIs
    * which might modify the statement.
    */
-  callback?: (
-    row: SqlValue[] | Record<string, SqlValue> | PreparedStatement | SqlValue,
-    stmt: PreparedStatement,
-  ) => void | false;
+  callback?:
+    | ((
+        row:
+          | SqlValue[]
+          | Record<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
@@ -738,7 +744,7 @@ export type WindowFunctionOptions = FunctionOptions & {
  * using `sqlite3_open` or equivalent.
  *
  * @example
- *   ```typescript
+ *   ```ts
  *   const db = new sqlite3.DB();
  *   try {
  *     db.exec([
@@ -1552,7 +1558,7 @@ export type SAHPoolUtil = {
 /** Exception class for reporting WASM-side allocation errors. */
 export class WasmAllocError extends Error {
   constructor(message: string);
-  toss: any;
+  toss: (...args: unknown[]) => never;
 }
 
 /** Exception class used primarily by the oo1 API. */
@@ -1566,6 +1572,232 @@ export type WasmPointer = number;
 
 export type NullPointer = 0 | null | undefined;
 
+/** 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?: unknown;
+
+  /**
+   * 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 = unknown,
+> extends Worker1MessageBusEnvelope {
+  type: T;
+  args?: Args;
+  /** Timestamp set by the promiser before posting a message. */
+  departureTime?: number;
+}
+
+/** Worker API #1 output message envelope. */
+interface Worker1OutputEnvelope<
+  T extends string,
+  Result = unknown,
+> extends Worker1MessageBusEnvelope {
+  type: T;
+  result: Result;
+}
+
+/**
+ * Worker API #1 per-row callback payload for promiser `exec()` callback
+ * functions.
+ */
+interface Worker1ExecRowMessage {
+  /** Internally synthesized callback message type. */
+  type: `${string}:row`;
+  /** Current row value in the shape implied by `rowMode`. */
+  row?: SqlValue[] | Record<string, SqlValue> | SqlValue;
+  /** 1-based row number, or null as end-of-result-set sentinel. */
+  rowNumber: number | null;
+  /** Column names populated when requested by options. */
+  columnNames?: string[];
+}
+
+/** Worker API #1 exec options accepted by the promiser wrapper. */
+type Worker1ExecArgs = Omit<ExecOptions, 'callback'> & {
+  /**
+   * Promiser-specific callback mode. String callback IDs are not accepted by
+   * the promiser wrapper.
+   */
+  callback?: (row: Worker1ExecRowMessage) => void;
+};
+
+/** 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: Worker1InputEnvelope<string, unknown>;
+  /** 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: Worker1ExecArgs | 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.
+   */
+  <T extends keyof Worker1ArgsMap>(
+    type: T,
+    args: Worker1ArgsMap[T],
+  ): Promise<Worker1OutputEnvelope<T, Worker1ResultMap[T]>>;
+
+  /**
+   * Sends a message to the worker and returns a Promise which resolves to the
+   * response message.
+   */
+  <T extends keyof Worker1ArgsMap>(
+    msg: Worker1InputEnvelope<T, Worker1ArgsMap[T]>,
+  ): Promise<Worker1OutputEnvelope<T, Worker1ResultMap[T]>>;
+}
+
+/** 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 | Promise<void>;
+
+  /** Callback for unhandled worker messages. */
+  onunhandled?: (event: MessageEvent) => void;
+
+  /** Optional function to generate unique message IDs. */
+  generateMessageId?: (msg: Worker1InputEnvelope<string, unknown>) => string;
+
+  /** Optional debug logging function. */
+  debug?: (...args: unknown[]) => void;
+
+  /** Optional error logging function (undocumented). */
+  onerror?: (...args: unknown[]) => 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<Worker1Promiser>;
+    (onready: (promiser: Worker1Promiser) => void): Promise<Worker1Promiser>;
+    defaultConfig: Worker1PromiserConfig;
+  };
+}
+
 export type StructPtrMapper<T> = {
   StructType: T;
   /**
@@ -2089,6 +2321,9 @@ export 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
@@ -2153,10 +2388,10 @@ export 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;

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 };