@dothift/amarok-lite 1.5.0

package/dist/store.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Store — Amarok-Lite embedded database engine for Node.js.
+ *
+ * Backed by the native `amarok-core` Rust engine via napi-rs.
+ * Provides the Amarok API surface so that code written for the Lite SDK
+ * is compatible with the full Amarok server SDK.
+ *
+ * Usage:
+ *   import { Store } from '@dothift/amarok-lite'
+ *   const db = Store.open('./myapp-data')
+ *   db.exec("CREATE TABLE IF NOT EXISTS tickets (id TEXT PRIMARY KEY, data TEXT)")
+ *   db.exec("INSERT INTO tickets VALUES ('t-001', '{\"title\": \"My ticket\"}')")
+ *   const rows = db.query("SELECT * FROM tickets WHERE id = 't-001'")
+ *   console.log(rows.fetchall())
+ *   db.close()
+ */
+import { Rows } from './rows.js';
+import { Tx } from './transaction.js';
+/** Row type — a record of column name → value. */
+export type Row = Record<string, unknown>;
+/** Options for opening an Amarok-Lite database. */
+export interface Options {
+    /** Default database name (default: `"dhs"`). */
+    defaultDb?: string;
+    /** Create Phase 2 event log stub tables (default: `true`). */
+    enableEventLog?: boolean;
+}
+export declare class Store {
+    private readonly _path;
+    private readonly _opts;
+    /** @internal */
+    private readonly _native;
+    private _closed;
+    private constructor();
+    /**
+     * Open or create a database at *path*. Returns a Store handle synchronously.
+     *
+     * @param path - Filesystem path to the database directory.
+     * @param opts - Optional configuration.
+     */
+    static open(path: string, opts?: Options): Store;
+    /** Filesystem path to the database directory. */
+    get path(): string;
+    /** Default database name. */
+    get defaultDb(): string;
+    /** Execute a SQL statement (DDL or DML). Returns rows affected. */
+    exec(sql: string): number;
+    /** Execute a SQL statement against a named database. Returns rows affected. */
+    execDb(db: string, sql: string): number;
+    /** Execute a SQL query and return result rows. */
+    query(sql: string): Rows;
+    /** Execute a SQL query against a named database. */
+    queryDb(db: string, sql: string): Rows;
+    /** Async wrapper for exec(). */
+    execAsync(sql: string): Promise<number>;
+    /** Async wrapper for query(). */
+    queryAsync(sql: string): Promise<Rows>;
+    /** Start a transaction. Use the transaction() helper instead when possible. */
+    begin(): Tx;
+    /**
+     * Run *fn* inside a transaction. Commits on success; rolls back on error.
+     *
+     * @example
+     * ```ts
+     * db.transaction(tx => {
+     *   tx.exec('INSERT INTO ...')
+     * })
+     * ```
+     */
+    transaction<T>(fn: (tx: Tx) => T): T;
+    /** Flush the WAL to disk. */
+    checkpoint(): void;
+    /** Close the database. Safe to call exactly once. */
+    close(): void;
+    private _checkOpen;
+    private _wrap;
+}

package/dist/store.js

