neutralinojs-ext-sqlite3 0.0.1-alpha.2

package/.cargo/config.toml

@@ -0,0 +1,2 @@
+[build]
+target-dir = "./build/rust"

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Raman Piatrou <rpiatrou.github@proton.me>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,195 @@
+# neutralinojs-ext-sqlite3
+
+A Neutralino extension that provides SQLite access for desktop applications.
+
+It runs SQLite in a separate native process and communicates with your app through Neutralino’s extension IPC layer.
+
+The package also includes a JavaScript client API compatible with the sqlite3 interface,
+supporting both callbacks and Promises.
+
+---
+
+## Motivation & Intent
+
+Desktop applications require persistent local storage with support for queries and complex data structures.
+This is commonly provided by SQLite or similar database engines.
+
+However, browser-based environments cannot access local SQLite database files due to sandbox restrictions.
+
+This extension bridges that gap by running SQLite in a separate native process
+and providing a client API compatible with the sqlite3 interface, as well as ORM packages built on top of it.
+
+Design goals:
+
+* JS-first development
+* Generic, not app-specific, API
+* Minimal native surface and small binary footprint
+
+---
+
+## Architecture Overview
+
+```
+Application Code (JavaScript / TypeScript)
+        │
+        │ calls SQLite client API
+        ▼
+Extension Client API (JS wrapper)
+(runs inside WebView, managed by Neutralino)
+        │
+        │ Neutralino.extensions.dispatch (IPC)
+        ▼
+Neutralino Runtime (native neutralino process)
+        │
+        │ WebSocket-based extension IPC
+        ▼
+SQLite Extension Process (Rust native binary)
+        │
+        │ direct SQLite C API
+        ▼
+SQLite Engine
+        │
+        ▼
+Database File (.db) on Filesystem
+```
+
+Key points:
+
+* The extension runs as a separate process managed by Neutralino
+* All database operations are asynchronous and do not block the UI.
+
+---
+
+## When to Use This Extension
+
+Use neutralinojs-ext-sqlite3 if you need:
+
+* Local SQL storage
+* A small, fast desktop database
+* Optional SQLite extensions (loaded at startup)
+
+---
+
+## Installation
+
+```
+npm install neutralinojs-ext-sqlite3
+```
+
+It will automatically copy appropriate binary into your Neutralino extensions/ directory:
+
+```
+extensions/sqlite/
+```
+
+Then register it in neutralino.config.json.
+
+Example:
+
+```json
+{
+  "enableExtensions": true,
+  "extensions": [
+    {
+      "id": "sqlite3",
+      "command": "./extensions/sqlite3/neutralinojs-ext-sqlite3 --run"
+    }
+  ]
+}
+```
+
+---
+
+## Usage Example
+
+The neutralino runtime should be initialized first.
+
+```js
+Neutralino.init();
+```
+
+Use the provided JS wrapper:
+
+```js
+import * as sqlite from "neutralinojs-ext-sqlite3";
+
+const db = await sqlite.open({
+  path: "app.db"
+});
+
+await db.exec("CREATE TABLE messages(id TEXT, content TEXT)");
+
+await db.close();
+```
+
+The JS wrapper API handles IPC communication with the native extension.
+
+---
+
+## Runtime Configuration
+
+The extension runs as a Neutralino extension process and communicates using Neutralino’s extension IPC protocol.
+
+Startup parameters:
+
+* `--run` (required)
+* `--extension <PATH>` for standard SQLite extensions (exports `sqlite3_extension_init`)
+* `--extension-symbol <PATH> <SYMBOL>` for extensions with a custom init symbol
+
+Example:
+
+```
+neutralinojs-ext-sqlite3 --run
+```
+
+```
+neutralinojs-ext-sqlite3 --run --extension ./my_ext.so
+```
+
+```
+neutralinojs-ext-sqlite3 --run --extension-symbol ./custom_ext.so my_custom_init
+```
+
+Neutralino provides WebSocket connection parameters to the extension at startup,
+and all runtime communication occurs over Neutralino’s extension messaging layer.
+
+---
+
+## Development
+
+### Build the native extension
+
+```
+npm run build
+```
+
+The extension links SQLite via the Rust libsqlite3-sys crate with the bundled SQLite source enabled.
+SQLite is compiled automatically during the build process,
+so no system SQLite libraries or development headers are required.
+
+Platform binaries are published into `dist/` folder.
+
+### Run tests
+
+```
+npm run test
+```
+Vitest requires Node.js 16+ (18+ recommended).
+The test suite also covers SQLite extension loading with multiple extension types;
+it is not tied to any specific extension library.
+
+---
+
+## Release Notes
+
+See `RELEASES.md` for binary coverage expectations.
+
+The SQLite engine version is determined by the Rust SQLite crate (libsqlite3-sys) used by this project. SQLite is bundled and compiled as part of the extension build process and included directly in the extension binary. No system SQLite installation is required at runtime.
+
+---
+
+## License
+
+MIT License © 2026 Raman Piatrou.
+
+See `LICENSE` for details.

