@cqlite/node 0.12.0 → 0.14.0

package/README.md

@@ -16,8 +16,8 @@ import { Database } from '@cqlite/node';
 // Open a database with schema
 const db = await Database.open('path/to/sstables', { schema: 'schema.cql' });
 
-// Execute queries
-const result = await db.execute('SELECT * FROM keyspace.table LIMIT 10');
+// Execute queries (executeNative() returns native JS types with full precision)
+const result = await db.executeNative('SELECT * FROM keyspace.table LIMIT 10');
 for (const row of result.rows) {
   console.log(row.name);
 }
@@ -25,6 +25,20 @@ for (const row of result.rows) {
 await db.close();
 ```
 
+> **⚠️ Warning: `execute()` is deprecated and will be removed in the next major.**
+> Prefer `executeNative()`. `execute()` returns **lossy** legacy JSON encodings:
+> - `blob` → base64 **string** (not a `Buffer`)
+> - `timestamp` → ISO-8601 **string** (not a `Date`)
+> - `varint` → `"0x{hex}"` **string**
+> - `decimal` → `"decimal:{scale}:0x{hex}"` **string**
+> - `date`/`time` → **number** (days-since-epoch / nanoseconds-since-midnight)
+>
+> It is also slower (JSON off-loop, then JS on-loop — a double conversion).
+> Calling `execute()` emits a one-time `DeprecationWarning`. Use `executeNative()`
+> for native types (`BigInt`, `Buffer`, `Date`, `Set`, `Map`) with full fidelity.
+> (`bigint`/`counter` currently come back as an exact `BigInt` on this napi build,
+> so they are not presently rounded — but `execute()` is unsupported regardless.)
+
 ## Features
 
 - **Zero cluster dependency** - Read SSTable files directly from disk
@@ -70,14 +84,14 @@ The `close()` method is idempotent - safe to call multiple times.
 ### Executing Queries
 
 ```typescript
-// Simple query - returns JSON-serializable values
-const result = await db.execute('SELECT * FROM keyspace.table');
+// Simple query - executeNative() returns native JS types with full precision
+const result = await db.executeNative('SELECT * FROM keyspace.table');
 for (const row of result.rows) {
   console.log(row);
 }
 
 // With LIMIT
-const limited = await db.execute('SELECT name, age FROM users LIMIT 100');
+const limited = await db.executeNative('SELECT name, age FROM users LIMIT 100');
 
 // Access query metadata
 console.log(`Rows returned: ${result.rowCount}`);
@@ -85,6 +99,9 @@ console.log(`Execution time: ${result.executionTimeMs}ms`);
 console.log(`Columns: ${result.columns.map(c => c.name).join(', ')}`);
 ```
 
+> Prefer `executeNative()` over the deprecated `execute()` — see the warning at
+> the top of this README for the precision/encoding hazards of `execute()`.
+
 ### Native Types with executeNative()
 
 Use `executeNative()` to get native JavaScript types instead of JSON-serializable values:
@@ -109,7 +126,13 @@ for (const row of result.rows) {
 }
 ```
 
-### JSON Encoding (execute method)
+### JSON Encoding (deprecated `execute()` method)
+
+> **⚠️ Deprecated — removed in the next major.** `execute()` returns lossy legacy
+> JSON encodings and is slower than `executeNative()`. In particular blob comes
+> back as a base64 string, timestamp as an ISO-8601 string, and varint/decimal
+> as bespoke non-round-trippable strings. This section documents the encoding for
+> the few callers that still depend on it; new code should use `executeNative()`.
 
 The `execute()` method returns JSON-serializable values. For most types this works intuitively,
 but `varint` and `decimal` types use a hex-based encoding to preserve arbitrary precision:
@@ -132,15 +155,16 @@ console.log(native.rows[0].amount);
 - `varint`: `"0x{hex}"` - Two's complement big-endian hex encoding
 - `decimal`: `"decimal:{scale}:0x{hex}"` - Scale (decimal places) + hex-encoded unscaled value
 
-**Recommendation:** Use `executeNative()` for most applications. The `execute()` method is
-primarily for JSON serialization scenarios where you need raw, reversible encoding.
+**Recommendation:** Use `executeNative()`. The `execute()` method is deprecated
+(removed in the next major); its JSON encoding is lossy (blob/timestamp/varint/
+decimal come back as bespoke strings) and it is slower than `executeNative()`.
 
 ### Column Metadata
 
 Each query result includes column information:
 
 ```typescript
-const result = await db.execute('SELECT * FROM keyspace.table');
+const result = await db.executeNative('SELECT * FROM keyspace.table');
 
 for (const col of result.columns) {
   console.log(`${col.name}: ${col.dataType}`);
@@ -158,6 +182,78 @@ console.log(`Total rows: ${stats.totalRows}`);
 console.log(`Memory: ${stats.memoryUsedBytes} bytes`);
 ```
 
+### Refreshing SSTables (v0.13)
+
+If Cassandra (or another process) writes new SSTables while your `Database` handle
+is open, call `refresh()` to re-discover them. Refresh is **explicit-only** (CQLite
+never rescans behind your back) and **atomic / fail-closed**: if any newly found
+generation fails to open, the swap is rolled back and the handle keeps serving the
+prior, consistent set of readers.
+
+```typescript
+// ... time passes; Cassandra flushes/compacts new SSTables to disk ...
+
+const report = await db.refresh();
+console.log(`Tables scanned:  ${report.tablesScanned}`);
+console.log(`Readers added:   ${report.readersAdded}`);
+console.log(`Readers removed: ${report.readersRemoved}`);
+
+// Subsequent queries see the newly discovered data
+const result = await db.executeNative('SELECT * FROM keyspace.table');
+```
+
+`refresh(): Promise<RefreshReport>` resolves to a `RefreshReport` with the numeric
+fields `tablesScanned`, `readersAdded`, and `readersRemoved`.
+
+### Result Byte Budget (v0.13)
+
+Non-streaming queries are bounded by a result-size budget of **64 MiB** by default.
+When the materialized result's running byte estimate exceeds the budget, the query
+rejects with a `CqliteError` whose `code === 'QUERY'`, directing you to add a
+`LIMIT` clause or use `executeStreaming()`. Streaming queries are **not** subject
+to this budget.
+
+```typescript
+try {
+  const result = await db.executeNative('SELECT * FROM keyspace.big_table');
+  for (const row of result.rows) {
+    process(row);
+  }
+} catch (e) {
+  if (e.code === 'QUERY') {
+    // Result exceeded the 64 MiB byte budget — add a LIMIT or stream instead
+    for await (const row of db.executeStreaming('SELECT * FROM keyspace.big_table')) {
+      process(row);
+    }
+  } else {
+    throw e;
+  }
+}
+```
+
+### OpenTelemetry Tracing (v0.13)
+
+CQLite can emit OpenTelemetry traces when built with the `observability` Cargo
+feature; without that feature the configuration is accepted but is a no-op. Pass an
+`otel` option to `Database.open()`:
+
+```typescript
+const db = await Database.open('path/to/sstables', {
+  schema: 'schema.cql',
+  otel: {
+    enabled: true,                       // default false
+    endpoint: 'http://localhost:4317',   // default 'http://localhost:4317'
+    protocol: 'grpc',                    // 'grpc' (default) or 'http'
+    serviceName: 'cqlite',               // default 'cqlite'
+    serviceVersion: '0.13.0',            // default: package version
+    samplingRatio: 1.0,                  // default 1.0
+    timeoutMs: 10000,                    // default 10000
+  },
+});
+```
+
+Options are layered over the `CQLITE_OTEL_*` environment variables.
+
 ### Error Handling
 
 All errors include structured metadata for programmatic handling:
@@ -167,7 +263,7 @@ import { Database } from '@cqlite/node';
 
 try {
   const db = await Database.open('/path/to/data');
-  const result = await db.execute('SELECT * FROM keyspace.table');
+  const result = await db.executeNative('SELECT * FROM keyspace.table');
 } catch (e) {
   // Error code for programmatic handling
   console.log(`Code: ${e.code}`);        // 'IO', 'SCHEMA', 'QUERY', 'PARSE', etc.
@@ -240,11 +336,11 @@ const db = await Database.open('path/to/sstables', {
 });
 
 // Write rows via CQL INSERT, UPDATE, or DELETE
-await db.execute(
+await db.executeNative(
   "INSERT INTO test_basic.simple_table (id, name, age) " +
   "VALUES (22222222-2222-2222-2222-222222222222, 'Bob', 25)"
 );
-await db.execute(
+await db.executeNative(
   "UPDATE test_basic.simple_table SET age = 26 " +
   "WHERE id = 22222222-2222-2222-2222-222222222222"
 );
@@ -273,7 +369,8 @@ await db.close();
 
 | Method / Property | Description |
 |-------------------|-------------|
-| `db.execute(cql)` | Execute a CQL INSERT, UPDATE, or DELETE statement |
+| `db.executeNative(cql)` | Execute a CQL INSERT, UPDATE, or DELETE statement (recommended) |
+| `db.execute(cql)` | **Deprecated** (removed next major; emits a `DeprecationWarning`). Same DML behavior as `executeNative()`, but lossy for SELECT — use `executeNative()` |
 | `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` |
@@ -297,6 +394,15 @@ See the [examples/](examples/) directory for complete working examples:
 - [streaming.ts](examples/streaming.ts) - Large result handling
 - [performance.ts](examples/performance.ts) - Memory-optimized usage
 
+> **Streaming concurrency caveat:** `executeStreaming()` fetches each batch of
+> `K = bufferSize` rows on a libuv threadpool thread, so N concurrent streams can
+> each occupy a libuv threadpool thread for the duration of a batch fetch. Heavy
+> concurrent `fs`/`crypto` work in the same process may see added latency until
+> the follow-up ([#1901](https://github.com/pmcfadin/cqlite/issues/1901)) moves
+> streaming off the libuv pool onto the tokio runtime. If an error occurs
+> mid-stream, rows already read in the in-flight batch (up to `bufferSize`) are
+> not delivered — the iterator rejects with the error (errors are terminal).
+
 ## Resources
 
 - [TypeScript Definitions](lib/index.d.ts) - Complete API type hints

package/lib/error-wrapper.js

@@ -95,6 +95,89 @@ function wrapAsync(fn) {
   };
 }
 
+/**
+ * Build an AsyncIterator that yields ONE row per `next()` while fetching rows
+ * from the native stream in BATCHES (issue #1443).
+ *
+ * The native `StreamingResult.next()` returns `{ rows: Array<Row>, done }` — a
+ * whole batch per AsyncTask/`block_on` (K == the stream's `bufferSize`), instead
+ * of one row per task. This wrapper buffers that batch and drains it one row at
+ * a time, so the public per-row `for await ... of` contract is UNCHANGED
+ * (consumers still see exactly one row per iteration; batching is invisible).
+ * Amortising dispatch over K rows both raises throughput and stops a busy stream
+ * from monopolising libuv's small (default 4) threadpool and starving concurrent
+ * `fs`/`crypto` work.
+ *
+ * @param {() => Promise<{rows: Array<Object>, done: boolean}>} refill
+ *   Fetches the next batch from the native stream. May throw (already enhanced).
+ * @param {(yielded: number) => (void|Promise<void>)} onReturn
+ *   Invoked on early termination (`return()`/`break`) to close the native
+ *   stream. Receives the exact number of rows this iterator YIELDED to the
+ *   consumer, so the native span records rows-yielded rather than the whole
+ *   fetched batch (the un-yielded tail of the last batch is discarded here on
+ *   early break). See issue #1443.
+ * @param {() => boolean} [isCancelled]
+ *   Optional predicate checked before each `next()`; when it returns true the
+ *   iterator discards any buffered rows and reports `done` immediately. This is
+ *   how an external `close()` on the stream object takes effect even though the
+ *   batch buffer lives in this iterator's closure.
+ * @returns {AsyncIterator} Iterator yielding one row per `next()`.
+ */
+function batchedAsyncIterator(refill, onReturn, isCancelled) {
+  let buffer = [];
+  let bufIdx = 0;
+  let exhausted = false;
+  // Exact count of rows YIELDED to the consumer (one per `next()` that returns
+  // a value). Passed to `onReturn` on early break so the native span records
+  // rows-yielded, not the whole fetched batch (issue #1443).
+  let yielded = 0;
+  return {
+    async next() {
+      // Honour an external close(): discard buffered rows and end immediately.
+      if (isCancelled && isCancelled()) {
+        buffer = [];
+        bufIdx = 0;
+        exhausted = true;
+        return { value: undefined, done: true };
+      }
+      // Drain the buffered batch first — no native call, no threadpool dispatch.
+      if (bufIdx < buffer.length) {
+        yielded++;
+        return { value: buffer[bufIdx++], done: false };
+      }
+      if (exhausted) {
+        return { value: undefined, done: true };
+      }
+      // Refill: exactly ONE AsyncTask/block_on fetches a whole batch.
+      const batch = await refill();
+      buffer = (batch && batch.rows) || [];
+      bufIdx = 0;
+      // An empty batch always signals exhaustion (native `Done`); a `done` flag
+      // is honoured defensively too. A non-empty batch may still be the final
+      // one — the next refill then observes the empty batch and ends the stream.
+      if (!batch || batch.done || buffer.length === 0) {
+        exhausted = true;
+      }
+      if (bufIdx < buffer.length) {
+        yielded++;
+        return { value: buffer[bufIdx++], done: false };
+      }
+      return { value: undefined, done: true };
+    },
+    async return() {
+      // Early `break`/`return()`: discard any un-yielded buffered rows and close
+      // the native stream (which terminates the producer and finalises the
+      // span). Pass the exact rows yielded so the span is not over-counted by
+      // the discarded buffer tail (issue #1443).
+      buffer = [];
+      bufIdx = 0;
+      exhausted = true;
+      await onReturn(yielded);
+      return { value: undefined, done: true };
+    },
+  };
+}
+
 /**
  * Create an async iterable wrapper around a native StreamingResult.
  *
@@ -105,6 +188,7 @@ function wrapAsync(fn) {
  * @returns {Object} An async iterable object with streaming functionality
  */
 function createAsyncIterator(nativeStream) {
+  let closed = false;
   return {
     /**
      * Number of rows received so far.
@@ -127,42 +211,70 @@ function createAsyncIterator(nativeStream) {
      * Safe to call multiple times.
      */
     close() {
+      closed = true;
       return nativeStream.close();
     },
 
     /**
      * Implement Symbol.asyncIterator for `for await...of` support.
+     *
+     * Yields one row per iteration while fetching in batches (issue #1443).
      * @returns {AsyncIterator}
      */
     [Symbol.asyncIterator]() {
-      return {
-        /**
-         * Get the next row from the stream.
-         * @returns {Promise<{value: Object|undefined, done: boolean}>}
-         */
-        async next() {
+      return batchedAsyncIterator(
+        async () => {
           try {
-            const result = await nativeStream.next();
-            return result;
+            return await nativeStream.next();
           } catch (error) {
             throw enhanceError(error);
           }
         },
-
-        /**
-         * Handle early termination (e.g., break from loop).
-         * Called automatically by JavaScript runtime.
-         * @returns {Promise<{value: undefined, done: true}>}
-         */
-        async return() {
-          nativeStream.close();
-          return { value: undefined, done: true };
+        (yielded) => {
+          closed = true;
+          nativeStream.close(yielded);
         },
-      };
+        () => closed
+      );
     },
   };
 }
 
+/**
+ * Emit a one-time deprecation warning for the legacy `execute()` method.
+ *
+ * `execute()` returns lossy legacy JSON encodings — blob comes back as a base64
+ * string (not a Buffer), timestamp as an ISO-8601 string (not a Date), and
+ * varint/decimal in bespoke `"0x…"` / `"decimal:…"` strings no caller can
+ * round-trip (see index.d.ts). It also double-converts (JSON off-loop, then JS
+ * on-loop) so it is slower than `executeNative()`. It is deprecated and will be
+ * removed in the next major; `executeNative()` returns native types with full
+ * fidelity. We emit via `process.emitWarning(..., 'DeprecationWarning')` guarded
+ * by a module-level flag so it fires at most once per process, matching Node's
+ * own deprecation convention (issue #1457).
+ *
+ * @private
+ */
+let executeDeprecationWarned = false;
+function warnExecuteDeprecated() {
+  if (executeDeprecationWarned) {
+    return;
+  }
+  executeDeprecationWarned = true;
+  process.emitWarning(
+    "Database.execute() is deprecated and will be removed in the next major. " +
+      "It returns lossy legacy JSON encodings: blob becomes a base64 string " +
+      "(not a Buffer), timestamp an ISO-8601 string (not a Date), and " +
+      "varint/decimal bespoke non-round-trippable strings; it is also slower " +
+      "(double conversion). Use executeNative() for native types with full " +
+      "fidelity (BigInt, Buffer, Date, Set, Map).",
+    {
+      type: "DeprecationWarning",
+      code: "CQLITE_DEP0001",
+    }
+  );
+}
+
 /**
  * Create a wrapped Database class with enhanced error handling.
  *
@@ -187,6 +299,7 @@ function createWrappedDatabase(NativeDatabase, wrapPreparedStatement) {
     }
 
     async execute(query) {
+      warnExecuteDeprecated();
       try {
         const result = await this._native.execute(query);
         // For SELECT: rowsAffected = rowCount (alias, Issue #348).
@@ -229,6 +342,25 @@ function createWrappedDatabase(NativeDatabase, wrapPreparedStatement) {
       }
     }
 
+    /**
+     * Re-discover the data directory and apply changes to the held reader set.
+     *
+     * Newly present SSTable generations become queryable, removed generations
+     * stop being queried, and unchanged generations keep their warm parsed
+     * state. In-flight queries are unaffected; the refresh is atomic and
+     * fail-closed. See index.d.ts for the full contract (issue #1749).
+     *
+     * @returns {Promise<Object>} RefreshReport with tablesScanned, readersAdded, readersRemoved
+     * @throws {CqliteError} If the database is closed or a new generation fails to open
+     */
+    async refresh() {
+      try {
+        return await this._native.refresh();
+      } catch (error) {
+        throw enhanceError(error);
+      }
+    }
+
     async close() {
       try {
         return await this._native.close();
@@ -328,11 +460,16 @@ function createWrappedDatabase(NativeDatabase, wrapPreparedStatement) {
 
         /**
          * Implement Symbol.asyncIterator for `for await...of` support.
+         *
+         * Yields one row per iteration while the native stream is fetched in
+         * batches (issue #1443): each refill is a single AsyncTask/block_on that
+         * returns up to `bufferSize` rows, which are then drained one at a time.
+         * The per-row consumer contract is unchanged; batching is invisible.
          * @returns {AsyncIterator}
          */
         [Symbol.asyncIterator]() {
-          return {
-            async next() {
+          return batchedAsyncIterator(
+            async () => {
               try {
                 const stream = await ensureInitialized();
                 return await stream.next();
@@ -340,13 +477,13 @@ function createWrappedDatabase(NativeDatabase, wrapPreparedStatement) {
                 throw enhanceError(error);
               }
             },
-            async return() {
+            (yielded) => {
               closed = true;
               nativeStreamPromise = null;
-              nativeStream?.close();
-              return { value: undefined, done: true };
+              nativeStream?.close(yielded);
             },
-          };
+            () => closed
+          );
         },
       };
     }

package/lib/index.d.ts

@@ -200,19 +200,24 @@ export interface ColumnInfo {
  */
 export interface QueryResult {
   /**
-   * Result rows as JSON-serializable objects.
+   * Result rows as legacy JSON-serialized objects (returned by `execute()`).
    *
-   * Values are JSON-serialized versions of CQL types:
-   * - BigInt/Counter: number (may lose precision for values > 2^53)
-   * - Blob: base64 string
-   * - Timestamp: ISO 8601 string
-   * - Set/Map: Array representations
-   * - Varint: Hex string `"0x{hex}"` (e.g., `"0x7f"` for 127)
-   * - Decimal: String `"decimal:{scale}:0x{hex}"` (e.g., `"decimal:2:0x7b"` for 1.23)
+   * ⚠️ These values are lossy legacy JSON encodings of CQL types — see the
+   * hazards on {@link Database.execute}:
+   * - **Blob → base64 `string`** (not a `Buffer`).
+   * - **Timestamp → ISO-8601 `string`** (not a `Date`).
+   * - **Varint → hex `string` `"0x{hex}"`** (e.g., `"0x7f"` for 127).
+   * - **Decimal → `string` `"decimal:{scale}:0x{hex}"`** (e.g., `"decimal:2:0x7b"`).
+   * - **Date/Time → `number`** (days-since-epoch / nanoseconds-since-midnight).
+   * - Set/Map → Array representations.
    *
-   * For native types with full precision, use `executeNative()`.
+   * (BigInt/Counter are currently returned as an exact `BigInt` on this napi
+   * build, but `execute()` is deprecated and unsupported regardless.)
    *
-   * @deprecated The execute() method uses legacy JSON encoding. Use executeNative() for proper type fidelity.
+   * For native types with full fidelity, use `executeNative()`.
+   *
+   * @deprecated The execute() method uses lossy legacy JSON encoding and is
+   *   removed in the next major. Use executeNative() for proper type fidelity.
    */
   rows: Record<string, unknown>[];
 
@@ -374,6 +379,115 @@ export interface DatabaseOptions {
    * ```
    */
   writeDir?: string;
+
+  /**
+   * Enable automatic (STCS) size-tiered compaction for the write engine.
+   * Default: true. Set false to disable compaction — `maintenanceStep`
+   * then performs no merges (issue #1619).
+   */
+  autoCompaction?: boolean;
+
+  /**
+   * Memtable flush threshold in bytes for the write engine (issue #1620).
+   * When the in-memory memtable grows past this size, the write path
+   * (`execute`) awaits a real async flush to a new SSTable generation.
+   * Only meaningful when `writable` is true. Default: 64 MB (67108864 bytes).
+   */
+  flushThreshold?: number;
+
+  /**
+   * OpenTelemetry export options (epic #1031, issue #1040).
+   *
+   * When omitted, the `CQLITE_OTEL_*` environment variables are consulted.
+   * Telemetry stays disabled unless `enabled: true` is set (here or via env)
+   * AND the native addon was built with the `observability` Cargo feature.
+   *
+   * Observability is initialised **once per process** on the first
+   * `Database.open()`, so passing different `otel` options to a later open has
+   * no effect.
+   *
+   * @example
+   * ```typescript
+   * const db = await Database.open('/data', {
+   *   schema: 'schema.cql',
+   *   otel: { enabled: true, endpoint: 'http://collector:4317', protocol: 'grpc' },
+   * });
+   * ```
+   */
+  otel?: OtelOptions;
+
+  /**
+   * Incoming W3C `traceparent` header to parent this handle's per-call and
+   * per-stream spans under a remote trace (distributed-tracing propagation).
+   *
+   * Applied as the default parent for every `execute`, `executeNative`, and
+   * `executeStreaming` on the returned handle. Invalid/empty values are
+   * ignored. Only meaningful when telemetry is enabled and the addon was built
+   * with the `observability` feature.
+   *
+   * @example
+   * ```typescript
+   * const db = await Database.open('/data', {
+   *   schema: 'schema.cql',
+   *   otel: { enabled: true },
+   *   traceparent: '00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01',
+   * });
+   * ```
+   */
+  traceparent?: string;
+}
+
+/**
+ * OpenTelemetry export options for the Node.js bindings (epic #1031, issue
+ * #1040).
+ *
+ * Any field left unset falls back to the corresponding `CQLITE_OTEL_*`
+ * environment variable, then to the foundation default. Exporters are only
+ * installed when the effective config has `enabled: true` AND the native addon
+ * was built with the `observability` feature.
+ */
+export interface OtelOptions {
+  /**
+   * Master enable switch. Unset defers to `CQLITE_OTEL_ENABLED`, then `false`.
+   */
+  enabled?: boolean;
+
+  /**
+   * OTLP collector endpoint: a gRPC endpoint or HTTP base URL.
+   * Unset defers to `CQLITE_OTEL_ENDPOINT`, then `http://localhost:4317`.
+   */
+  endpoint?: string;
+
+  /**
+   * Wire protocol: `"grpc"` (default) or `"http"`. Unrecognised values are
+   * ignored (the default/env value is kept).
+   */
+  protocol?: string;
+
+  /**
+   * `service.name` resource attribute.
+   * Unset defers to `CQLITE_OTEL_SERVICE_NAME`, then `cqlite`.
+   */
+  serviceName?: string;
+
+  /**
+   * `service.version` resource attribute.
+   * Unset defers to `CQLITE_OTEL_SERVICE_VERSION`, then the crate version.
+   */
+  serviceVersion?: string;
+
+  /**
+   * Trace-ID-ratio sampling probability in `[0.0, 1.0]` (clamped; non-finite
+   * values fall back to full sampling).
+   * Unset defers to `CQLITE_OTEL_SAMPLING_RATIO`, then `1.0`.
+   */
+  samplingRatio?: number;
+
+  /**
+   * Exporter export timeout in milliseconds.
+   * Unset defers to `CQLITE_OTEL_TIMEOUT_MS`, then `10000`.
+   */
+  timeoutMs?: number;
 }
 
 // ============================================================================
@@ -465,6 +579,34 @@ export interface MaintenanceReport {
   pendingCompaction: boolean;
 }
 
+/**
+ * Report returned by `Database.refresh()`.
+ *
+ * Describes what an explicit directory refresh applied to the database's held
+ * SSTable reader set: newly present generations become queryable, removed
+ * generations stop being queried, and unchanged generations keep their warm
+ * parsed state (they are not re-parsed).
+ *
+ * @example
+ * ```typescript
+ * const report = await db.refresh();
+ * console.log(
+ *   `scanned ${report.tablesScanned} tables, ` +
+ *   `+${report.readersAdded}/-${report.readersRemoved} readers`
+ * );
+ * ```
+ */
+export interface RefreshReport {
+  /** Number of distinct logical tables present after the refresh. */
+  tablesScanned: number;
+
+  /** Number of SSTable generations newly opened and made queryable. */
+  readersAdded: number;
+
+  /** Number of SSTable generations dropped from the reader set. */
+  readersRemoved: number;
+}
+
 /**
  * Configuration for streaming query execution.
  *
@@ -649,7 +791,8 @@ export type ErrorCode =
   | 'CONSTRAINT'   // Constraint violations
   | 'TRANSACTION'  // Transaction errors
   | 'PLATFORM'     // Platform-specific errors (WASM)
-  | 'INTERNAL';    // Internal errors
+  | 'INTERNAL'     // Internal errors
+  | 'CANCELLED';   // Cooperative scan cancellation (issue #2264 — never 'IO')
 
 /**
  * Error category names for CQLite errors.
@@ -671,7 +814,8 @@ export type ErrorCategory =
   | 'Constraint'
   | 'Transaction'
   | 'Platform'
-  | 'Internal';
+  | 'Internal'
+  | 'Cancelled';
 
 /**
  * CQLite error interface.
@@ -831,24 +975,45 @@ export declare class Database {
   static open(dataDir: string, options?: DatabaseOptions): Promise<Database>;
 
   /**
-   * Execute a CQL query and return results as JSON-serializable values.
+   * Execute a CQL query and return results as legacy JSON-serialized values.
+   *
+   * **DEPRECATED — removed in the next major. Use {@link Database.executeNative} instead.**
+   *
+   * ## ⚠️ Lossy legacy encodings and correctness hazards
+   *
+   * `execute()` routes every value through a legacy JSON encoder. Several CQL
+   * types come back in a lossy or bespoke encoding that no caller can round-trip
+   * and that differs from the native type `executeNative()` returns:
    *
-   * Use this method when you need JSON-compatible output or don't need
-   * native JavaScript types. For native types with full precision,
-   * use `executeNative()` instead.
+   * - **`blob` → base64 `string`** (not a `Buffer`).
+   * - **`timestamp` → ISO-8601 `string`** (not a `Date`).
+   * - **`varint` → `"0x{hex}"` string.** Two's-complement big-endian hex.
+   *   Example: 127 -> `"0x7f"`, -1 -> `"0xff"`, 256 -> `"0x0100"`.
+   * - **`decimal` → `"decimal:{scale}:0x{hex}"` string.** Example: 1.23
+   *   (scale=2, unscaled=123) -> `"decimal:2:0x7b"`.
+   * - **`date` → `number`** (days since epoch); **`time` → `number`**
+   *   (nanoseconds since midnight).
    *
-   * ## Varint and Decimal Encoding
+   * It is also **slower** than `executeNative()`: it converts each value to JSON
+   * off the JS main thread, then converts that JSON to JS values on-loop — a
+   * double conversion `executeNative()` avoids.
    *
-   * This method uses hex-based encoding for arbitrary precision numbers:
-   * - **Varint**: `"0x{hex}"` - Two's complement big-endian hex encoding
-   *   - Example: 127 -> `"0x7f"`, -1 -> `"0xff"`, 256 -> `"0x0100"`
-   * - **Decimal**: `"decimal:{scale}:0x{hex}"` - Scale + hex-encoded unscaled value
-   *   - Example: 1.23 (scale=2, unscaled=123) -> `"decimal:2:0x7b"`
+   * NOTE on precision: with this napi build (BigInt support), `bigint`/`counter`
+   * are currently returned as an exact JS `BigInt`, so a value above 2^53 is
+   * **not** presently rounded. Do not rely on this — the encoding is legacy and
+   * unsupported; `executeNative()` is the contract. (Older docs claimed a >2^53
+   * rounding loss; that is not observed on the current binding — issue #1457.)
+   *
+   * `executeNative()` returns native types with full fidelity (`BigInt`,
+   * `Buffer`, `Date`, `Set`, `Map`) and is the supported path.
    *
    * @param query - CQL SELECT statement to execute
    * @returns Promise resolving to QueryResult with rows and metadata
    * @throws {CqliteError} If the query fails
-   * @deprecated Since 0.4.0. Use `executeNative()` for proper type fidelity.
+   * @deprecated Since 0.4.0; removed in the next major. Use `executeNative()`
+   *   for proper type fidelity — `execute()` returns blob/decimal/varint/
+   *   timestamp/date/time in lossy legacy encodings and is slower. Calling it
+   *   emits a one-time `DeprecationWarning`.
    *
    * @example
    * ```typescript
@@ -882,6 +1047,18 @@ export declare class Database {
    * - Native Buffer handling for binary data
    * - Native Set/Map operations
    *
+   * ## Performance: O(rows) work on the event-loop thread
+   *
+   * The result set is scanned off the event loop, but every row is materialized
+   * into a JS object on the event-loop thread (a napi `Env` is thread-bound, so
+   * this work cannot be moved off-loop). It is therefore O(rows) of synchronous
+   * on-loop work: a large result set will freeze timers, HTTP handlers, and
+   * other callbacks for the duration of the burst. Prefer
+   * {@link Database.executeStreaming} for result sets beyond ~a few thousand
+   * rows. Result sets larger than `CQLITE_NODE_MAX_NATIVE_ROWS` (default
+   * 100,000) are rejected with a typed error advising `executeStreaming`
+   * instead of freezing the loop (issue #1442).
+   *
    * @param query - CQL SELECT statement to execute
    * @returns Promise resolving to NativeQueryResult with native typed rows
    * @throws {CqliteError} If the query fails
@@ -917,6 +1094,35 @@ export declare class Database {
    */
   getStats(): Promise<DatabaseStats>;
 
+  /**
+   * Re-discover the data directory and apply changes to the held reader set.
+   *
+   * A `Database` is a snapshot at `open()`: a Cassandra flush/compaction (or a
+   * CQLite `--flush`) may add or remove SSTable generations under a warm handle,
+   * and those changes become queryable only after an explicit `refresh()`. This
+   * re-runs the same TOC/filename-based discovery `open()` used (no content
+   * sniffing, no heuristics) and applies the diff:
+   * - newly present generations become queryable,
+   * - removed generations stop being queried,
+   * - unchanged generations keep their warm parsed Index/Statistics/bloom state.
+   *
+   * In-flight queries are never affected: a scan already running completes
+   * against the pre-refresh set; a query issued after this Promise resolves sees
+   * the post-refresh set. The refresh is atomic and fail-closed — if any newly
+   * discovered generation fails to open (e.g. a corrupt `Statistics.db`), the
+   * Promise rejects and the previously held reader set is left unchanged.
+   *
+   * @returns Promise resolving to a RefreshReport with the applied counts
+   * @throws {CqliteError} If the database is closed or a new generation fails to open
+   *
+   * @example
+   * ```typescript
+   * const report = await db.refresh();
+   * console.log(`+${report.readersAdded}/-${report.readersRemoved} readers`);
+   * ```
+   */
+  refresh(): Promise<RefreshReport>;
+
   /**
    * Close the database and release resources.
    *
@@ -952,6 +1158,17 @@ export declare class Database {
    * - `bufferSize`: 1024 rows in flight (~1MB)
    * - `chunkSize`: 10,000 rows per fetch chunk (~10MB)
    *
+   * Concurrency caveat: each `next()` fetches a batch of `K = bufferSize` rows
+   * on a libuv threadpool thread, so N concurrent streams can each occupy a
+   * libuv threadpool thread for the duration of a batch fetch. Heavy concurrent
+   * `fs`/`crypto` work in the same process may therefore see added latency until
+   * the follow-up (cqlite#1901) lands, which moves streaming off the libuv pool
+   * onto the tokio runtime.
+   *
+   * Error caveat: if an error occurs mid-stream, rows already read in the
+   * in-flight batch (up to `bufferSize`) are not delivered — the iterator
+   * rejects with the error (errors are terminal).
+   *
    * @param query - CQL SELECT statement to execute
    * @param config - Optional StreamingConfig for buffer/chunk sizes
    * @returns StreamingResult async iterable (iteration triggers query execution)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cqlite/node",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Node.js bindings for CQLite - read Apache Cassandra 5.0 SSTables without cluster dependencies",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -16,7 +16,6 @@
   },
   "files": [
     "index.js",
-    "index.d.ts",
     "lib",
     "*.node",
     "README.md",
@@ -27,13 +26,13 @@
     "access": "public"
   },
   "scripts": {
-    "build": "napi build --platform --release --features write-support",
+    "build": "napi build --platform --profile release-unwind --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",
+    "test": "node --expose-gc ./node_modules/jest/bin/jest.js",
+    "test:watch": "node --expose-gc ./node_modules/jest/bin/jest.js --watch",
+    "test:coverage": "node --expose-gc ./node_modules/jest/bin/jest.js --coverage",
     "test:parity": "jest parity.test.js --testTimeout=60000",
     "typecheck": "tsc --noEmit -p examples/tsconfig.json",
     "examples": "ts-node examples/basic-query.ts",