@dothift/amarok-lite 1.5.0

package/Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "amarok_lite_node"
+version = "1.5.0"
+edition = "2021"
+description = "napi-rs bindings for dotHIFT://Amarok Lite"
+license = "MIT"
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+napi = { version = "2", features = ["napi8", "serde-json"] }
+napi-derive = "2"
+amarok-core = { path = "../../crates/amarok-core" }
+serde_json = "1"
+
+[build-dependencies]
+napi-build = "2"

package/README.md

@@ -0,0 +1,90 @@
+# dotHIFT://Amarok — Amarok-Lite Node.js SDK
+
+`@dothift/amarok-lite` is an embeddable TypeScript/Node.js database engine for
+[dotHIFT://Amarok](https://gitea.local/dotHIFT/amarok). It wraps
+[better-sqlite3](https://github.com/WiseLibs/better-sqlite3) in WAL mode and
+exposes the Amarok API surface so that code written for Amarok-Lite is
+compatible with the full Amarok server SDK.
+
+## Install
+
+```bash
+npm install @dothift/amarok-lite
+```
+
+## Quick start — synchronous
+
+```typescript
+import { Store } from '@dothift/amarok-lite'
+
+const db = Store.open('./myapp.db')
+
+db.exec('CREATE TABLE IF NOT EXISTS tickets (id TEXT PRIMARY KEY, data TEXT)')
+db.exec('INSERT INTO tickets VALUES ($1, $2)', ['t-001', { title: 'First ticket' }])
+
+const rows = db.query('SELECT * FROM tickets WHERE id = $1', ['t-001'])
+console.log(rows.fetchall())
+
+db.close()
+```
+
+## Quick start — async
+
+```typescript
+import { Store } from '@dothift/amarok-lite'
+
+const db = Store.open('./myapp.db')
+
+await db.execAsync('CREATE TABLE IF NOT EXISTS tickets (id TEXT PRIMARY KEY, data TEXT)')
+await db.execAsync('INSERT INTO tickets VALUES ($1, $2)', ['t-002', { title: 'Second' }])
+
+const rows = await db.queryAsync('SELECT * FROM tickets')
+console.log(rows.fetchall())
+
+db.close()
+```
+
+## Transactions
+
+```typescript
+import { Store } from '@dothift/amarok-lite'
+
+const db = Store.open('./bank.db')
+db.exec('CREATE TABLE IF NOT EXISTS accounts (id TEXT PRIMARY KEY, balance INTEGER)')
+db.exec('INSERT INTO accounts VALUES ($1, $2)', ['alice', 1000])
+db.exec('INSERT INTO accounts VALUES ($1, $2)', ['bob', 500])
+
+db.transaction((tx) => {
+  tx.exec('UPDATE accounts SET balance = balance - 100 WHERE id = $1', ['alice'])
+  tx.exec('UPDATE accounts SET balance = balance + 100 WHERE id = $1', ['bob'])
+})
+
+db.close()
+```
+
+## JSONB operators
+
+Queries using Amarok's PostgreSQL-style JSONB operators are automatically
+rewritten to SQLite3 JSON functions:
+
+| Amarok operator        | SQLite equivalent                            |
+|------------------------|----------------------------------------------|
+| `col->>'key'`          | `json_extract(col, '$.key')`                 |
+| `col->'key'`           | `json_extract(col, '$.key')`                 |
+| `col ? 'key'`          | `(json_type(col, '$.key') IS NOT NULL)`      |
+| `col @> '{"k":"v"}'`   | `(json_patch(col, '{"k":"v"}') = col)`       |
+
+## Options
+
+| Option             | Default | Description                              |
+|--------------------|---------|------------------------------------------|
+| `wal`              | `true`  | Enable WAL journal mode                  |
+| `cacheKB`          | `8000`  | Page cache size in KB (~8 MB)            |
+| `walAutocheckpoint`| `1000`  | WAL auto-checkpoint threshold (pages)    |
+| `timeoutMs`        | `30000` | Busy-wait timeout in milliseconds        |
+| `enableEventLog`   | `true`  | Create Phase 2 event log stub tables     |
+
+## Part of dotHIFT
+
+See the [.platform](https://gitea.local/dotHIFT/.platform) repo for
+cross-product architecture decisions and the dependency manifest.

package/dist/amarok-lite.js

@@ -0,0 +1,315 @@
+/* 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, 'amarok-lite.android-arm64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./amarok-lite.android-arm64.node')
+          } else {
+            nativeBinding = require('@dothift/amarok-lite-android-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm':
+        localFileExisted = existsSync(join(__dirname, 'amarok-lite.android-arm-eabi.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./amarok-lite.android-arm-eabi.node')
+          } else {
+            nativeBinding = require('@dothift/amarok-lite-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, 'amarok-lite.win32-x64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./amarok-lite.win32-x64-msvc.node')
+          } else {
+            nativeBinding = require('@dothift/amarok-lite-win32-x64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'ia32':
+        localFileExisted = existsSync(
+          join(__dirname, 'amarok-lite.win32-ia32-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./amarok-lite.win32-ia32-msvc.node')
+          } else {
+            nativeBinding = require('@dothift/amarok-lite-win32-ia32-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'amarok-lite.win32-arm64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./amarok-lite.win32-arm64-msvc.node')
+          } else {
+            nativeBinding = require('@dothift/amarok-lite-win32-arm64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Windows: ${arch}`)
+    }
+    break
+  case 'darwin':
+    localFileExisted = existsSync(join(__dirname, 'amarok-lite.darwin-universal.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./amarok-lite.darwin-universal.node')
+      } else {
+        nativeBinding = require('@dothift/amarok-lite-darwin-universal')
+      }
+      break
+    } catch {}
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(join(__dirname, 'amarok-lite.darwin-x64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./amarok-lite.darwin-x64.node')
+          } else {
+            nativeBinding = require('@dothift/amarok-lite-darwin-x64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'amarok-lite.darwin-arm64.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./amarok-lite.darwin-arm64.node')
+          } else {
+            nativeBinding = require('@dothift/amarok-lite-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, 'amarok-lite.freebsd-x64.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./amarok-lite.freebsd-x64.node')
+      } else {
+        nativeBinding = require('@dothift/amarok-lite-freebsd-x64')
+      }
+    } catch (e) {
+      loadError = e
+    }
+    break
+  case 'linux':
+    switch (arch) {
+      case 'x64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'amarok-lite.linux-x64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./amarok-lite.linux-x64-musl.node')
+            } else {
+              nativeBinding = require('@dothift/amarok-lite-linux-x64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'amarok-lite.linux-x64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./amarok-lite.linux-x64-gnu.node')
+            } else {
+              nativeBinding = require('@dothift/amarok-lite-linux-x64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'amarok-lite.linux-arm64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./amarok-lite.linux-arm64-musl.node')
+            } else {
+              nativeBinding = require('@dothift/amarok-lite-linux-arm64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'amarok-lite.linux-arm64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./amarok-lite.linux-arm64-gnu.node')
+            } else {
+              nativeBinding = require('@dothift/amarok-lite-linux-arm64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'amarok-lite.linux-arm-musleabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./amarok-lite.linux-arm-musleabihf.node')
+            } else {
+              nativeBinding = require('@dothift/amarok-lite-linux-arm-musleabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'amarok-lite.linux-arm-gnueabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./amarok-lite.linux-arm-gnueabihf.node')
+            } else {
+              nativeBinding = require('@dothift/amarok-lite-linux-arm-gnueabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'riscv64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'amarok-lite.linux-riscv64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./amarok-lite.linux-riscv64-musl.node')
+            } else {
+              nativeBinding = require('@dothift/amarok-lite-linux-riscv64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'amarok-lite.linux-riscv64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./amarok-lite.linux-riscv64-gnu.node')
+            } else {
+              nativeBinding = require('@dothift/amarok-lite-linux-riscv64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 's390x':
+        localFileExisted = existsSync(
+          join(__dirname, 'amarok-lite.linux-s390x-gnu.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./amarok-lite.linux-s390x-gnu.node')
+          } else {
+            nativeBinding = require('@dothift/amarok-lite-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 { AmarokStore } = nativeBinding
+
+module.exports.AmarokStore = AmarokStore

package/dist/errors.d.ts

@@ -0,0 +1,16 @@
+/** Base class for all Amarok-Lite errors. */
+export declare class AmarokError extends Error {
+    constructor(message: string);
+}
+/** Raised for operational errors (I/O, locking, WAL). */
+export declare class AmarokOperationalError extends AmarokError {
+    constructor(message: string);
+}
+/** Raised for constraint violations (UNIQUE, NOT NULL, FK). */
+export declare class AmarokIntegrityError extends AmarokError {
+    constructor(message: string);
+}
+/** Raised for programming errors (bad SQL, wrong param count). */
+export declare class AmarokProgrammingError extends AmarokError {
+    constructor(message: string);
+}

package/dist/errors.js

@@ -0,0 +1,28 @@
+/** Base class for all Amarok-Lite errors. */
+export class AmarokError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AmarokError';
+    }
+}
+/** Raised for operational errors (I/O, locking, WAL). */
+export class AmarokOperationalError extends AmarokError {
+    constructor(message) {
+        super(message);
+        this.name = 'AmarokOperationalError';
+    }
+}
+/** Raised for constraint violations (UNIQUE, NOT NULL, FK). */
+export class AmarokIntegrityError extends AmarokError {
+    constructor(message) {
+        super(message);
+        this.name = 'AmarokIntegrityError';
+    }
+}
+/** Raised for programming errors (bad SQL, wrong param count). */
+export class AmarokProgrammingError extends AmarokError {
+    constructor(message) {
+        super(message);
+        this.name = 'AmarokProgrammingError';
+    }
+}

package/dist/event-log.d.ts

@@ -0,0 +1,3 @@
+import type { Store } from './store.js';
+/** Create Phase 2 event log stub tables if they do not exist. */
+export declare function ensureEventLog(store: Store): void;

package/dist/event-log.js

@@ -0,0 +1,31 @@
+const CREATE_EVENTS_TABLE = `
+CREATE TABLE IF NOT EXISTS _amarok_events (
+    event_id        TEXT    NOT NULL,
+    sequence        INTEGER NOT NULL,
+    region          TEXT    NOT NULL DEFAULT 'local',
+    node_id         TEXT    NOT NULL DEFAULT 'lite',
+    ts              TEXT    NOT NULL,
+    db_name         TEXT    NOT NULL DEFAULT 'default',
+    collection      TEXT    NOT NULL,
+    entity_id       TEXT    NOT NULL,
+    operation       TEXT    NOT NULL CHECK(operation IN ('insert','update','delete','schema')),
+    actor_type      TEXT    NOT NULL DEFAULT 'system',
+    actor_id        TEXT    NOT NULL DEFAULT 'lite',
+    correlation_id  TEXT,
+    before_state    TEXT,
+    after_state     TEXT,
+    metadata        TEXT,
+    PRIMARY KEY (sequence, node_id)
+)`;
+const CREATE_ENTITY_IDX = `
+CREATE INDEX IF NOT EXISTS _amarok_events_entity_idx
+    ON _amarok_events(collection, entity_id, sequence)`;
+const CREATE_SEQ_IDX = `
+CREATE INDEX IF NOT EXISTS _amarok_events_seq_idx
+    ON _amarok_events(sequence)`;
+/** Create Phase 2 event log stub tables if they do not exist. */
+export function ensureEventLog(store) {
+    store.exec(CREATE_EVENTS_TABLE);
+    store.exec(CREATE_ENTITY_IDX);
+    store.exec(CREATE_SEQ_IDX);
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { Store } from './store.js';
+export type { Options } from './store.js';
+export { Rows } from './rows.js';
+export type { Row } from './rows.js';
+export { Tx } from './transaction.js';
+export { AmarokError, AmarokOperationalError, AmarokIntegrityError, AmarokProgrammingError, } from './errors.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { Store } from './store.js';
+export { Rows } from './rows.js';
+export { Tx } from './transaction.js';
+export { AmarokError, AmarokOperationalError, AmarokIntegrityError, AmarokProgrammingError, } from './errors.js';

package/dist/jsonb.d.ts

@@ -0,0 +1,16 @@
+/**
+ * JSONB operator passthrough for Amarok-Lite.
+ *
+ * `amarok-core` natively understands PostgreSQL-style JSONB operators
+ * (`->`, `->>`, `@>`, `?`), so no SQL rewriting is required.
+ *
+ * The `rewrite`, `rewritePlaceholders`, and `normaliseParams` functions are
+ * kept as no-ops / identity functions for API compatibility with callers that
+ * were written against the SQLite-backed version of the SDK.
+ */
+/** Pass SQL through unchanged. amarok-core handles all JSONB operators natively. */
+export declare function rewrite(sql: string): string;
+/** Pass SQL through unchanged. The native engine uses $1/$2 syntax natively. */
+export declare function rewritePlaceholders(sql: string): string;
+/** Pass params through unchanged. */
+export declare function normaliseParams(params: unknown[] | undefined): unknown[];

package/dist/jsonb.js

@@ -0,0 +1,24 @@
+/**
+ * JSONB operator passthrough for Amarok-Lite.
+ *
+ * `amarok-core` natively understands PostgreSQL-style JSONB operators
+ * (`->`, `->>`, `@>`, `?`), so no SQL rewriting is required.
+ *
+ * The `rewrite`, `rewritePlaceholders`, and `normaliseParams` functions are
+ * kept as no-ops / identity functions for API compatibility with callers that
+ * were written against the SQLite-backed version of the SDK.
+ */
+/** Pass SQL through unchanged. amarok-core handles all JSONB operators natively. */
+export function rewrite(sql) {
+    return sql;
+}
+/** Pass SQL through unchanged. The native engine uses $1/$2 syntax natively. */
+export function rewritePlaceholders(sql) {
+    return sql;
+}
+/** Pass params through unchanged. */
+export function normaliseParams(params) {
+    if (!params || params.length === 0)
+        return [];
+    return params;
+}

package/dist/rows.d.ts

@@ -0,0 +1,21 @@
+/** Row type — a record of column name → value. */
+export type Row = Record<string, unknown>;
+/** Iterator over query results. */
+export declare class Rows {
+    private readonly _columns;
+    private readonly _rows;
+    private _pos;
+    private _closed;
+    /** @internal */
+    constructor(rawRows: Record<string, unknown>[], columns: string[]);
+    /** Column names for the current result set. */
+    get columns(): string[];
+    /** Return the next row, or undefined if exhausted. */
+    fetchone(): Row | undefined;
+    /** Return all remaining rows. */
+    fetchall(): Row[];
+    /** Iterate rows with for…of. */
+    [Symbol.iterator](): Iterator<Row>;
+    get length(): number;
+    close(): void;
+}

package/dist/rows.js

@@ -0,0 +1,45 @@
+/** Iterator over query results. */
+export class Rows {
+    _columns;
+    _rows;
+    _pos = 0;
+    _closed = false;
+    /** @internal */
+    constructor(rawRows, columns) {
+        this._columns = columns;
+        this._rows = rawRows;
+    }
+    /** Column names for the current result set. */
+    get columns() {
+        return this._columns;
+    }
+    /** Return the next row, or undefined if exhausted. */
+    fetchone() {
+        if (this._closed || this._pos >= this._rows.length)
+            return undefined;
+        return this._rows[this._pos++];
+    }
+    /** Return all remaining rows. */
+    fetchall() {
+        const remaining = this._rows.slice(this._pos);
+        this._pos = this._rows.length;
+        return remaining;
+    }
+    /** Iterate rows with for…of. */
+    [Symbol.iterator]() {
+        return {
+            next: () => {
+                const row = this.fetchone();
+                return row !== undefined
+                    ? { value: row, done: false }
+                    : { value: undefined, done: true };
+            },
+        };
+    }
+    get length() {
+        return this._rows.length;
+    }
+    close() {
+        this._closed = true;
+    }
+}