package/dist/index.d.ts

@@ -0,0 +1,82 @@
+/** Result of run() - matches sqlite3 RunResult */
+export interface RunResult {
+    lastID: number;
+    changes: number;
+    /** Alias for lastID (SQLite native name) */
+    lastInsertRowid: number;
+}
+/** Options for open() */
+export interface OpenOptions {
+    path?: string;
+    filename?: string;
+    readonly?: boolean;
+    create?: boolean;
+    wal?: boolean;
+    pragmas?: string[];
+    [key: string]: unknown;
+}
+/**
+ * Database instance - classic sqlite3 promises interface.
+ * Use open() to obtain a Database.
+ */
+export declare class Database {
+    #private;
+    constructor(connection: string);
+    /**
+     * Run a SQL statement (INSERT/UPDATE/DELETE). Returns lastID and changes.
+     * @example db.run("INSERT INTO t VALUES (?)", "foo")
+     * @example db.run("UPDATE t SET x = ? WHERE id = ?", "bar", 1)
+     */
+    run(sql: string, ...params: unknown[]): Promise<RunResult>;
+    /**
+     * Get a single row. Returns undefined if no row.
+     * @example db.get("SELECT * FROM t WHERE id = ?", 1)
+     */
+    get<T = Record<string, unknown>>(sql: string, ...params: unknown[]): Promise<T | undefined>;
+    /**
+     * Get all rows.
+     * @example db.all("SELECT * FROM t")
+     */
+    all<T = Record<string, unknown>>(sql: string, ...params: unknown[]): Promise<T[]>;
+    /**
+     * Execute SQL without params (DDL, PRAGMAs, multiple statements).
+     * @example db.exec("CREATE TABLE t(id INTEGER PRIMARY KEY)")
+     */
+    exec(sql: string): Promise<void>;
+    /**
+     * Close the database connection.
+     */
+    close(): Promise<void>;
+    /**
+     * Run multiple statements in a transaction. Rolls back on error.
+     */
+    transaction(ops: Array<{
+        sql: string;
+        params?: unknown[];
+    }>): Promise<{
+        changes: number;
+    }>;
+}
+/**
+ * Open a database. Returns a Database instance (classic sqlite3 interface).
+ * @param pathOrOptions - Path string (e.g. ":memory:" or "/path/to/db.sqlite") or options object
+ * @param options - Optional options when path is a string
+ * @example const db = await open(":memory:")
+ * @example const db = await open({ path: "/tmp/app.db", readonly: false })
+ */
+export declare function open(pathOrOptions?: string | {
+    path?: string;
+    filename?: string;
+    options?: Record<string, unknown>;
+}, options?: Record<string, unknown>): Promise<Database>;
+/**
+ * Shutdown the SQLite extension process. Call after closing all databases.
+ */
+export declare function shutdown(): Promise<void>;
+declare const _default: {
+    open: typeof open;
+    Database: typeof Database;
+    shutdown: typeof shutdown;
+};
+export default _default;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAiFA,kDAAkD;AAClD,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,yBAAyB;AACzB,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;GAGG;AACH,qBAAa,QAAQ;;gBAGP,UAAU,EAAE,MAAM;IAI9B;;;;OAIG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,SAAS,CAAC;IAc1D;;;OAGG;IACH,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAU3F;;;OAGG;IACH,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAKjF;;;OAGG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhC;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB;;OAEG;IACH,WAAW,CACT,GAAG,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAA;KAAE,CAAC,GAC9C,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAMhC;AAED;;;;;;GAMG;AACH,wBAAsB,IAAI,CACxB,aAAa,CAAC,EACV,MAAM,GACN;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,EAC3E,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,OAAO,CAAC,QAAQ,CAAC,CAInB;AAED;;GAEG;AACH,wBAAsB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAE9C;;;;;;AAED,wBAIE"}

