@cqlite/node 0.3.1-rc5 → 0.9.1

package/README.md

@@ -225,6 +225,68 @@ CQL types are automatically converted to JavaScript types:
 \* **Note:** With `execute()`, `varint` returns `"0x{hex}"` and `decimal` returns `"decimal:{scale}:0x{hex}"`.
 Use `executeNative()` for human-readable formats.
 
+## Write Operations
+
+CQLite v0.9.0 adds write support to the Node.js bindings. Open the database with
+`writable: true` and a `writeDir` to enable write operations.
+
+```javascript
+const { Database } = require('@cqlite/node');
+
+const db = await Database.open('path/to/sstables', {
+  schema: 'schema.cql',
+  writable: true,
+  writeDir: '/tmp/my-writes',
+});
+
+// Write rows via CQL INSERT, UPDATE, or DELETE
+await db.execute(
+  "INSERT INTO test_basic.simple_table (id, name, age) " +
+  "VALUES (22222222-2222-2222-2222-222222222222, 'Bob', 25)"
+);
+await db.execute(
+  "UPDATE test_basic.simple_table SET age = 26 " +
+  "WHERE id = 22222222-2222-2222-2222-222222222222"
+);
+
+// Flush the in-memory write buffer (memtable) to an SSTable on disk.
+// Returns the path to the flushed Data.db file, or "" if memtable was empty.
+const path = await db.flushRun();
+console.log('Flushed to:', path);
+
+// Run background compaction within a time budget
+const report = await db.maintenanceStep({ budgetMs: 100 });
+console.log(`Merged ${report.rowsMerged} rows in ${report.timeSpentMs}ms`);
+if (report.pendingCompaction) {
+  console.log('More compaction work available');
+}
+
+// Inspect write statistics (synchronous getter)
+const stats = db.writeStats;
+console.log('Memtable size:', stats.memtableSizeBytes, 'bytes');
+console.log('Total flushed:', stats.totalWrittenBytes, 'bytes');
+
+await db.close();
+```
+
+### Write API
+
+| Method / Property | Description |
+|-------------------|-------------|
+| `db.execute(cql)` | Execute a CQL INSERT, UPDATE, or DELETE statement |
+| `db.flushRun()` | Flush memtable to SSTable; returns the Data.db path or `""` if memtable was empty |
+| `db.maintenanceStep(options?)` | Run STCS compaction for up to `options.budgetMs` ms (default: 100); returns `MaintenanceReport` |
+| `db.writeStats` | Synchronous getter: `memtableSizeBytes`, `memtableRowCount`, `totalWrittenBytes`, `l0SstableCount` |
+
+### Known Limitations
+
+- Counter columns cannot be written — `execute()` throws `CqliteError` for
+  counter mutations.
+- BTI-format index files are not produced; the writer emits BIG format.
+
+See [docs/write-support-limitations.md](../../docs/write-support-limitations.md)
+for the full limitations reference.
+
 ## Examples
 
 See the [examples/](examples/) directory for complete working examples:
@@ -239,6 +301,7 @@ See the [examples/](examples/) directory for complete working examples:
 
 - [TypeScript Definitions](lib/index.d.ts) - Complete API type hints
 - [Main Project README](../../README.md) - CQLite project overview
