|
| 1 | +# @sqliteai/sqlite-js |
| 2 | + |
| 3 | +[](https://www.npmjs.com/package/@sqliteai/sqlite-js) |
| 4 | +[](LICENSE.md) |
| 5 | + |
| 6 | +> SQLite JS extension packaged for Node.js |
| 7 | +
|
| 8 | +**SQLite JS** is a powerful extension that brings JavaScript capabilities to SQLite. With this extension, you can create custom SQLite functions, aggregates, window functions, and collation sequences using JavaScript code, allowing for flexible and powerful data manipulation directly within your SQLite database. |
| 9 | + |
| 10 | +## Features |
| 11 | + |
| 12 | +- ✅ **JavaScript UDFs** - Custom SQLite functions in JavaScript |
| 13 | +- ✅ **QuickJS Integration** - Fast JavaScript execution inside SQLite |
| 14 | +- ✅ **Cross-platform** - Works on macOS, Linux (glibc/musl), and Windows |
| 15 | +- ✅ **Zero configuration** - Automatically detects and loads the correct binary for your platform |
| 16 | +- ✅ **TypeScript native** - Full type definitions included |
| 17 | +- ✅ **Modern ESM + CJS** - Works with both ES modules and CommonJS |
| 18 | + |
| 19 | +## Installation |
| 20 | + |
| 21 | +```bash |
| 22 | +npm install @sqliteai/sqlite-js |
| 23 | +``` |
| 24 | + |
| 25 | +The package automatically downloads the correct native extension for your platform during installation. |
| 26 | + |
| 27 | +### Supported Platforms |
| 28 | + |
| 29 | +| Platform | Architecture | Package | |
| 30 | +|----------|-------------|---------| |
| 31 | +| macOS | ARM64 (Apple Silicon) | `@sqliteai/sqlite-js-darwin-arm64` | |
| 32 | +| macOS | x86_64 (Intel) | `@sqliteai/sqlite-js-darwin-x86_64` | |
| 33 | +| Linux | ARM64 (glibc) | `@sqliteai/sqlite-js-linux-arm64` | |
| 34 | +| Linux | ARM64 (musl/Alpine) | `@sqliteai/sqlite-js-linux-arm64-musl` | |
| 35 | +| Linux | x86_64 (glibc) | `@sqliteai/sqlite-js-linux-x86_64` | |
| 36 | +| Linux | x86_64 (musl/Alpine) | `@sqliteai/sqlite-js-linux-x86_64-musl` | |
| 37 | +| Windows | x86_64 | `@sqliteai/sqlite-js-win32-x86_64` | |
| 38 | + |
| 39 | +## sqlite-js API |
| 40 | + |
| 41 | +For detailed information on how to use the JS extension features, see the [main documentation](https://github.com/sqliteai/sqlite-js/blob/main/README.md). |
| 42 | + |
| 43 | +## Usage |
| 44 | + |
| 45 | +```typescript |
| 46 | +import { getExtensionPath } from '@sqliteai/sqlite-js'; |
| 47 | +import Database from 'better-sqlite3'; |
| 48 | + |
| 49 | +const db = new Database(':memory:'); |
| 50 | +db.loadExtension(getExtensionPath()); |
| 51 | + |
| 52 | +// Ready to use |
| 53 | +const version = db.prepare('SELECT js_version()').pluck().get(); |
| 54 | +console.log('JS extension version:', version); |
| 55 | +``` |
| 56 | + |
| 57 | +## Examples |
| 58 | + |
| 59 | +For complete, runnable examples, see the [sqlite-extensions-guide](https://github.com/sqliteai/sqlite-extensions-guide/tree/main/examples/node). |
| 60 | + |
| 61 | +These examples are generic and work with all SQLite extensions: `sqlite-vector`, `sqlite-sync`, `sqlite-js`, and `sqlite-ai`. |
| 62 | + |
| 63 | +## API Reference |
| 64 | + |
| 65 | +### `getExtensionPath(): string` |
| 66 | + |
| 67 | +Returns the absolute path to the SQLite JS extension binary for the current platform. |
| 68 | + |
| 69 | +**Returns:** `string` - Absolute path to the extension file (`.so`, `.dylib`, or `.dll`) |
| 70 | + |
| 71 | +**Throws:** `ExtensionNotFoundError` - If the extension binary cannot be found for the current platform |
| 72 | + |
| 73 | +**Example:** |
| 74 | +```typescript |
| 75 | +import { getExtensionPath } from '@sqliteai/sqlite-js'; |
| 76 | + |
| 77 | +const path = getExtensionPath(); |
| 78 | +// => '/path/to/node_modules/@sqliteai/sqlite-js-darwin-arm64/js.dylib' |
| 79 | +``` |
| 80 | + |
| 81 | +--- |
| 82 | + |
| 83 | +### `getExtensionInfo(): ExtensionInfo` |
| 84 | + |
| 85 | +Returns detailed information about the extension for the current platform. |
| 86 | + |
| 87 | +**Returns:** `ExtensionInfo` object with the following properties: |
| 88 | +- `platform: Platform` - Current platform identifier (e.g., `'darwin-arm64'`) |
| 89 | +- `packageName: string` - Name of the platform-specific npm package |
| 90 | +- `binaryName: string` - Filename of the binary (e.g., `'js.dylib'`) |
| 91 | +- `path: string` - Full path to the extension binary |
| 92 | + |
| 93 | +**Throws:** `ExtensionNotFoundError` - If the extension binary cannot be found |
| 94 | + |
| 95 | +**Example:** |
| 96 | +```typescript |
| 97 | +import { getExtensionInfo } from '@sqliteai/sqlite-js'; |
| 98 | + |
| 99 | +const info = getExtensionInfo(); |
| 100 | +console.log(`Running on ${info.platform}`); |
| 101 | +console.log(`Extension path: ${info.path}`); |
| 102 | +``` |
| 103 | + |
| 104 | +--- |
| 105 | + |
| 106 | +### `getCurrentPlatform(): Platform` |
| 107 | + |
| 108 | +Returns the current platform identifier. |
| 109 | + |
| 110 | +**Returns:** `Platform` - One of: |
| 111 | +- `'darwin-arm64'` - macOS ARM64 |
| 112 | +- `'darwin-x86_64'` - macOS x86_64 |
| 113 | +- `'linux-arm64'` - Linux ARM64 (glibc) |
| 114 | +- `'linux-arm64-musl'` - Linux ARM64 (musl) |
| 115 | +- `'linux-x86_64'` - Linux x86_64 (glibc) |
| 116 | +- `'linux-x86_64-musl'` - Linux x86_64 (musl) |
| 117 | +- `'win32-x86_64'` - Windows x86_64 |
| 118 | + |
| 119 | +**Throws:** `Error` - If the platform is unsupported |
| 120 | + |
| 121 | +--- |
| 122 | + |
| 123 | +### `isMusl(): boolean` |
| 124 | + |
| 125 | +Detects if the system uses musl libc (Alpine Linux, etc.). |
| 126 | + |
| 127 | +**Returns:** `boolean` - `true` if musl is detected, `false` otherwise |
| 128 | + |
| 129 | +--- |
| 130 | + |
| 131 | +### `class ExtensionNotFoundError extends Error` |
| 132 | + |
| 133 | +Error thrown when the SQLite JS extension cannot be found for the current platform. |
| 134 | + |
| 135 | +## Related Projects |
| 136 | + |
| 137 | +- **[@sqliteai/sqlite-vector](https://www.npmjs.com/package/@sqliteai/sqlite-vector)** - Vector search and similarity matching |
| 138 | +- **[@sqliteai/sqlite-ai](https://www.npmjs.com/package/@sqliteai/sqlite-ai)** - On-device AI inference and embedding generation |
| 139 | +- **[@sqliteai/sqlite-sync](https://www.npmjs.com/package/@sqliteai/sqlite-sync)** - Sync on-device databases with the cloud |
| 140 | + |
| 141 | +## License |
| 142 | + |
| 143 | +This project is licensed under the [Elastic License 2.0](LICENSE.md). |
| 144 | + |
| 145 | +For production or managed service use, please [contact SQLite Cloud, Inc ](mailto:[email protected]) for a commercial license. |
| 146 | + |
| 147 | +## Contributing |
| 148 | + |
| 149 | +Contributions are welcome! Please see the [main repository](https://github.com/sqliteai/sqlite-js) to open an issue. |
| 150 | + |
| 151 | +## Support |
| 152 | + |
| 153 | +- 📖 [Documentation](https://github.com/sqliteai/sqlite-js/blob/main/README.md) |
| 154 | +- 🐛 [Report Issues](https://github.com/sqliteai/sqlite-js/issues) |
0 commit comments