package/dist/index.js

@@ -0,0 +1,170 @@
+"use strict";
+/// <reference path="../neutralino.d.ts" />
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _Database_connection;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Database = void 0;
+exports.open = open;
+exports.shutdown = shutdown;
+function assertNeutralino() {
+    if (typeof Neutralino === "undefined" || !Neutralino.extensions) {
+        throw new Error("Neutralino.extensions is not available in this runtime");
+    }
+}
+function generateId() {
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, c => {
+        const r = Math.random() * 16 | 0;
+        const v = c === 'x' ? r : (r & 0x3 | 0x8);
+        return v.toString(16);
+    });
+}
+async function invoke(method, params) {
+    assertNeutralino();
+    const id = generateId();
+    return new Promise((resolve, reject) => {
+        const handler = (evt) => {
+            const data = evt.detail || evt;
+            if (data.id !== id)
+                return;
+            Neutralino.events.off("sqlite3", handler);
+            const rpcData = data;
+            if (rpcData.error) {
+                const err = new Error(rpcData.error.message || "RPC error");
+                err.code = rpcData.error.code;
+                err.details = rpcData.error.details;
+                reject(err);
+            }
+            else {
+                resolve(rpcData.result);
+            }
+        };
+        Neutralino.events.on("sqlite3", handler);
+        Neutralino.extensions.dispatch("sqlite3", "sqlite3", { id, method, params });
+    });
+}
+/**
+ * Normalize params for run/get/all: (sql, x) | (sql, x, y) | (sql, [x, y])
+ */
+function normalizeParams(sql, ...args) {
+    if (args.length === 0) {
+        return { sql, params: [] };
+    }
+    if (args.length === 1 && Array.isArray(args[0])) {
+        return { sql, params: args[0] };
+    }
+    return { sql, params: args };
+}
+function normalizeOpenArg(arg1, arg2) {
+    if (arg1 === undefined)
+        return {};
+    if (typeof arg1 === "string") {
+        return { path: arg1, options: arg2 };
+    }
+    if (typeof arg1 === "object" && arg1 !== null && !Array.isArray(arg1)) {
+        const path = arg1.path ?? arg1.filename;
+        return path !== undefined ? { path, options: arg1.options ?? arg2 } : arg1;
+    }
+    return { path: arg1, options: arg2 };
+}
+/**
+ * Database instance - classic sqlite3 promises interface.
+ * Use open() to obtain a Database.
+ */
+class Database {
+    constructor(connection) {
+        _Database_connection.set(this, void 0);
+        __classPrivateFieldSet(this, _Database_connection, connection, "f");
+    }
+    /**
+     * Run a SQL statement (INSERT/UPDATE/DELETE). Returns lastID and changes.
+     * @example db.run("INSERT INTO t VALUES (?)", "foo")
+     * @example db.run("UPDATE t SET x = ? WHERE id = ?", "bar", 1)
+     */
+    run(sql, ...params) {
+        const { sql: s, params: p } = normalizeParams(sql, ...params);
+        return invoke("run", { connection: __classPrivateFieldGet(this, _Database_connection, "f"), sql: s, params: p }).then((r) => {
+            const res = r;
+            return {
+                lastID: res.lastInsertRowid,
+                changes: res.changes,
+                lastInsertRowid: res.lastInsertRowid,
+            };
+        });
+    }
+    /**
+     * Get a single row. Returns undefined if no row.
+     * @example db.get("SELECT * FROM t WHERE id = ?", 1)
+     */
+    get(sql, ...params) {
+        const { sql: s, params: p } = normalizeParams(sql, ...params);
+        return invoke("query", { connection: __classPrivateFieldGet(this, _Database_connection, "f"), sql: s, params: p }).then((rows) => {
+            const arr = rows;
+            return arr.length > 0 ? arr[0] : undefined;
+        });
+    }
+    /**
+     * Get all rows.
+     * @example db.all("SELECT * FROM t")
+     */
+    all(sql, ...params) {
+        const { sql: s, params: p } = normalizeParams(sql, ...params);
+        return invoke("query", { connection: __classPrivateFieldGet(this, _Database_connection, "f"), sql: s, params: p });
+    }
+    /**
+     * Execute SQL without params (DDL, PRAGMAs, multiple statements).
+     * @example db.exec("CREATE TABLE t(id INTEGER PRIMARY KEY)")
+     */
+    exec(sql) {
+        return invoke("exec", { connection: __classPrivateFieldGet(this, _Database_connection, "f"), sql });
+    }
+    /**
+     * Close the database connection.
+     */
+    close() {
+        return invoke("close", { connection: __classPrivateFieldGet(this, _Database_connection, "f") });
+    }
+    /**
+     * Run multiple statements in a transaction. Rolls back on error.
+     */
+    transaction(ops) {
+        return invoke("transaction", {
+            connection: __classPrivateFieldGet(this, _Database_connection, "f"),
+            ops,
+        });
+    }
+}
+exports.Database = Database;
+_Database_connection = new WeakMap();
+/**
+ * Open a database. Returns a Database instance (classic sqlite3 interface).
+ * @param pathOrOptions - Path string (e.g. ":memory:" or "/path/to/db.sqlite") or options object
+ * @param options - Optional options when path is a string
+ * @example const db = await open(":memory:")
+ * @example const db = await open({ path: "/tmp/app.db", readonly: false })
+ */
+async function open(pathOrOptions, options) {
+    const params = normalizeOpenArg(pathOrOptions, options);
+    const connection = (await invoke("open", params));
+    return new Database(connection);
+}
+/**
+ * Shutdown the SQLite extension process. Call after closing all databases.
+ */
+async function shutdown() {
+    return invoke("shutdown", {});
+}
+exports.default = {
+    open,
+    Database,
+    shutdown,
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "neutralinojs-ext-sqlite3",
+  "version": "0.0.1-alpha.2",
+  "description": "Neutralino extension providing SQLite with vector indexing",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "scripts/postinstall.js",
+    "rust",
+    ".cargo",
+    "README.md",
+    "LICENSE"
+  ],
+  "optionalDependencies": {
+    "neutralinojs-ext-sqlite3-darwin-arm64": "0.0.1-alpha.2",
+    "neutralinojs-ext-sqlite3-darwin-x64": "0.0.1-alpha.2",
+    "neutralinojs-ext-sqlite3-linux-arm64": "0.0.1-alpha.2",
+    "neutralinojs-ext-sqlite3-linux-x64": "0.0.1-alpha.2",
+    "neutralinojs-ext-sqlite3-win32-x64": "0.0.1-alpha.2"
+  },
+  "scripts": {
+    "clean": "rimraf dist build/rust tests/integration/tmp tests/e2e/app/bin tests/e2e/app/dist tests/e2e/app/extensions tests/e2e/app/resources/js tests/e2e/app/tmp tests/e2e/app/.storage tests/e2e/app/*.log",
+    "typecheck": "npx tsc --noEmit -p tsconfig.build.json",
+    "build": "npm run clean && npm run typecheck && npm run build:ts && npm run build:native",
+    "build:ts": "npx tsc -p tsconfig.build.json",
+    "build:native": "cargo build --release",
+    "package:platform": "node scripts/package.js",
+    "prepublishOnly": "npm run build",
+    "postinstall": "node scripts/postinstall.js",
+    "test": "vitest run tests/integration",
+    "test:e2e": "vitest run tests/e2e --testTimeout=90000",
+    "version:all": "node scripts/version-all.js",
+    "setup:config": "node scripts/postinstall.js"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/adm-zip": "^0.5.7",
+    "@types/sqlite3": "^3.1.11",
+    "@types/ws": "^8.18.1",
+    "adm-zip": "^0.5.16",
+    "rimraf": "^6.1.3",
+    "sqlite3": "^5.1.7",
+    "tar": "^7.5.7",
+    "tsx": "^4.19.2",
+    "typescript": "^5.9.3",
+    "vitest": "^0.34.6",
+    "ws": "^8.19.0"
+  },
+  "dependencies": {
+    "jsonc-parser": "^3.3.1"
+  }
+}