+- [Write Support Guide](../../docs/write-support.md) - Detailed write documentation
 - [Issue Tracker](https://github.com/pmcfadin/cqlite/issues) - Report bugs or request features
 
 ## License

package/lib/error-wrapper.js

@@ -189,7 +189,12 @@ function createWrappedDatabase(NativeDatabase, wrapPreparedStatement) {
     async execute(query) {
       try {
         const result = await this._native.execute(query);
-        result.rowsAffected = result.rowCount; // M4 spec alias (Issue #348)
+        // For SELECT: rowsAffected = rowCount (alias, Issue #348).
+        // For DML (INSERT/UPDATE/DELETE): rowsAffected is already set by Rust layer to 1;
+        // do NOT overwrite it with rowCount (which would be 0 for writes).
+        if (result.rowsAffected === undefined || result.rowsAffected === null) {
+          result.rowsAffected = result.rowCount;
+        }
         return result;
       } catch (error) {
         throw enhanceError(error);
@@ -199,7 +204,10 @@ function createWrappedDatabase(NativeDatabase, wrapPreparedStatement) {
     async executeNative(query) {
       try {
         const result = await this._native.executeNative(query);
-        result.rowsAffected = result.rowCount; // M4 spec alias (Issue #348)
+        // Same pattern as execute(): preserve rowsAffected from Rust layer.
+        if (result.rowsAffected === undefined || result.rowsAffected === null) {
+          result.rowsAffected = result.rowCount;
+        }
         return result;
       } catch (error) {
         throw enhanceError(error);
@@ -362,6 +370,55 @@ function createWrappedDatabase(NativeDatabase, wrapPreparedStatement) {
         throw enhanceError(error);
       }
     }
+
+    /**
+     * Flush the in-memory write buffer (memtable) to an SSTable on disk.
+     *
+     * Returns the path to the created Data.db file.
+     * Returns an empty string if the memtable was empty (no-op flush).
+     *
+     * Requires the database to have been opened with `{ writable: true }`.
+     *
+     * @returns {Promise<string>} Absolute path to the Data.db file, or "" if nothing flushed
+     * @throws {CqliteError} If write support is not enabled or the flush fails
+     */
+    async flushRun() {
+      try {
+        return await this._native.flushRun();
+      } catch (error) {
+        throw enhanceError(error);
+      }
+    }
+
+    /**
+     * Perform time-bounded background maintenance (compaction).
+     *
+     * @param {Object} [options] - Maintenance options
+     * @param {number} [options.budgetMs=100] - Time budget in milliseconds
+     * @returns {Promise<Object>} MaintenanceReport with timeSpentMs, rowsMerged, etc.
+     * @throws {CqliteError} If write support is not enabled or maintenance fails
+     */
+    async maintenanceStep(options) {
+      try {
+        return await this._native.maintenanceStep(options);
+      } catch (error) {
+        throw enhanceError(error);
+      }
+    }
+
+    /**
+     * Get current write engine statistics (synchronous getter).
+     *
+     * @returns {Object} WriteStats with memtableSize, memtableRows, walSize, l0Count, totalWritten
+     * @throws {CqliteError} If write support is not enabled
+     */
+    get writeStats() {
+      try {
+        return this._native.writeStats;
+      } catch (error) {
+        throw enhanceError(error);
+      }
+    }
   }
 
   return Database;

package/lib/index.d.ts

@@ -220,10 +220,8 @@ export interface QueryResult {
   rowCount: number;
 
   /**
-   * Number of rows returned (M4 spec alias for rowCount).
-   *
-   * Note: CQLite is read-only. For SELECT queries, this represents
-   * the number of rows read, not modified.
+   * Number of rows affected by the write (INSERT/UPDATE/DELETE).
+   * 0 for SELECT queries.
    */
   rowsAffected: number;
 
@@ -262,10 +260,8 @@ export interface NativeQueryResult {
   rowCount: number;
 
   /**
-   * Number of rows returned (M4 spec alias for rowCount).
-   *
-   * Note: CQLite is read-only. For SELECT queries, this represents
-   * the number of rows read, not modified.
+   * Number of rows affected by the write (INSERT/UPDATE/DELETE).
+   * 0 for SELECT queries.
    */
   rowsAffected: number;
 
@@ -316,18 +312,27 @@ export interface DatabaseStats {
  *
  * @example
  * ```typescript
+ * // Read-only
  * const options: DatabaseOptions = {
  *   schema: '/path/to/schema.cql',
  *   memoryLimit: 256 * 1024 * 1024, // 256MB
  *   cacheEnabled: true
  * };
  * const db = await Database.open('/path/to/data', options);
+ *
+ * // Read-write
+ * const db = await Database.open('/path/to/data', {
+ *   schema: '/path/to/schema.cql',
+ *   writable: true,
+ *   writeDir: '/tmp/cqlite-writes',
+ * });
  * ```
  */
 export interface DatabaseOptions {
   /**
    * Path to a CQL schema file (.cql).
    * If provided, the schema will be loaded and used for query execution.
+   * Required when `writable` is true.
    */
   schema?: string;
 
@@ -350,6 +355,114 @@ export interface DatabaseOptions {
    * Set to false to minimize memory usage at the cost of performance.
    */
   cacheEnabled?: boolean;
+
+  /**
+   * Enable write support (INSERT, UPDATE, DELETE).
+   * When true, `writeDir` must also be provided and a `schema` is required.
+   * Default: false (read-only mode).
+   */
+  writable?: boolean;
+
+  /**
+   * Directory for write-engine data (memtable flush targets and WAL files).
+   * Required when `writable` is true.
+   * Sub-directories `data/` and `wal/` are created automatically.
+   *
+   * @example
+   * ```typescript
+   * { writable: true, writeDir: '/tmp/cqlite-writes' }
+   * ```
+   */
+  writeDir?: string;
+}
+
+// ============================================================================
+// Write Support
+// ============================================================================
+
+/**
+ * Write engine statistics.
+ *
+ * Returned synchronously by `Database.writeStats`.
+ * Reflects the current state of the in-memory write buffer and WAL.
+ *
+ * @example
+ * ```typescript
+ * const stats = db.writeStats;
+ * console.log(`Memtable: ${stats.memtableSize} bytes, ${stats.memtableRows} rows`);
+ * console.log(`L0 files: ${stats.l0Count}`);
+ * ```
+ */
+export interface WriteStats {
+  /** Current memtable size in bytes. */
+  memtableSize: number;
+
+  /** Current number of rows in the memtable. */
+  memtableRows: number;
+
+  /** Current write-ahead log (WAL) size in bytes. */
+  walSize: number;
+
+  /**
+   * Number of L0 SSTable files flushed during this session.
+   * Increases by 1 for each `flushRun()` call that produced data.
+   */
+  l0Count: number;
+
+  /** Total bytes written to SSTables across all flushes in this session. */
+  totalWritten: number;
+}
+
+/**
+ * Options for `Database.maintenanceStep()`.
+ *
+ * Controls time-bounded background compaction.
+ *
+ * @example
+ * ```typescript
+ * const report = await db.maintenanceStep({ budgetMs: 200 });
+ * ```
+ */
+export interface MaintenanceOptions {
+  /**
+   * Maximum time to spend in this maintenance step, in milliseconds.
+   * Default: 100.
+   */
+  budgetMs?: number;
+}
+
+/**
+ * Report returned by `Database.maintenanceStep()`.
+ *
+ * Describes progress made during one time-bounded compaction step.
+ *
+ * @example
+ * ```typescript
+ * const report = await db.maintenanceStep({ budgetMs: 100 });
+ * console.log(`Merged ${report.rowsMerged} rows in ${report.timeSpentMs}ms`);
+ * if (report.pendingCompaction) {
+ *   console.log('More compaction work pending');
+ * }
+ * ```
+ */
+export interface MaintenanceReport {
+  /** Time actually spent in the maintenance step, in milliseconds. */
+  timeSpentMs: number;
+
+  /** Number of rows merged during this step. */
+  rowsMerged: number;
+
+  /** Number of bytes written during this step. */
+  bytesWritten: number;
+
+  /**
+   * Paths of SSTables produced by merges completed in this step.
+   * Empty array when no merge was completed (step was partial progress).
+   */
+  completedMerges: string[];
+
+  /** Whether there is more compaction work pending after this step. */
+  pendingCompaction: boolean;
 }
 
 /**
@@ -854,6 +967,75 @@ export declare class Database {
    * @throws {CqliteError} If the query cannot be prepared
    */
   prepare(query: string): Promise<PreparedStatement>;
+
+  /**
+   * Flush the in-memory write buffer (memtable) to an SSTable on disk.
+   *
+   * Returns the path to the created Data.db file.
+   * If the memtable is empty, an empty string is returned (no-op flush).
+   *
+   * Requires the database to have been opened with `{ writable: true }`.
+   *
+   * @returns Promise resolving to the Data.db path, or "" if nothing was flushed
+   * @throws {CqliteError} If write support is not enabled or the flush fails
+   *
+   * @example
+   * ```typescript
+   * const db = await Database.open('/data', {
+   *   schema: 'schema.cql',
+   *   writable: true,
+   *   writeDir: '/tmp/writes',
+   * });
+   * await db.execute("INSERT INTO t (id, name) VALUES (uuid(), 'Alice')");
+   * const sstablePath = await db.flushRun();
+   * console.log(`Flushed to: ${sstablePath}`);
+   * ```
+   */
+  flushRun(): Promise<string>;
+
+  /**
+   * Perform time-bounded background maintenance (compaction).
+   *
+   * Runs incremental compaction work within the provided time budget.
+   * Can be called repeatedly to drain pending compaction work.
+   *
+   * Requires the database to have been opened with `{ writable: true }`.
+   *
+   * @param options - Optional maintenance options (default budgetMs: 100)
+   * @returns Promise resolving to a MaintenanceReport
+   * @throws {CqliteError} If write support is not enabled or maintenance fails
+   *
+   * @example
+   * ```typescript
+   * let report: MaintenanceReport;
+   * do {
+   *   report = await db.maintenanceStep({ budgetMs: 100 });
+   *   console.log(`Merged ${report.rowsMerged} rows`);
+   * } while (report.pendingCompaction);
+   * ```
+   */
+  maintenanceStep(options?: MaintenanceOptions): Promise<MaintenanceReport>;
+
+  /**
+   * Get current write engine statistics (synchronous getter).
+   *
+   * Returns a snapshot of the in-memory write buffer (memtable) and WAL state.
+   *
+   * Requires the database to have been opened with `{ writable: true }`.
+   *
+   * @returns WriteStats snapshot
+   * @throws {CqliteError} If write support is not enabled
+   *
+   * @example
+   * ```typescript
+   * const stats = db.writeStats;
+   * console.log(`Memtable: ${stats.memtableSize} bytes, ${stats.memtableRows} rows`);
+   * console.log(`WAL: ${stats.walSize} bytes`);
+   * console.log(`L0 files: ${stats.l0Count}`);
+   * console.log(`Total written: ${stats.totalWritten} bytes`);
+   * ```
+   */
+  get writeStats(): WriteStats;
 }
 
 // ============================================================================

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cqlite/node",
-  "version": "0.3.1-rc5",
+  "version": "0.9.1",
   "description": "Node.js bindings for CQLite - read Apache Cassandra 5.0 SSTables without cluster dependencies",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -27,8 +27,10 @@
     "access": "public"
   },
   "scripts": {
-    "build": "napi build --platform --release",
-    "build:debug": "napi build --platform",
+    "build": "napi build --platform --release --features write-support",
+    "postbuild": "node scripts/generate-loader.mjs",
+    "build:debug": "napi build --platform --features write-support",
+    "pretest": "node scripts/generate-loader.mjs",
     "test": "jest",
     "test:watch": "jest --watch",
     "test:coverage": "jest --coverage",

package/index.d.ts

@@ -1,413 +0,0 @@
-/* tslint:disable */
-/* eslint-disable */
-
-/* auto-generated by NAPI-RS */
-
-/**
- * Column metadata information.
- *
- * Provides information about a column in the query result set,
- * including name, data type, and nullability.
- */
-export interface ColumnInfo {
-  /** Column name. */
-  name: string
-  /** CQL data type as a string (e.g., "Text", "Integer", "List"). */
-  dataType: string
-  /** Whether the column can contain null values. */
-  nullable: boolean
-  /** Column position in the result set (0-indexed). */
-  position: number
-  /** Original table name (for joined queries). */
-  tableName?: string
-}
-/**
- * Query execution result.
- *
- * Contains the query results serialized as JSON values for JavaScript
- * consumption, along with metadata about the execution.
- */
-export interface QueryResult {
-  /**
-   * Result rows as JSON objects.
-   * Each row is a JSON object with column names as keys.
-   */
-  rows: Array<any>
-  /** Number of rows returned. */
-  rowCount: number
-  /** Query execution time in milliseconds. */
-  executionTimeMs: number
-  /**
-   * Column metadata for the result set.
-   * Contains information about each column's name, type, and nullability.
-   */
-  columns: Array<ColumnInfo>
-}
-/**
- * Database statistics.
- *
- * Provides information about the database state including
- * storage and memory metrics.
- */
-export interface DatabaseStats {
-  /** Total number of SSTable files. */
-  totalSstables: number
-  /** Total number of rows across all SSTables. */
-  totalRows: bigint
-  /** Memory currently used by the database in bytes. */
-  memoryUsedBytes: bigint
-}
-/**
- * Database open options.
- *
- * Configuration options for opening a database.
- */
-export interface DatabaseOptions {
-  /**
-   * Path to a CQL schema file (.cql).
-   * If provided, the schema will be loaded and used for query execution.
-   */
-  schema?: string
-  /**
-   * Maximum memory usage in bytes.
-   * Default: 1GB (1073741824 bytes).
-   * Controls the overall memory budget for caches and internal buffers.
-   * JavaScript numbers can safely represent up to 2^53 bytes (~9 petabytes).
-   */
-  memoryLimit?: number
-  /**
-   * Enable or disable all caches (block, row, query).
-   * Default: true (caches enabled).
-   * Set to false to minimize memory usage at the cost of performance.
-   */
-  cacheEnabled?: boolean
-}
-/**
- * Configuration for streaming query execution.
- *
- * Controls memory usage during large result set iteration.
- * Used with `executeStreaming()` for memory-efficient processing
- * of large result sets.
- *
- * ## Example
- *
- * ```javascript
- * const config = { bufferSize: 512, chunkSize: 5000 };
- * for await (const row of db.executeStreaming(query, config)) {
- *   console.log(row);
- * }
- * ```
- *
- * ## Memory Budget
- *
- * Default values (~11MB peak usage):
- * - bufferSize: 1024 rows × ~1KB = ~1MB in flight
- * - chunkSize: 10000 rows × ~1KB = ~10MB per chunk
- *
- * For rows with large blobs, reduce buffer sizes proportionally.
- */
-export interface StreamingConfig {
-  /**
-   * Number of rows to buffer in memory during streaming.
-   * Controls backpressure. Default: 1024.
-   */
-  bufferSize?: number
-  /**
-   * Number of rows per fetch chunk from storage.
-   * Larger chunks improve throughput, smaller chunks reduce memory.
-   * Default: 10000.
-   */
-  chunkSize?: number
-}
-/**
- * Statistics about a prepared statement.
- *
- * Contains query plan information useful for optimization
- * and debugging query performance.
- */
-export interface PreparedStatementStats {
-  /** Number of parameters in the query. */
-  parameterCount: number
-  /** Type of execution plan (TableScan, IndexScan, PointLookup). */
-  planType: string
-  /** Estimated execution cost (relative metric for comparing plans). */
-  estimatedCost: number
-  /** Estimated number of rows to be returned. */
-  estimatedRows: bigint
-  /** Whether the query is cache-friendly. */
-  cacheFriendly: boolean
-}
-/**
- * Returns the version of the cqlite-node binding.
- *
- * @returns The semantic version string (e.g., "0.3.0")
- *
- * @example
- * ```javascript
- * const { version } = require('@cqlite/node');
- * console.log(`CQLite version: ${version()}`);
- * ```
- */
-export declare function version(): string
-/**
- * A CQLite database handle.
- *
- * Use `Database.open()` to create a Database instance.
- * Always close the database when done to release resources.
- *
- * ## Example
- *
- * ```javascript
- * const db = await Database.open('/path/to/data', { schema: '/path/to/schema.cql' });
- * try {
- *   const result = await db.execute('SELECT * FROM users LIMIT 10');
- *   console.log(`Got ${result.rowCount} rows`);
- * } finally {
- *   await db.close();
- * }
- * ```
- *
- * ## Thread Safety
- *
- * Database handles are thread-safe and can be shared across worker threads.
- * The `close()` method is idempotent - calling it multiple times is safe.
- */
-export declare class Database {
-  /**
-   * Opens a database at the specified data directory.
-   *
-   * @param dataDir - Path to the SSTable data directory
-   * @param options - Optional configuration (schema path, etc.)
-   * @returns Promise resolving to a Database instance
-   *
-   * @example
-   * ```javascript
-   * // Basic open
-   * const db = await Database.open('/path/to/sstables');
-   *
-   * // With schema file
-   * const db = await Database.open('/path/to/sstables', {
-   *   schema: '/path/to/schema.cql'
-   * });
-   * ```
-   */
-  static open(dataDir: string, options?: DatabaseOptions | undefined | null): Promise<Database>
-  /**
-   * Execute a CQL query and return results.
-   *
-   * Executes a query against the database and returns all matching rows.
-   * For large result sets, consider using streaming (future feature).
-   *
-   * @param query - CQL SELECT statement to execute
-   * @returns Promise resolving to QueryResult with rows and metadata
-   *
-   * @example
-   * ```javascript
-   * const result = await db.execute('SELECT * FROM users LIMIT 10');
-   * console.log(`Got ${result.rowCount} rows in ${result.executionTimeMs}ms`);
-   * for (const row of result.rows) {
-   *   console.log(row.name);
-   * }
-   * ```
-   */
-  execute(query: string): Promise<QueryResult>
-  /**
-   * Get database statistics.
-   *
-   * Returns information about storage, memory usage, and other metrics.
-   *
-   * @returns Promise resolving to DatabaseStats
-   *
-   * @example
-   * ```javascript
-   * const stats = await db.getStats();
-   * console.log(`SSTables: ${stats.totalSstables}`);
-   * console.log(`Total rows: ${stats.totalRows}`);
-   * console.log(`Memory: ${stats.memoryUsedBytes} bytes`);
-   * ```
-   */
-  getStats(): Promise<DatabaseStats>
-  /**
-   * Close the database and release resources.
-   *
-   * This method is idempotent - calling it multiple times is safe.
-   * After closing, any operations on the database will throw an error.
-   *
-   * @returns Promise resolving when close is complete
-   *
-   * @example
-   * ```javascript
-   * const db = await Database.open('/path/to/data');
-   * // ... use database ...
-   * await db.close();
-   * await db.close(); // Safe to call again
-   * ```
-   */
-  close(): Promise<void>
-  /**
-   * Check if the database is closed.
-   *
-   * @returns True if the database has been closed, false otherwise
-   */
-  get isClosed(): boolean
-  /**
-   * Execute a CQL query with streaming results.
-   *
-   * Returns a `StreamingResult` that yields rows one at a time for memory-efficient
-   * processing of large result sets. Use with JavaScript's `for await...of` loop.
-   *
-   * Memory stays bounded by `StreamingConfig` settings (default ~11MB peak):
-   * - `bufferSize`: 1024 rows in flight
-   * - `chunkSize`: 10,000 rows per fetch chunk
-   *
-   * @param query - CQL SELECT statement to execute
-   * @param config - Optional StreamingConfig for buffer/chunk sizes
-   * @returns StreamingResult async iterable (JS wrapper makes this sync)
-   *
-   * Note: The native Rust layer returns a Promise, but the JavaScript wrapper
-   * in error-wrapper.js converts this to a synchronous return of AsyncIterable,
-   * per M4 spec requirement (Issue #347).
-   *
-   * @example
-   * ```javascript
-   * // No await on executeStreaming - returns AsyncIterable directly
-   * for await (const row of db.executeStreaming('SELECT * FROM large_table')) {
-   *   console.log(row.name);
-   * }
-   *
-   * // With custom config for memory constraints
-   * const config = { bufferSize: 256, chunkSize: 2500 };
-   * for await (const row of db.executeStreaming(query, config)) {
-   *   process(row);
-   * }
-   *
-   * // Early termination is safe - resources cleaned up automatically
-   * for await (const row of db.executeStreaming('SELECT * FROM huge_table')) {
-   *   if (row.id === targetId) {
-   *     break;
-   *   }
-   * }
-   * ```
-   */
-  executeStreaming(query: string, config?: StreamingConfig | undefined | null): Promise<StreamingResult>
-  /**
-   * Execute a CQL query and return results with native JavaScript types.
-   *
-   * This method returns native JavaScript types instead of JSON:
-   * - BigInt for bigint/counter columns (preserves 64-bit precision)
-   * - Buffer for blob columns
-   * - Date for timestamp/date columns
-   * - Set for set columns
-   * - Map for map columns
-   *
-   * @param query - CQL SELECT statement to execute
-   * @returns Promise resolving to NativeQueryResult with native typed rows
-   *
-   * @example
-   * ```javascript
-   * const result = await db.executeNative('SELECT * FROM users LIMIT 10');
-   * console.log(`Got ${result.rowCount} rows`);
-   * for (const row of result.rows) {
-   *   // row.id is a BigInt if the column is bigint type
-   *   // row.created_at is a Date if the column is timestamp
-   *   // row.data is a Buffer if the column is blob
-   *   console.log(row.name, typeof row.id);
-   * }
-   * ```
-   */
-  executeNative(query: string): Promise<{rows: object[], rowCount: number, executionTimeMs: number, columns: ColumnInfo[]}>
-  /**
-   * Prepare a CQL query for analysis.
-   *
-   * Returns a PreparedStatement that can be inspected for query plan
-   * information and statistics.
-   */
-  prepare(query: string): Promise<PreparedStatement>
-}
-/**
- * A prepared CQL statement.
- *
- * PreparedStatement holds a pre-parsed and planned query that can be
- * inspected for metadata and statistics. Created via Database.prepare().
- */
-export declare class PreparedStatement {
-  /** The original CQL query text. */
-  get query(): string
-  /**
-   * Number of parameters in the query.
-   * Returns count of placeholder parameters (?), clamped to u32::MAX.
-   */
-  get parameterCount(): number
-  /** Get statistics about this prepared statement. */
-  stats(): PreparedStatementStats
-  /** String representation of the prepared statement. */
-  toString(): string
-}
-/**
- * Streaming query result iterator.
- *
- * Yields rows one at a time via `next()` method which returns an AsyncTask.
- * JavaScript wrapper implements `Symbol.asyncIterator` for `for await...of` support.
- *
- * ## Resource Cleanup
- *
- * Resources are cleaned up when:
- * 1. All rows consumed (`next()` returns `done: true`)
- * 2. Iterator dropped (early break from loop triggers `return()`)
- * 3. `close()` called explicitly
- * 4. Error occurs
- *
- * ## Example (JavaScript)
- *
- * ```javascript
- * // No await on executeStreaming - it returns an AsyncIterable directly
- * for await (const row of db.executeStreaming('SELECT * FROM large_table')) {
- *   console.log(row);
- * }
- * ```
- */
-export declare class StreamingResult {
-  /**
-   * Get the next row from the stream.
-   *
-   * Returns an object matching JavaScript's iterator protocol:
-   * - `{ value: Row, done: false }` - More rows available
-   * - `{ value: undefined, done: true }` - Stream exhausted
-   *
-   * Errors are thrown as exceptions with structured error properties
-   * (code, category, isRecoverable).
-   *
-   * @returns Promise resolving to iterator result object
-   */
-  next(): Promise<unknown>
-  /**
-   * Number of rows received so far.
-   *
-   * This counter increases as rows are yielded from the stream.
-   * Useful for progress tracking.
-   *
-   * @returns Number of rows received
-   */
-  get rowsReceived(): number
-  /**
-   * Column metadata for the result set.
-   *
-   * Contains information about each column's name, type, and nullability.
-   * Available immediately after creating the streaming result.
-   *
-   * @returns Array of ColumnInfo objects
-   */
-  get columns(): Array<ColumnInfo>
-  /**
-   * Release resources early (synchronous).
-   *
-   * Called automatically when:
-   * - All rows are consumed
-   * - JavaScript iterator's `return()` is called (e.g., `break` from loop)
-   * - Error occurs during iteration
-   *
-   * Safe to call multiple times - subsequent calls are no-ops.
-   * This method is synchronous and does not need to be awaited.
-   */
-  close(): void
-}

package/index.js

@@ -1,318 +0,0 @@
-/* tslint:disable */
-/* eslint-disable */
-/* prettier-ignore */
-
-/* auto-generated by NAPI-RS */
-
-const { existsSync, readFileSync } = require('fs')
-const { join } = require('path')
-
-const { platform, arch } = process
-
-let nativeBinding = null
-let localFileExisted = false
-let loadError = null
-
-function isMusl() {
-  // For Node 10
-  if (!process.report || typeof process.report.getReport !== 'function') {
-    try {
-      const lddPath = require('child_process').execSync('which ldd').toString().trim()
-      return readFileSync(lddPath, 'utf8').includes('musl')
-    } catch (e) {
-      return true
-    }
-  } else {
-    const { glibcVersionRuntime } = process.report.getReport().header
-    return !glibcVersionRuntime
-  }
-}
-
-switch (platform) {
-  case 'android':
-    switch (arch) {
-      case 'arm64':
-        localFileExisted = existsSync(join(__dirname, 'cqlite-node.android-arm64.node'))
-        try {
-          if (localFileExisted) {
-            nativeBinding = require('./cqlite-node.android-arm64.node')
-          } else {
-            nativeBinding = require('@cqlite/node-android-arm64')
-          }
-        } catch (e) {
-          loadError = e
-        }
-        break
-      case 'arm':
-        localFileExisted = existsSync(join(__dirname, 'cqlite-node.android-arm-eabi.node'))
-        try {
-          if (localFileExisted) {
-            nativeBinding = require('./cqlite-node.android-arm-eabi.node')
-          } else {
-            nativeBinding = require('@cqlite/node-android-arm-eabi')
-          }
-        } catch (e) {
-          loadError = e
-        }
-        break
-      default:
-        throw new Error(`Unsupported architecture on Android ${arch}`)
-    }
-    break
-  case 'win32':
-    switch (arch) {
-      case 'x64':
-        localFileExisted = existsSync(
-          join(__dirname, 'cqlite-node.win32-x64-msvc.node')
-        )
-        try {
-          if (localFileExisted) {
-            nativeBinding = require('./cqlite-node.win32-x64-msvc.node')
-          } else {
-            nativeBinding = require('@cqlite/node-win32-x64-msvc')
-          }
-        } catch (e) {
-          loadError = e
-        }
-        break
-      case 'ia32':
-        localFileExisted = existsSync(
-          join(__dirname, 'cqlite-node.win32-ia32-msvc.node')
-        )
-        try {
-          if (localFileExisted) {
-            nativeBinding = require('./cqlite-node.win32-ia32-msvc.node')
-          } else {
-            nativeBinding = require('@cqlite/node-win32-ia32-msvc')
-          }
-        } catch (e) {
-          loadError = e
-        }
-        break
-      case 'arm64':
-        localFileExisted = existsSync(
-          join(__dirname, 'cqlite-node.win32-arm64-msvc.node')
-        )
-        try {
-          if (localFileExisted) {
-            nativeBinding = require('./cqlite-node.win32-arm64-msvc.node')
-          } else {
-            nativeBinding = require('@cqlite/node-win32-arm64-msvc')
-          }
-        } catch (e) {
-          loadError = e
-        }
-        break
-      default:
-        throw new Error(`Unsupported architecture on Windows: ${arch}`)
-    }
-    break
-  case 'darwin':
-    localFileExisted = existsSync(join(__dirname, 'cqlite-node.darwin-universal.node'))
-    try {
-      if (localFileExisted) {
-        nativeBinding = require('./cqlite-node.darwin-universal.node')
-      } else {
-        nativeBinding = require('@cqlite/node-darwin-universal')
-      }
-      break
-    } catch {}
-    switch (arch) {
-      case 'x64':
-        localFileExisted = existsSync(join(__dirname, 'cqlite-node.darwin-x64.node'))
-        try {
-          if (localFileExisted) {
-            nativeBinding = require('./cqlite-node.darwin-x64.node')
-          } else {
-            nativeBinding = require('@cqlite/node-darwin-x64')
-          }
-        } catch (e) {
-          loadError = e
-        }
-        break
-      case 'arm64':
-        localFileExisted = existsSync(
-          join(__dirname, 'cqlite-node.darwin-arm64.node')
-        )
-        try {
-          if (localFileExisted) {
-            nativeBinding = require('./cqlite-node.darwin-arm64.node')
-          } else {
-            nativeBinding = require('@cqlite/node-darwin-arm64')
-          }
-        } catch (e) {
-          loadError = e
-        }
-        break
-      default:
-        throw new Error(`Unsupported architecture on macOS: ${arch}`)
-    }
-    break
-  case 'freebsd':
-    if (arch !== 'x64') {
-      throw new Error(`Unsupported architecture on FreeBSD: ${arch}`)
-    }
-    localFileExisted = existsSync(join(__dirname, 'cqlite-node.freebsd-x64.node'))
-    try {
-      if (localFileExisted) {
-        nativeBinding = require('./cqlite-node.freebsd-x64.node')
-      } else {
-        nativeBinding = require('@cqlite/node-freebsd-x64')
-      }
-    } catch (e) {
-      loadError = e
-    }
-    break
-  case 'linux':
-    switch (arch) {
-      case 'x64':
-        if (isMusl()) {
-          localFileExisted = existsSync(
-            join(__dirname, 'cqlite-node.linux-x64-musl.node')
-          )
-          try {
-            if (localFileExisted) {
-              nativeBinding = require('./cqlite-node.linux-x64-musl.node')
-            } else {
-              nativeBinding = require('@cqlite/node-linux-x64-musl')
-            }
-          } catch (e) {
-            loadError = e
-          }
-        } else {
-          localFileExisted = existsSync(
-            join(__dirname, 'cqlite-node.linux-x64-gnu.node')
-          )
-          try {
-            if (localFileExisted) {
-              nativeBinding = require('./cqlite-node.linux-x64-gnu.node')
-            } else {
-              nativeBinding = require('@cqlite/node-linux-x64-gnu')
-            }
-          } catch (e) {
-            loadError = e
-          }
-        }
-        break
-      case 'arm64':
-        if (isMusl()) {
-          localFileExisted = existsSync(
-            join(__dirname, 'cqlite-node.linux-arm64-musl.node')
-          )
-          try {
-            if (localFileExisted) {
-              nativeBinding = require('./cqlite-node.linux-arm64-musl.node')
-            } else {
-              nativeBinding = require('@cqlite/node-linux-arm64-musl')
-            }
-          } catch (e) {
-            loadError = e
-          }
-        } else {
-          localFileExisted = existsSync(
-            join(__dirname, 'cqlite-node.linux-arm64-gnu.node')
-          )
-          try {
-            if (localFileExisted) {
-              nativeBinding = require('./cqlite-node.linux-arm64-gnu.node')
-            } else {
-              nativeBinding = require('@cqlite/node-linux-arm64-gnu')
-            }
-          } catch (e) {
-            loadError = e
-          }
-        }
-        break
-      case 'arm':
-        if (isMusl()) {
-          localFileExisted = existsSync(
-            join(__dirname, 'cqlite-node.linux-arm-musleabihf.node')
-          )
-          try {
-            if (localFileExisted) {
-              nativeBinding = require('./cqlite-node.linux-arm-musleabihf.node')
-            } else {
-              nativeBinding = require('@cqlite/node-linux-arm-musleabihf')
-            }
-          } catch (e) {
-            loadError = e
-          }
-        } else {
-          localFileExisted = existsSync(
-            join(__dirname, 'cqlite-node.linux-arm-gnueabihf.node')
-          )
-          try {
-            if (localFileExisted) {
-              nativeBinding = require('./cqlite-node.linux-arm-gnueabihf.node')
-            } else {
-              nativeBinding = require('@cqlite/node-linux-arm-gnueabihf')
-            }
-          } catch (e) {
-            loadError = e
-          }
-        }
-        break
-      case 'riscv64':
-        if (isMusl()) {
-          localFileExisted = existsSync(
-            join(__dirname, 'cqlite-node.linux-riscv64-musl.node')
-          )
-          try {
-            if (localFileExisted) {
-              nativeBinding = require('./cqlite-node.linux-riscv64-musl.node')
-            } else {
-              nativeBinding = require('@cqlite/node-linux-riscv64-musl')
-            }
-          } catch (e) {
-            loadError = e
-          }
-        } else {
-          localFileExisted = existsSync(
-            join(__dirname, 'cqlite-node.linux-riscv64-gnu.node')
-          )
-          try {
-            if (localFileExisted) {
-              nativeBinding = require('./cqlite-node.linux-riscv64-gnu.node')
-            } else {
-              nativeBinding = require('@cqlite/node-linux-riscv64-gnu')
-            }
-          } catch (e) {
-            loadError = e
-          }
-        }
-        break
-      case 's390x':
-        localFileExisted = existsSync(
-          join(__dirname, 'cqlite-node.linux-s390x-gnu.node')
-        )
-        try {
-          if (localFileExisted) {
-            nativeBinding = require('./cqlite-node.linux-s390x-gnu.node')
-          } else {
-            nativeBinding = require('@cqlite/node-linux-s390x-gnu')
-          }
-        } catch (e) {
-          loadError = e
-        }
-        break
-      default:
-        throw new Error(`Unsupported architecture on Linux: ${arch}`)
-    }
-    break
-  default:
-    throw new Error(`Unsupported OS: ${platform}, architecture: ${arch}`)
-}
-
-if (!nativeBinding) {
-  if (loadError) {
-    throw loadError
-  }
-  throw new Error(`Failed to load native binding`)
-}
-
-const { Database, PreparedStatement, StreamingResult, version } = nativeBinding
-
-module.exports.Database = Database
-module.exports.PreparedStatement = PreparedStatement
-module.exports.StreamingResult = StreamingResult
-module.exports.version = version