@@ -0,0 +1,212 @@
+/**
+ * Store — Amarok-Lite embedded database engine for Node.js.
+ *
+ * Backed by the native `amarok-core` Rust engine via napi-rs.
+ * Provides the Amarok API surface so that code written for the Lite SDK
+ * is compatible with the full Amarok server SDK.
+ *
+ * Usage:
+ *   import { Store } from '@dothift/amarok-lite'
+ *   const db = Store.open('./myapp-data')
+ *   db.exec("CREATE TABLE IF NOT EXISTS tickets (id TEXT PRIMARY KEY, data TEXT)")
+ *   db.exec("INSERT INTO tickets VALUES ('t-001', '{\"title\": \"My ticket\"}')")
+ *   const rows = db.query("SELECT * FROM tickets WHERE id = 't-001'")
+ *   console.log(rows.fetchall())
+ *   db.close()
+ */
+import { AmarokIntegrityError, AmarokOperationalError, AmarokProgrammingError } from './errors.js';
+import { ensureEventLog } from './event-log.js';
+import { Rows } from './rows.js';
+import { Tx } from './transaction.js';
+// Attempt to load the native napi-rs module. The module name is set by
+// `napi.name` in package.json. When running from TypeScript source (tests),
+// napi-rs also generates a JS shim that loads the .node binary.
+let NativeStore;
+try {
+    // Dynamic import so that TypeScript source can still load without the binary.
+    const mod = await import('./amarok-lite.js').catch(() => undefined);
+    NativeStore = mod?.AmarokStore;
+}
+catch {
+    NativeStore = undefined;
+}
+const DEFAULT_OPTIONS = {
+    defaultDb: 'dhs',
+    enableEventLog: true,
+};
+export class Store {
+    _path;
+    _opts;
+    /** @internal */
+    _native;
+    _closed = false;
+    constructor(_path, native, _opts) {
+        this._path = _path;
+        this._opts = _opts;
+        this._native = native;
+    }
+    // ── Constructors ────────────────────────────────────────────────────────
+    /**
+     * Open or create a database at *path*. Returns a Store handle synchronously.
+     *
+     * @param path - Filesystem path to the database directory.
+     * @param opts - Optional configuration.
+     */
+    static open(path, opts) {
+        if (!NativeStore) {
+            throw new AmarokOperationalError('amarok-lite native module not found. ' +
+                'Run `npm run build` inside sdk/node-lite/ to build it.');
+        }
+        const resolved = { ...DEFAULT_OPTIONS, ...opts };
+        let native;
+        try {
+            native = NativeStore.open(path, resolved.defaultDb);
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            throw new AmarokOperationalError(`Cannot open database at ${path}: ${msg}`);
+        }
+        const store = new Store(path, native, resolved);
+        if (resolved.enableEventLog) {
+            ensureEventLog(store);
+        }
+        return store;
+    }
+    /** Filesystem path to the database directory. */
+    get path() {
+        return this._path;
+    }
+    /** Default database name. */
+    get defaultDb() {
+        return this._opts.defaultDb;
+    }
+    // ── Sync exec/query ─────────────────────────────────────────────────────
+    /** Execute a SQL statement (DDL or DML). Returns rows affected. */
+    exec(sql) {
+        this._checkOpen();
+        try {
+            return Number(this._native.exec(sql));
+        }
+        catch (e) {
+            return this._wrap(e);
+        }
+    }
+    /** Execute a SQL statement against a named database. Returns rows affected. */
+    execDb(db, sql) {
+        this._checkOpen();
+        try {
+            return Number(this._native.execDb(db, sql));
+        }
+        catch (e) {
+            return this._wrap(e);
+        }
+    }
+    /** Execute a SQL query and return result rows. */
+    query(sql) {
+        this._checkOpen();
+        try {
+            const rawRows = this._native.query(sql);
+            const columns = rawRows.length > 0 ? Object.keys(rawRows[0]) : [];
+            return new Rows(rawRows, columns);
+        }
+        catch (e) {
+            return this._wrap(e);
+        }
+    }
+    /** Execute a SQL query against a named database. */
+    queryDb(db, sql) {
+        this._checkOpen();
+        try {
+            const rawRows = this._native.queryDb(db, sql);
+            const columns = rawRows.length > 0 ? Object.keys(rawRows[0]) : [];
+            return new Rows(rawRows, columns);
+        }
+        catch (e) {
+            return this._wrap(e);
+        }
+    }
+    // ── Async wrappers ──────────────────────────────────────────────────────
+    // The native engine is synchronous; these wrappers let callers use await.
+    /** Async wrapper for exec(). */
+    async execAsync(sql) {
+        return this.exec(sql);
+    }
+    /** Async wrapper for query(). */
+    async queryAsync(sql) {
+        return this.query(sql);
+    }
+    // ── Transactions ────────────────────────────────────────────────────────
+    /** Start a transaction. Use the transaction() helper instead when possible. */
+    begin() {
+        this._checkOpen();
+        try {
+            this._native.exec('BEGIN');
+        }
+        catch (e) {
+            this._wrap(e);
+        }
+        return new Tx(this._native, () => { this._native.exec('COMMIT'); }, () => { this._native.exec('ROLLBACK'); });
+    }
+    /**
+     * Run *fn* inside a transaction. Commits on success; rolls back on error.
+     *
+     * @example
+     * ```ts
+     * db.transaction(tx => {
+     *   tx.exec('INSERT INTO ...')
+     * })
+     * ```
+     */
+    transaction(fn) {
+        this._checkOpen();
+        const tx = this.begin();
+        try {
+            const result = fn(tx);
+            if (!tx['_done'])
+                tx.commit();
+            return result;
+        }
+        catch (e) {
+            tx.rollback();
+            throw e;
+        }
+    }
+    // ── Lifecycle ────────────────────────────────────────────────────────────
+    /** Flush the WAL to disk. */
+    checkpoint() {
+        this._checkOpen();
+        try {
+            this._native.checkpoint();
+        }
+        catch (e) {
+            this._wrap(e);
+        }
+    }
+    /** Close the database. Safe to call exactly once. */
+    close() {
+        if (this._closed)
+            return;
+        try {
+            this._native.close();
+        }
+        finally {
+            this._closed = true;
+        }
+    }
+    // ── Internal ─────────────────────────────────────────────────────────────
+    _checkOpen() {
+        if (this._closed)
+            throw new AmarokOperationalError('Store is closed');
+    }
+    _wrap(e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        const lower = msg.toLowerCase();
+        if (lower.includes('unique') || lower.includes('constraint')) {
+            throw new AmarokIntegrityError(msg);
+        }
+        if (lower.includes('parse') || lower.includes('syntax') || lower.includes('plan')) {
+            throw new AmarokProgrammingError(msg);
+        }
+        throw new AmarokOperationalError(msg);
+    }
+}

