@cqlite/node 0.3.1-rc1 → 0.3.1-rc5

package/index.d.ts

@@ -0,0 +1,413 @@
+/* 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cqlite/node",
-  "version": "0.3.1-rc1",
+  "version": "0.3.1-rc5",
   "description": "Node.js bindings for CQLite - read Apache Cassandra 5.0 SSTables without cluster dependencies",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -49,7 +49,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/pmcfadin/cqlite.git",
+    "url": "git+https://github.com/pmcfadin/cqlite.git",
     "directory": "bindings/node"
   },
   "license": "MIT OR Apache-2.0",