@cqlite/node 0.3.1-rc1

package/README.md

@@ -0,0 +1,252 @@
+# @cqlite/node
+
+Node.js bindings for [CQLite](https://github.com/pmcfadin/cqlite) - a high-performance library for reading Apache Cassandra 5.0 SSTable files locally, without requiring a running Cassandra cluster.
+
+## Installation
+
+```bash
+npm install @cqlite/node
+```
+
+## Quick Start
+
+```typescript
+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');
+for (const row of result.rows) {
+  console.log(row.name);
+}
+
+await db.close();
+```
+
+## Features
+
+- **Zero cluster dependency** - Read SSTable files directly from disk
+- **Full CQL type support** - All primitive types, collections, UDTs, and frozen types
+- **Native JavaScript types** - BigInt, Date, Buffer, Set, Map via `executeNative()`
+- **Memory-efficient streaming** - Configure buffer sizes for large datasets
+- **Thread-safe** - Safe concurrent access from multiple workers
+- **Cross-platform** - Linux (x86_64, ARM64), macOS (Intel, Apple Silicon), Windows
+
+## Supported Platforms
+
+| Platform | Architecture | Status |
+|----------|--------------|--------|
+| Linux | x86_64 | ✅ |
+| Linux | ARM64 | ✅ |
+| macOS | Intel (x86_64) | ✅ |
+| macOS | Apple Silicon | ✅ |
+| Windows | x64 | ✅ |
+
+## Requirements
+
+- Node.js 18+
+- Cassandra 5.0 SSTable files
+
+## API Reference
+
+### Opening a Database
+
+```typescript
+import { Database } from '@cqlite/node';
+
+// With schema file
+const db = await Database.open('/path/to/sstables', {
+  schema: '/path/to/schema.cql',
+});
+
+// Always close when done
+await db.close();
+```
+
+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');
+for (const row of result.rows) {
+  console.log(row);
+}
+
+// With LIMIT
+const limited = await db.execute('SELECT name, age FROM users LIMIT 100');
+
+// Access query metadata
+console.log(`Rows returned: ${result.rowCount}`);
+console.log(`Execution time: ${result.executionTimeMs}ms`);
+console.log(`Columns: ${result.columns.map(c => c.name).join(', ')}`);
+```
+
+### Native Types with executeNative()
+
+Use `executeNative()` to get native JavaScript types instead of JSON-serializable values:
+
+```typescript
+const result = await db.executeNative('SELECT * FROM keyspace.table');
+for (const row of result.rows) {
+  // BigInt for CQL bigint/varint
+  const balance: bigint = row.balance;
+
+  // Date for CQL timestamp
+  const created: Date = row.created;
+
+  // Buffer for CQL blob
+  const data: Buffer = row.blob_data;
+
+  // Set for CQL set
+  const tags: Set<string> = row.tags;
+
+  // Map for CQL map
+  const metadata: Map<string, string> = row.metadata;
+}
+```
+
+### JSON Encoding (execute method)
+
+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:
+
+```typescript
+// Using execute() - hex encoding (deprecated)
+const result = await db.execute('SELECT amount FROM transactions');
+console.log(result.rows[0].amount);
+// Varint: "0x7f" (127), "0xff" (-1), "0x0100" (256)
+// Decimal: "decimal:2:0x7b" (1.23), "decimal:2:0xee29" (-45.67)
+
+// Using executeNative() - proper types (recommended)
+const native = await db.executeNative('SELECT amount FROM transactions');
+console.log(native.rows[0].amount);
+// Varint: 127n (BigInt)
+// Decimal: "1.23" (human-readable string)
+```
+
+**Hex Format Details:**
+- `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.
+
+### Column Metadata
+
+Each query result includes column information:
+
+```typescript
+const result = await db.execute('SELECT * FROM keyspace.table');
+
+for (const col of result.columns) {
+  console.log(`${col.name}: ${col.dataType}`);
+  console.log(`  nullable: ${col.nullable}`);
+  console.log(`  position: ${col.position}`);
+}
+```
+
+### Database Statistics
+
+```typescript
+const stats = await db.getStats();
+console.log(`SSTables: ${stats.totalSstables}`);
+console.log(`Total rows: ${stats.totalRows}`);
+console.log(`Memory: ${stats.memoryUsedBytes} bytes`);
+```
+
+### Error Handling
+
+All errors include structured metadata for programmatic handling:
+
+```typescript
+import { Database } from '@cqlite/node';
+
+try {
+  const db = await Database.open('/path/to/data');
+  const result = await db.execute('SELECT * FROM keyspace.table');
+} catch (e) {
+  // Error code for programmatic handling
+  console.log(`Code: ${e.code}`);        // 'IO', 'SCHEMA', 'QUERY', 'PARSE', etc.
+
+  // Error category
+  console.log(`Category: ${e.category}`); // 'System', 'Schema', 'Query', etc.
+
+  // Whether the operation can be retried
+  console.log(`Recoverable: ${e.isRecoverable}`);
+
+  // Original error message
+  console.log(`Message: ${e.message}`);
+}
+```
+
+**Error Codes:**
+
+| Code | Category | Description | Recoverable |
+|------|----------|-------------|-------------|
+| `IO` | System | File system errors | Yes |
+| `SCHEMA` | Schema | Schema parsing/validation | No |
+| `QUERY` | Query | Query execution failures | No |
+| `PARSE` | Data | CQL syntax errors | No |
+| `CONFIG` | Configuration | Invalid configuration | No |
+| `STORAGE` | Storage | Storage engine errors | No |
+| `NOT_FOUND` | NotFound | Table/resource not found | No |
+| `INVALID_INPUT` | Logic | Invalid operation (e.g., closed db) | No |
+
+## Type Conversions
+
+CQL types are automatically converted to JavaScript types:
+
+| CQL Type | JavaScript Type | Notes |
+|----------|-----------------|-------|
+| `text`, `varchar`, `ascii` | `string` | |
+| `int`, `smallint`, `tinyint` | `number` | |
+| `bigint`, `varint`*, `counter` | `bigint` | via `executeNative()` |
+| `float`, `double` | `number` | |
+| `decimal`* | `string` | Preserves precision |
+| `boolean` | `boolean` | |
+| `blob` | `Buffer` | via `executeNative()` |
+| `timestamp` | `Date` | via `executeNative()` |
+| `date` | `Date` | via `executeNative()` |
+| `time` | `bigint` | Nanoseconds since midnight, via `executeNative()` |
+| `duration` | `object` | `{ months, days, nanos }` |
+| `uuid`, `timeuuid` | `string` | Lowercase formatted |
+| `inet` | `string` | IP address string |
+| `list<T>` | `T[]` | |
+| `set<T>` | `Set<T>` | via `executeNative()` |
+| `map<K,V>` | `Map<K,V>` | via `executeNative()` |
+| `tuple<...>` | `[...]` | Array |
+| `frozen<T>` | Inner type | Unwrapped |
+| UDT | `object` | With `_type` and `_keyspace` fields |
+
+\* **Note:** With `execute()`, `varint` returns `"0x{hex}"` and `decimal` returns `"decimal:{scale}:0x{hex}"`.
+Use `executeNative()` for human-readable formats.
+
+## Examples
+
+See the [examples/](examples/) directory for complete working examples:
+
+- [basic-query.ts](examples/basic-query.ts) - Simple SELECT queries
+- [type-handling.ts](examples/type-handling.ts) - Working with CQL types
+- [error-handling.ts](examples/error-handling.ts) - Error handling patterns
+- [streaming.ts](examples/streaming.ts) - Large result handling
+- [performance.ts](examples/performance.ts) - Memory-optimized usage
+
+## Resources
+
+- [TypeScript Definitions](lib/index.d.ts) - Complete API type hints
+- [Main Project README](../../README.md) - CQLite project overview
+- [Issue Tracker](https://github.com/pmcfadin/cqlite/issues) - Report bugs or request features
+
+## License
+
+MIT OR Apache-2.0
+
+## Links
+
+- [GitHub Repository](https://github.com/pmcfadin/cqlite)
+- [npm Package](https://www.npmjs.com/package/@cqlite/node)
+- [Documentation](https://github.com/pmcfadin/cqlite/tree/main/docs)

package/index.js

@@ -0,0 +1,318 @@
+/* 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