package/dist/transaction.d.ts

@@ -0,0 +1,28 @@
+import { Rows } from './rows.js';
+import type { Row } from './store.js';
+/** @internal Native store interface used by Tx. */
+interface NativeExec {
+    exec(sql: string): bigint | number;
+    query(sql: string): Row[];
+}
+/** An active database transaction. */
+export declare class Tx {
+    private readonly _native;
+    private readonly _commitFn;
+    private readonly _rollbackFn;
+    /** @internal */
+    _done: boolean;
+    /** @internal */
+    constructor(_native: NativeExec, _commitFn: () => void, _rollbackFn: () => void);
+    /** Execute a SQL statement. Returns rows affected. */
+    exec(sql: string): number;
+    /** Execute a SQL query and return result rows. */
+    query(sql: string): Rows;
+    /** Commit the transaction. */
+    commit(): void;
+    /** Roll back the transaction. */
+    rollback(): void;
+    private _checkOpen;
+    private _wrap;
+}
+export {};

package/dist/transaction.js

@@ -0,0 +1,66 @@
+import { AmarokIntegrityError, AmarokOperationalError, AmarokProgrammingError } from './errors.js';
+import { Rows } from './rows.js';
+/** An active database transaction. */
+export class Tx {
+    _native;
+    _commitFn;
+    _rollbackFn;
+    /** @internal */
+    _done = false;
+    /** @internal */
+    constructor(_native, _commitFn, _rollbackFn) {
+        this._native = _native;
+        this._commitFn = _commitFn;
+        this._rollbackFn = _rollbackFn;
+    }
+    /** Execute a SQL statement. Returns rows affected. */
+    exec(sql) {
+        this._checkOpen();
+        try {
+            return Number(this._native.exec(sql));
+        }
+        catch (e) {
+            return this._wrap(e);
+        }
+    }
+    /** Execute a SQL query and return result rows. */
+    query(sql) {
+        this._checkOpen();
+        try {
+            const rawRows = this._native.query(sql);
+            const columns = rawRows.length > 0 ? Object.keys(rawRows[0]) : [];
+            return new Rows(rawRows, columns);
+        }
+        catch (e) {
+            return this._wrap(e);
+        }
+    }
+    /** Commit the transaction. */
+    commit() {
+        this._checkOpen();
+        this._commitFn();
+        this._done = true;
+    }
+    /** Roll back the transaction. */
+    rollback() {
+        if (!this._done) {
+            this._rollbackFn();
+            this._done = true;
+        }
+    }
+    _checkOpen() {
+        if (this._done)
+            throw new AmarokOperationalError('Transaction is already closed');
+    }
+    _wrap(e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        const lower = msg.toLowerCase();
+        if (lower.includes('unique') || lower.includes('constraint')) {
+            throw new AmarokIntegrityError(msg);
+        }
+        if (lower.includes('parse') || lower.includes('syntax') || lower.includes('plan')) {
+            throw new AmarokProgrammingError(msg);
+        }
+        throw new AmarokOperationalError(msg);
+    }
+}

package/index.d.ts

@@ -0,0 +1,35 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/* auto-generated by NAPI-RS */
+
+/**
+ * Embedded Amarok database handle.
+ *
+ * Open with `AmarokStore.open(path)`.
+ */
+export declare class AmarokStore {
+  /** Filesystem path to the database directory. */
+  readonly path: string
+  /**
+   * Open or create a database at *path*.
+   *
+   * @param path - Filesystem path to the database directory.
+   * @param defaultDb - Active database name. Defaults to `"dhs"`.
+   */
+  static open(path: string, defaultDb?: string | undefined | null): AmarokStore
+  /** Execute a DML or DDL statement. Returns rows affected. */
+  exec(sql: string): number
+  /** Execute a SQL statement against a named database. Returns rows affected. */
+  execDb(db: string, sql: string): number
+  /** Execute a SELECT and return rows as an array of JSON objects. */
+  query(sql: string): Array<any>
+  /** Execute a SELECT against a named database. Returns rows as JSON objects. */
+  queryDb(db: string, sql: string): Array<any>
+  /** Flush the WAL to disk. */
+  checkpoint(): void
+  /** Checkpoint and mark the store as closed. */
+  close(): void
+  /** Return the default database name. */
+  get defaultDb(): string
+}