@stoolap/node 0.3.3 → 0.3.5

package/README.md

@@ -1,11 +1,13 @@
 # @stoolap/node
 
-High-performance Node.js driver for [Stoolap](https://github.com/stoolap/stoolap) — a modern embedded SQL database with MVCC, time-travel queries, and full ACID compliance.
+High-performance JavaScript driver for [Stoolap](https://github.com/stoolap/stoolap), a modern embedded SQL database with MVCC, time-travel queries, and full ACID compliance.
 
-Built with [NAPI-RS](https://napi.rs) for native performance. Provides both async and sync APIs with direct V8 object creation for minimal overhead.
+Built with a native N-API C addon for minimal overhead. Works with Node.js, Bun, and Deno. Provides both async and sync APIs.
 
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
-[![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](https://nodejs.org)
+[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)
+[![Bun](https://img.shields.io/badge/bun-compatible-f472b6.svg)](https://bun.sh)
+[![Deno](https://img.shields.io/badge/deno-compatible-000000.svg)](https://deno.com)
 
 ## Installation
 
@@ -13,11 +15,16 @@ Built with [NAPI-RS](https://napi.rs) for native performance. Provides both asyn
 npm install @stoolap/node
 ```
 
-Pre-built binaries are available for:
+The stoolap engine shared library is pre-built for:
 - macOS (x64, ARM64)
 - Linux (x64, ARM64 GNU)
 - Windows (x64 MSVC)
 
+A C compiler is required to build the thin N-API addon on install (compiled automatically via `node-gyp`):
+- **macOS**: `xcode-select --install`
+- **Linux**: `sudo apt-get install build-essential` (or equivalent)
+- **Windows**: [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) with "Desktop development with C++"
+
 ## Quick Start
 
 ```js
@@ -59,7 +66,7 @@ const users = await db.query('SELECT * FROM users ORDER BY id');
 const user = await db.queryOne('SELECT * FROM users WHERE id = $1', [1]);
 // { id: 1, name: 'Alice', email: 'alice@example.com' }
 
-// Query in raw columnar format (faster — no per-row object creation)
+// Query in raw columnar format (faster, no per-row object creation)
 const raw = await db.queryRaw('SELECT id, name FROM users ORDER BY id');
 // { columns: ['id', 'name'], rows: [[1, 'Alice'], [2, 'Bob']] }
 
@@ -85,8 +92,9 @@ const db = await Database.open('file:///absolute/path/to/db');
 
 | Method | Returns | Description |
 |--------|---------|-------------|
+| `Database.open(path)` | `Promise<Database>` | Open a database |
 | `execute(sql, params?)` | `Promise<RunResult>` | Execute DML statement |
-| `exec(sql)` | `Promise<void>` | Execute one or more statements |
+| `exec(sql)` | `Promise<void>` | Execute a DDL statement |
 | `query(sql, params?)` | `Promise<Object[]>` | Query rows as objects |
 | `queryOne(sql, params?)` | `Promise<Object \| null>` | Query single row |
 | `queryRaw(sql, params?)` | `Promise<{columns, rows}>` | Query in columnar format |
@@ -95,18 +103,20 @@ const db = await Database.open('file:///absolute/path/to/db');
 
 #### Sync Methods
 
-Sync methods run on the main thread — faster for simple operations but block the event loop.
+Sync methods run on the main thread. Faster for simple operations but block the event loop.
 
 | Method | Returns | Description |
 |--------|---------|-------------|
+| `Database.openSync(path)` | `Database` | Open a database |
 | `executeSync(sql, params?)` | `RunResult` | Execute DML statement |
-| `execSync(sql)` | `void` | Execute one or more statements |
+| `execSync(sql)` | `void` | Execute a DDL statement |
 | `querySync(sql, params?)` | `Object[]` | Query rows as objects |
 | `queryOneSync(sql, params?)` | `Object \| null` | Query single row |
 | `queryRawSync(sql, params?)` | `{columns, rows}` | Query in columnar format |
 | `executeBatchSync(sql, paramsArray)` | `RunResult` | Execute with multiple param sets |
 | `beginSync()` | `Transaction` | Begin a transaction |
 | `prepare(sql)` | `PreparedStatement` | Create a prepared statement |
+| `closeSync()` | `void` | Close the database |
 
 `RunResult` is `{ changes: number }`. It can be imported as a type:
 
@@ -125,7 +135,7 @@ await db.exec('CREATE TABLE kv (key TEXT PRIMARY KEY, value TEXT)');
 await db.execute('INSERT INTO kv VALUES ($1, $2)', ['hello', 'world']);
 await db.close();
 
-// Reopen — data is still there
+// Reopen: data is still there
 const db2 = await Database.open('./mydata');
 const row = await db2.queryOne('SELECT * FROM kv WHERE key = $1', ['hello']);
 // { key: 'hello', value: 'world' }
@@ -137,10 +147,10 @@ await db2.close();
 Pass configuration as query parameters in the path:
 
 ```js
-// Maximum durability — fsync on every WAL write
+// Maximum durability: fsync on every WAL write
 const db = await Database.open('./mydata?sync=full');
 
-// High throughput — no fsync, larger buffers
+// High throughput: no fsync, larger buffers
 const db = await Database.open('./mydata?sync=none&wal_buffer_size=131072');
 
 // Custom snapshot interval with compression
@@ -158,9 +168,9 @@ Controls the durability vs. performance trade-off:
 
 | Mode | Value | Description |
 |------|-------|-------------|
-| `none` | `sync=none` | No fsync — fastest, data may be lost on crash |
-| `normal` | `sync=normal` | Fsync on commit batches — good balance (default) |
-| `full` | `sync=full` | Fsync on every WAL write — slowest, maximum durability |
+| `none` | `sync=none` | No fsync. Fastest, data may be lost on crash |
+| `normal` | `sync=normal` | Fsync on commit batches. Good balance (default) |
+| `full` | `sync=full` | Fsync on every WAL write. Slowest, maximum durability |
 
 ##### All Configuration Parameters
 
@@ -176,7 +186,7 @@ Controls the durability vs. performance trade-off:
 | `sync_interval_ms` | `10` | Minimum ms between syncs (normal mode) |
 | `wal_compression` | `on` | LZ4 compression for WAL entries |
 | `snapshot_compression` | `on` | LZ4 compression for snapshots |
-| `compression` | — | Set both `wal_compression` and `snapshot_compression` |
+| `compression` | | Set both `wal_compression` and `snapshot_compression` |
 | `compression_threshold` | `64` | Minimum bytes before compressing an entry |
 
 #### Raw Query Format
@@ -207,7 +217,7 @@ console.log(result.changes); // 3
 
 ### PreparedStatement
 
-Prepared statements parse SQL once and reuse the cached execution plan on every call — no parsing or cache lookup overhead per execution.
+Prepared statements parse SQL once and reuse the cached execution plan on every call. No parsing or cache lookup overhead per execution.
 
 ```js
 const insert = db.prepare('INSERT INTO users VALUES ($1, $2, $3)');
@@ -230,8 +240,9 @@ All methods mirror `Database` but without the `sql` parameter (it's bound at pre
 | `queryOne(params?)` | `queryOneSync(params?)` | Query single row |
 | `queryRaw(params?)` | `queryRawSync(params?)` | Query in columnar format |
 | | `executeBatchSync(paramsArray)` | Execute with multiple param sets |
+| | `finalize()` | Release the prepared statement |
 
-Property: `sql` — returns the SQL text of this prepared statement.
+Property: `sql` returns the SQL text of this prepared statement.
 
 #### Async Prepared Statement
 
@@ -368,41 +379,66 @@ try {
 } catch (err) {
   console.error(err.message);
 }
-
-// Prepared statement — errors at prepare time for invalid SQL
-try {
-  db.prepare('INVALID SQL HERE');
-} catch (err) {
-  console.error(err.message);
-}
 ```
 
 ### Supported Types
 
-| JavaScript | Stoolap |
-|-----------|---------|
-| `number` (integer) | `INTEGER` |
-| `number` (float) | `FLOAT` |
-| `string` | `TEXT` |
-| `boolean` | `BOOLEAN` |
-| `null` / `undefined` | `NULL` |
-| `BigInt` | `INTEGER` |
-| `Date` | `TIMESTAMP` |
-| `Buffer` | `TEXT` (UTF-8) |
-| `Object` / `Array` | `JSON` (stringified) |
+| JavaScript | Stoolap | Notes |
+|-----------|---------|-------|
+| `number` (integer) | `INTEGER` | |
+| `number` (float) | `FLOAT` | |
+| `string` | `TEXT` | |
+| `boolean` | `BOOLEAN` | |
+| `null` / `undefined` | `NULL` | |
+| `BigInt` | `INTEGER` | |
+| `Date` | `TIMESTAMP` | |
+| `Float32Array` | `VECTOR(N)` | Returned as `Float32Array` |
+| `Buffer` | `TEXT` (UTF-8) | |
+| `Object` / `Array` | `JSON` (stringified) | |
+
+### Vector Support
+
+Stoolap supports native vector storage and similarity search. Vectors are returned as `Float32Array` and can be passed as `Float32Array` bind parameters.
+
+```js
+// Create a table with a vector column
+await db.exec('CREATE TABLE embeddings (id INTEGER PRIMARY KEY, vec VECTOR(3))');
+
+// Insert vectors via SQL string literals
+await db.execute("INSERT INTO embeddings VALUES (1, '[0.1, 0.2, 0.3]')");
+
+// Query: vectors are returned as Float32Array
+const row = await db.queryOne('SELECT vec FROM embeddings WHERE id = 1');
+console.log(row.vec);              // Float32Array(3) [0.1, 0.2, 0.3]
+console.log(row.vec instanceof Float32Array); // true
+
+// k-NN search with distance functions
+const nearest = await db.query(`
+  SELECT id, VEC_DISTANCE_L2(vec, '[0.15, 0.25, 0.35]') AS dist
+  FROM embeddings ORDER BY dist LIMIT 5
+`);
+
+// HNSW index for fast approximate nearest neighbor search
+await db.exec('CREATE INDEX idx ON embeddings(vec) USING HNSW');
+```
+
+Available distance functions: `VEC_DISTANCE_L2`, `VEC_DISTANCE_COSINE`, `VEC_DISTANCE_IP`.
+
+See the [Stoolap Vector Search docs](https://stoolap.io/docs/data-types/vector-search/) for full details on HNSW indexes, distance metrics, and configuration.
 
 ## Building from Source
 
 Requires:
-- [Rust](https://rustup.rs) (stable)
-- [Node.js](https://nodejs.org) >= 22 (with development headers)
-- C++ compiler (for V8 helpers)
+- [Node.js](https://nodejs.org) >= 18
+- C compiler (gcc, clang, or MSVC)
+- [node-gyp](https://github.com/nodejs/node-gyp) and its prerequisites
+
+The stoolap shared library (`libstoolap.dylib` / `libstoolap.so` / `stoolap.dll`) must be available, either via a platform package or built from the [Stoolap](https://github.com/stoolap/stoolap) repository.
 
 ```bash
 git clone https://github.com/stoolap/stoolap-node.git
 cd stoolap-node
 npm install
-npm run build
 npm test
 ```
 

package/binding.gyp

@@ -0,0 +1,31 @@
+{
+  "targets": [
+    {
+      "target_name": "stoolap",
+      "sources": ["src/stoolap.c"],
+      "include_dirs": [],
+      "cflags": ["-std=c11", "-O2"],
+      "xcode_settings": {
+        "OTHER_CFLAGS": ["-std=c11", "-O2"],
+        "MACOSX_DEPLOYMENT_TARGET": "10.15"
+      },
+      "msvs_settings": {
+        "VCCLCompilerTool": {}
+      },
+      "conditions": [
+        [
+          "OS=='win'",
+          {
+            "libraries": []
+          }
+        ],
+        [
+          "OS!='win'",
+          {
+            "libraries": ["-ldl"]
+          }
+        ]
+      ]
+    }
+  ]
+}

package/index.d.ts

@@ -1,13 +1,10 @@
-/* auto-generated by NAPI-RS */
-/* eslint-disable */
-
 export interface RunResult {
-  changes: number
+  changes: number;
 }
 
 export declare class Database {
   /**
-   * Open a database. Returns a Promise that resolves to a Database instance.
+   * Open a database asynchronously. Returns a Promise that resolves to a Database instance.
    *
    * Accepts:
    * - `:memory:` or empty string for in-memory database
@@ -15,162 +12,178 @@ export declare class Database {
    * - `file:///path/to/db` for file-based database
    * - Bare path like `./mydb` for file-based database
    */
-  static open(path: string): Promise<Database>
+  static open(path: string): Promise<Database>;
+  /**
+   * Open a database synchronously.
+   */
+  static openSync(path: string): Database;
   /**
    * Execute a DDL/DML statement. Returns Promise<{ changes: number }>.
    *
    * @param sql - SQL statement
    * @param params - Optional: Array for positional ($1, $2) or Object for named (:key)
    */
-  execute(sql: string, params?: any[] | Record<string, any>): Promise<RunResult>
+  execute(
+    sql: string,
+    params?: any[] | Record<string, any>,
+  ): Promise<RunResult>;
   /**
-   * Execute one or more SQL statements separated by semicolons.
-   * Returns Promise<void>.
+   * Execute a DDL statement. Returns Promise<void>.
    */
-  exec(sql: string): Promise<void>
+  exec(sql: string): Promise<void>;
   /**
    * Query rows. Returns Promise<Array<Object>>.
    *
    * Each row is an object with column names as keys.
    */
-  query(sql: string, params?: any[] | Record<string, any>): Promise<Record<string, any>[]>
+  query(
+    sql: string,
+    params?: any[] | Record<string, any>,
+  ): Promise<Record<string, any>[]>;
   /** Query a single row. Returns Promise<Object | null>. */
-  queryOne(sql: string, params?: any[] | Record<string, any>): Promise<Record<string, any> | null>
+  queryOne(
+    sql: string,
+    params?: any[] | Record<string, any>,
+  ): Promise<Record<string, any> | null>;
   /**
    * Query rows in raw format. Returns Promise<{ columns: string[], rows: any[][] }>.
    *
-   * Faster than query() — skips per-row object creation.
+   * Faster than query(). Skips per-row object creation.
    */
-  queryRaw(sql: string, params?: any[] | Record<string, any>): Promise<{ columns: string[], rows: any[][] }>
+  queryRaw(
+    sql: string,
+    params?: any[] | Record<string, any>,
+  ): Promise<{ columns: string[]; rows: any[][] }>;
   /**
    * Execute a DML statement synchronously. Returns { changes: number }.
    *
-   * Faster than execute() for simple operations — no async overhead.
-   * Blocks the event loop, so use for fast operations only.
-   */
-  executeSync(sql: string, params?: any[] | Record<string, any>): RunResult
-  /**
-   * Query rows synchronously. Returns Array<Object>.
-   * Uses direct V8 bulk object creation — bypasses NAPI per-property overhead.
-   */
-  querySync(sql: string, params?: any[] | Record<string, any>): Record<string, any>[]
-  /**
-   * Query a single row synchronously. Returns Object | null.
-   * Uses direct V8 bulk object creation — optimal hidden class in one call.
-   */
-  queryOneSync(sql: string, params?: any[] | Record<string, any>): Record<string, any> | null
-  /**
-   * Query rows in raw format synchronously. Returns { columns: string[], rows: any[][] }.
-   * Uses direct V8 bulk array creation — bypasses NAPI per-element overhead.
-   */
-queryRawSync(sql: string, params?: any[] | Record<string, any>): { columns: string[], rows: any[][] }
-/**
- * Execute the same SQL with multiple param sets in a single call.
- * Parses SQL once, auto-wraps in a transaction: begin, execute all, commit.
- * Returns { changes: total_rows_affected }.
- */
-executeBatchSync(sql: string, paramsArray: any[][]): RunResult
-/** Execute one or more SQL statements synchronously. */
-execSync(sql: string): void
-/** Create a prepared statement (synchronous — parses and caches the plan). */
-prepare(sql: string): JsPreparedStatement
-/** Begin a transaction. Returns Promise<Transaction>. */
-begin(): Promise<Transaction>
-/** Begin a transaction synchronously. Returns Transaction. */
-beginSync(): Transaction
-/** Close the database. Returns Promise<void>. */
-close(): Promise<void>
+   * Faster than execute() for simple operations. No async overhead.
+   */
+  executeSync(sql: string, params?: any[] | Record<string, any>): RunResult;
+  /** Execute a DDL statement synchronously. */
+  execSync(sql: string): void;
+  /** Query rows synchronously. Returns Array<Object>. */
+  querySync(
+    sql: string,
+    params?: any[] | Record<string, any>,
+  ): Record<string, any>[];
+  /** Query a single row synchronously. Returns Object | null. */
+  queryOneSync(
+    sql: string,
+    params?: any[] | Record<string, any>,
+  ): Record<string, any> | null;
+  /** Query rows in raw format synchronously. Returns { columns: string[], rows: any[][] }. */
+  queryRawSync(
+    sql: string,
+    params?: any[] | Record<string, any>,
+  ): { columns: string[]; rows: any[][] };
+  /**
+   * Execute the same SQL with multiple param sets in a single call.
+   * Auto-wraps in a transaction: begin, execute all, commit.
+   * Returns { changes: total_rows_affected }.
+   */
+  executeBatchSync(sql: string, paramsArray: any[][]): RunResult;
+  /** Create a prepared statement (synchronous). */
+  prepare(sql: string): PreparedStatement;
+  /** Begin a transaction. Returns Promise<Transaction>. */
+  begin(): Promise<Transaction>;
+  /** Begin a transaction synchronously. Returns Transaction. */
+  beginSync(): Transaction;
+  /** Close the database. Returns Promise<void>. */
+  close(): Promise<void>;
+  /** Close the database synchronously. */
+  closeSync(): void;
 }
-export type JsDatabase = Database
+export type JsDatabase = Database;
 
 export declare class PreparedStatement {
   /** Execute the statement (DML). Returns Promise<{ changes: number }>. */
-  execute(params?: any[] | Record<string, any>): Promise<RunResult>
+  execute(params?: any[] | Record<string, any>): Promise<RunResult>;
   /** Query rows. Returns Promise<Array<Object>>. */
-  query(params?: any[] | Record<string, any>): Promise<Record<string, any>[]>
+  query(params?: any[] | Record<string, any>): Promise<Record<string, any>[]>;
   /** Query single row. Returns Promise<Object | null>. */
-  queryOne(params?: any[] | Record<string, any>): Promise<Record<string, any> | null>
+  queryOne(
+    params?: any[] | Record<string, any>,
+  ): Promise<Record<string, any> | null>;
   /** Query rows in raw format. Returns Promise<{ columns: string[], rows: any[][] }>. */
-  queryRaw(params?: any[] | Record<string, any>): Promise<{ columns: string[], rows: any[][] }>
+  queryRaw(
+    params?: any[] | Record<string, any>,
+  ): Promise<{ columns: string[]; rows: any[][] }>;
   /** Execute synchronously. Returns { changes: number }. */
-  executeSync(params?: any[] | Record<string, any>): RunResult
-  /**
-   * Query rows synchronously. Returns Array<Object>.
-   * Uses direct V8 bulk object creation — bypasses NAPI per-property overhead.
-   */
-  querySync(params?: any[] | Record<string, any>): Record<string, any>[]
-  /**
-   * Query single row synchronously. Returns Object | null.
-   * Uses direct V8 bulk object creation — optimal hidden class in one call.
-   */
-  queryOneSync(params?: any[] | Record<string, any>): Record<string, any> | null
-  /**
-   * Query rows in raw format synchronously. Returns { columns: string[], rows: any[][] }.
-   * Uses direct V8 bulk array creation — bypasses NAPI per-element overhead.
-   */
-queryRawSync(params?: any[] | Record<string, any>): { columns: string[], rows: any[][] }
-/**
- * Execute the prepared SQL with multiple param sets in a single call.
- * Uses pre-cached AST, auto-wraps in a transaction: begin, execute all, commit.
- * Returns { changes: total_rows_affected }.
- */
-executeBatchSync(paramsArray: any[][]): RunResult
-/** Get the SQL text of this prepared statement. */
-get sql(): string
+  executeSync(params?: any[] | Record<string, any>): RunResult;
+  /** Query rows synchronously. Returns Array<Object>. */
+  querySync(params?: any[] | Record<string, any>): Record<string, any>[];
+  /** Query single row synchronously. Returns Object | null. */
+  queryOneSync(
+    params?: any[] | Record<string, any>,
+  ): Record<string, any> | null;
+  /** Query rows in raw format synchronously. Returns { columns: string[], rows: any[][] }. */
+  queryRawSync(params?: any[] | Record<string, any>): {
+    columns: string[];
+    rows: any[][];
+  };
+  /**
+   * Execute the prepared SQL with multiple param sets in a single call.
+   * Returns { changes: total_rows_affected }.
+   */
+  executeBatchSync(paramsArray: any[][]): RunResult;
+  /** Get the SQL text of this prepared statement. */
+  get sql(): string;
+  /** Release the prepared statement. */
+  finalize(): void;
 }
-export type JsPreparedStatement = PreparedStatement
+export type JsPreparedStatement = PreparedStatement;
 
 export declare class Transaction {
-  /**
-   * Execute a DML statement within the transaction.
-   * Returns Promise<{ changes: number }>.
-   */
-  execute(sql: string, params?: any[] | Record<string, any>): Promise<RunResult>
-  /**
-   * Query rows within the transaction.
-   * Returns Promise<Array<Object>>.
-   */
-  query(sql: string, params?: any[] | Record<string, any>): Promise<Record<string, any>[]>
-  /**
-   * Query a single row within the transaction.
-   * Returns Promise<Object | null>.
-   */
-  queryOne(sql: string, params?: any[] | Record<string, any>): Promise<Record<string, any> | null>
-  /**
-   * Query rows in raw format within the transaction.
-   * Returns Promise<{ columns: string[], rows: any[][] }>.
-   */
-  queryRaw(sql: string, params?: any[] | Record<string, any>): Promise<{ columns: string[], rows: any[][] }>
+  /** Execute a DML statement within the transaction. Returns Promise<{ changes: number }>. */
+  execute(
+    sql: string,
+    params?: any[] | Record<string, any>,
+  ): Promise<RunResult>;
+  /** Query rows within the transaction. Returns Promise<Array<Object>>. */
+  query(
+    sql: string,
+    params?: any[] | Record<string, any>,
+  ): Promise<Record<string, any>[]>;
+  /** Query a single row within the transaction. Returns Promise<Object | null>. */
+  queryOne(
+    sql: string,
+    params?: any[] | Record<string, any>,
+  ): Promise<Record<string, any> | null>;
+  /** Query rows in raw format within the transaction. Returns Promise<{ columns: string[], rows: any[][] }>. */
+  queryRaw(
+    sql: string,
+    params?: any[] | Record<string, any>,
+  ): Promise<{ columns: string[]; rows: any[][] }>;
   /** Commit the transaction. Returns Promise<void>. */
-  commit(): Promise<void>
+  commit(): Promise<void>;
   /** Rollback the transaction. Returns Promise<void>. */
-  rollback(): Promise<void>
+  rollback(): Promise<void>;
   /** Execute a DML statement synchronously. Returns { changes: number }. */
-  executeSync(sql: string, params?: any[] | Record<string, any>): RunResult
-  /**
-   * Query rows synchronously. Returns Array<Object>.
-   * Uses direct V8 bulk object creation — bypasses NAPI per-property overhead.
-   */
-  querySync(sql: string, params?: any[] | Record<string, any>): Record<string, any>[]
-  /**
-   * Query a single row synchronously. Returns Object | null.
-   * Uses direct V8 bulk object creation — optimal hidden class in one call.
-   */
-  queryOneSync(sql: string, params?: any[] | Record<string, any>): Record<string, any> | null
-  /**
-   * Query rows in raw format synchronously. Returns { columns: string[], rows: any[][] }.
-   * Uses direct V8 bulk array creation — bypasses NAPI per-element overhead.
-   */
-queryRawSync(sql: string, params?: any[] | Record<string, any>): { columns: string[], rows: any[][] }
-/** Commit the transaction synchronously. */
-commitSync(): void
-/**
- * Execute the same SQL with multiple param sets in a single call.
- * Parses SQL once, locks the transaction once — eliminates per-call overhead.
- * Returns { changes: total_rows_affected }.
- */
-executeBatchSync(sql: string, paramsArray: any[][]): RunResult
-/** Rollback the transaction synchronously. */
-rollbackSync(): void
+  executeSync(sql: string, params?: any[] | Record<string, any>): RunResult;
+  /** Query rows synchronously. Returns Array<Object>. */
+  querySync(
+    sql: string,
+    params?: any[] | Record<string, any>,
+  ): Record<string, any>[];
+  /** Query a single row synchronously. Returns Object | null. */
+  queryOneSync(
+    sql: string,
+    params?: any[] | Record<string, any>,
+  ): Record<string, any> | null;
+  /** Query rows in raw format synchronously. Returns { columns: string[], rows: any[][] }. */
+  queryRawSync(
+    sql: string,
+    params?: any[] | Record<string, any>,
+  ): { columns: string[]; rows: any[][] };
+  /** Commit the transaction synchronously. */
+  commitSync(): void;
+  /**
+   * Execute the same SQL with multiple param sets in a single call.
+   * Returns { changes: total_rows_affected }.
+   */
+  executeBatchSync(sql: string, paramsArray: any[][]): RunResult;
+  /** Rollback the transaction synchronously. */
+  rollbackSync(): void;
 }
-export type JsTransaction = Transaction
+export type JsTransaction = Transaction;