@cqlite/node 0.3.1-rc1

package/lib/index.js

@@ -0,0 +1,102 @@
+/**
+ * CQLite Node.js bindings entry point.
+ *
+ * This module wraps the native bindings with enhanced error handling
+ * that provides structured error properties (code, category, isRecoverable).
+ *
+ * @example
+ * ```javascript
+ * const { Database, version } = require('@cqlite/node');
+ *
+ * try {
+ *   const db = await Database.open('/path/to/data', {
+ *     schema: '/path/to/schema.cql'
+ *   });
+ *   const result = await db.execute('SELECT * FROM users LIMIT 10');
+ *   console.log(`Got ${result.rowCount} rows`);
+ *   await db.close();
+ * } catch (e) {
+ *   console.log('Error code:', e.code);       // e.g., "IO", "SCHEMA", "QUERY"
+ *   console.log('Category:', e.category);     // e.g., "System", "Schema"
+ *   console.log('Recoverable:', e.isRecoverable);
+ * }
+ * ```
+ */
+
+const nativeBinding = require('../index.js');
+const { createWrappedDatabase } = require('./error-wrapper.js');
+
+/**
+ * PreparedStatement wraps a native PreparedStatement with type consistency.
+ *
+ * Ensures estimatedRows in stats() is always BigInt (Issue #351).
+ * Users get this via Database.prepare() - direct construction not supported.
+ *
+ * Issue #351: Stats fields typed as bigint but runtime returns number
+ * Issue #352: PreparedStatement not exported at runtime but TypeScript declares it
+ */
+class PreparedStatement {
+  /**
+   * @private
+   * @param {Object} nativeStmt - The native PreparedStatement from Rust
+   */
+  constructor(nativeStmt) {
+    this._native = nativeStmt;
+  }
+
+  /** The original CQL query text. */
+  get query() {
+    return this._native.query;
+  }
+
+  /** Number of parameters in the query. */
+  get parameterCount() {
+    return this._native.parameterCount;
+  }
+
+  /**
+   * Get statistics about the prepared query.
+   * @returns {Object} PreparedStatementStats with estimatedRows as bigint
+   */
+  stats() {
+    const nativeStats = this._native.stats();
+    return {
+      parameterCount: nativeStats.parameterCount,
+      planType: nativeStats.planType,
+      estimatedCost: nativeStats.estimatedCost,
+      estimatedRows: BigInt(nativeStats.estimatedRows),
+      cacheFriendly: nativeStats.cacheFriendly,
+    };
+  }
+
+  /**
+   * Return a string representation of this prepared statement.
+   * @returns {string} String representation
+   */
+  toString() {
+    return this._native.toString();
+  }
+}
+
+/**
+ * Wrap a native PreparedStatement to ensure type consistency.
+ *
+ * @private
+ * @param {Object} nativeStmt - The native PreparedStatement from Rust
+ * @returns {PreparedStatement} Wrapped PreparedStatement instance
+ */
+function wrapPreparedStatement(nativeStmt) {
+  return new PreparedStatement(nativeStmt);
+}
+
+// Create wrapped Database class with enhanced error handling
+const Database = createWrappedDatabase(nativeBinding.Database, wrapPreparedStatement);
+
+// Re-export version function
+const { version } = nativeBinding;
+
+module.exports = {
+  Database,
+  PreparedStatement,
+  version,
+};

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@cqlite/node",
+  "version": "0.3.1-rc1",
+  "description": "Node.js bindings for CQLite - read Apache Cassandra 5.0 SSTables without cluster dependencies",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "napi": {
+    "binaryName": "cqlite-node",
+    "targets": [
+      "x86_64-apple-darwin",
+      "aarch64-apple-darwin",
+      "x86_64-unknown-linux-gnu",
+      "aarch64-unknown-linux-gnu",
+      "x86_64-pc-windows-msvc"
+    ]
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "lib",
+    "*.node",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "scripts": {
+    "build": "napi build --platform --release",
+    "build:debug": "napi build --platform",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "test:parity": "jest parity.test.js --testTimeout=60000",
+    "typecheck": "tsc --noEmit -p examples/tsconfig.json",
+    "examples": "ts-node examples/basic-query.ts",
+    "prepublishOnly": "echo 'Skipping napi prepublish - artifacts handled by CI workflow'"
+  },
+  "devDependencies": {
+    "@napi-rs/cli": "^3.5.1",
+    "@types/node": "^20.0.0",
+    "jest": "^29.7.0",
+    "ts-node": "^10.9.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">= 18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pmcfadin/cqlite.git",
+    "directory": "bindings/node"
+  },
+  "license": "MIT OR Apache-2.0",
+  "keywords": [
+    "cassandra",
+    "sstable",
+    "database",
+    "cql",
+    "cqlite"
+  ],
+  "author": "CQLite Team",
+  "homepage": "https://github.com/pmcfadin/cqlite#readme",
+  "bugs": {
+    "url": "https://github.com/pmcfadin/cqlite/issues"
+  }
+}