@procedures/sqlite 0.2.3 → 0.3.0

package/dist/procedures/db/shared.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The helpers of the db.* procedures of roadmap R44.
+ */
+import type { Database } from "@mark1russell7/docker-sqlite";
+/** The database file of an input: `dbPath`, or the CLI log database. */
+export declare function databasePath(dbPath: string | undefined): string;
+/**
+ * This function throws ENOENT for a database file that does not exist. A procedure that only
+ * reads uses it: sql.js opens a missing file as an empty database, so a wrong path gave no tables.
+ */
+export declare function requireDatabaseFile(procedure: string, path: string): void;
+/** True for a statement that starts, ends or names a transaction (BEGIN, COMMIT, SAVEPOINT, ...). */
+export declare function controlsTransaction(sql: string): boolean;
+/** The result of one statement: the rows that it changed, and its rows when it gives rows. */
+export interface StatementRun {
+    changes: number;
+    rows?: Record<string, unknown>[];
+}
+/**
+ * This function runs the statements of one SQL text in order, and gives one result for the text.
+ * The params bind to the first statement, so a text with params must hold one statement. A
+ * statement that controls a transaction is refused: the caller owns the transaction.
+ */
+export declare function runStatements(db: Database, sql: string, params: unknown[], label: string): StatementRun;
+//# sourceMappingURL=shared.d.ts.map

package/dist/procedures/db/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../../src/procedures/db/shared.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AAG7D,wEAAwE;AACxE,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAE/D;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAKzE;AAsBD,qGAAqG;AACrG,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAExD;AAED,8FAA8F;AAC9F,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;CAClC;AAMD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,CA4CvG"}

package/dist/procedures/db/shared.js

@@ -0,0 +1,105 @@
+/**
+ * The helpers of the db.* procedures of roadmap R44.
+ */
+import { existsSync } from "node:fs";
+import { DEFAULT_DB_PATH } from "../../types.js";
+/** The database file of an input: `dbPath`, or the CLI log database. */
+export function databasePath(dbPath) {
+    return dbPath ?? DEFAULT_DB_PATH;
+}
+/**
+ * This function throws ENOENT for a database file that does not exist. A procedure that only
+ * reads uses it: sql.js opens a missing file as an empty database, so a wrong path gave no tables.
+ */
+export function requireDatabaseFile(procedure, path) {
+    if (path === ":memory:" || existsSync(path))
+        return;
+    const error = new Error(`${procedure}: the database file does not exist: ${path}`);
+    error.code = "ENOENT";
+    throw error;
+}
+/** The statements that control a transaction, which the procedures run themselves. */
+const TRANSACTION_CONTROL = /^(BEGIN|COMMIT|END|ROLLBACK|SAVEPOINT|RELEASE)\b/i;
+/** The SQL of a statement without its leading spaces and comments. */
+function withoutLeadingComments(sql) {
+    let rest = sql;
+    for (;;) {
+        const trimmed = rest.replace(/^\s+/, "");
+        if (trimmed.startsWith("--")) {
+            const end = trimmed.indexOf("\n");
+            rest = end === -1 ? "" : trimmed.slice(end + 1);
+        }
+        else if (trimmed.startsWith("/*")) {
+            const end = trimmed.indexOf("*/");
+            rest = end === -1 ? "" : trimmed.slice(end + 2);
+        }
+        else {
+            return trimmed;
+        }
+    }
+}
+/** True for a statement that starts, ends or names a transaction (BEGIN, COMMIT, SAVEPOINT, ...). */
+export function controlsTransaction(sql) {
+    return TRANSACTION_CONTROL.test(withoutLeadingComments(sql));
+}
+function totalChanges(db) {
+    return Number(db.exec("SELECT total_changes()")[0]?.values[0]?.[0] ?? 0);
+}
+/**
+ * This function runs the statements of one SQL text in order, and gives one result for the text.
+ * The params bind to the first statement, so a text with params must hold one statement. A
+ * statement that controls a transaction is refused: the caller owns the transaction.
+ */
+export function runStatements(db, sql, params, label) {
+    const before = totalChanges(db);
+    const result = { changes: 0 };
+    let count = 0;
+    const iterator = db.iterateStatements(sql);
+    try {
+        for (let step = iterator.next(); !step.done; step = iterator.next()) {
+            const statement = step.value;
+            try {
+                count++;
+                if (count > 1 && params.length > 0) {
+                    throw new Error(`${label}: the params bind to one statement, and the SQL has several`);
+                }
+                if (controlsTransaction(statement.getSQL())) {
+                    throw new Error(`${label}: the procedure runs the transaction: BEGIN, COMMIT, ROLLBACK, SAVEPOINT and RELEASE are refused`);
+                }
+                if (count === 1 && params.length > 0)
+                    statement.bind(params);
+                if (statement.getColumnNames().length > 0) {
+                    const rows = [];
+                    while (statement.step())
+                        rows.push(statement.getAsObject());
+                    result.rows = rows;
+                }
+                else {
+                    while (statement.step()) {
+                        // A statement without columns gives no rows: one step runs it
+                    }
+                }
+            }
+            finally {
+                statement.free();
+            }
+        }
+    }
+    catch (error) {
+        // Read the iterator to its end: that frees its copy of the SQL (it only prepares the rest)
+        try {
+            while (!iterator.next().done) {
+                // Prepare only
+            }
+        }
+        catch {
+            // A later statement did not prepare: the iterator ended
+        }
+        throw error;
+    }
+    if (count === 0)
+        throw new Error(`${label}: the SQL has no statement`);
+    result.changes = totalChanges(db) - before;
+    return result;
+}
+//# sourceMappingURL=shared.js.map

package/dist/procedures/db/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../../src/procedures/db/shared.ts"],"names":[],"mappings":"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"}

package/dist/procedures/db/tables.d.ts

@@ -0,0 +1,12 @@
+/**
+ * db.tables procedure (roadmap R44)
+ *
+ * The tables and the views of a database, without the internal `sqlite_` tables. The connection
+ * is read only (PRAGMA query_only), and a missing file is an error: it does not make one.
+ */
+import type { DbTablesInput, DbTablesOutput } from "../../types.js";
+/**
+ * The tables and views of a database
+ */
+export declare function dbTables(input: DbTablesInput): Promise<DbTablesOutput>;
+//# sourceMappingURL=tables.d.ts.map

package/dist/procedures/db/tables.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tables.d.ts","sourceRoot":"","sources":["../../../src/procedures/db/tables.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAe,aAAa,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAGjF;;GAEG;AACH,wBAAsB,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CAY5E"}

package/dist/procedures/db/tables.js

@@ -0,0 +1,22 @@
+/**
+ * db.tables procedure (roadmap R44)
+ *
+ * The tables and the views of a database, without the internal `sqlite_` tables. The connection
+ * is read only (PRAGMA query_only), and a missing file is an error: it does not make one.
+ */
+import { query, withConnection } from "@mark1russell7/docker-sqlite";
+import { databasePath, requireDatabaseFile } from "./shared.js";
+/**
+ * The tables and views of a database
+ */
+export async function dbTables(input) {
+    const path = databasePath(input.dbPath);
+    requireDatabaseFile("db.tables", path);
+    const types = input.views === false ? "('table')" : "('table', 'view')";
+    return withConnection({ dbPath: path }, (db) => {
+        db.run("PRAGMA query_only = 1");
+        const result = query(db, `SELECT name, type, sql FROM sqlite_master WHERE type IN ${types} AND name NOT LIKE 'sqlite\\_%' ESCAPE '\\' ORDER BY name`);
+        return { tables: result.rows.map((row) => ({ name: row.name, type: row.type, sql: row.sql ?? null })) };
+    });
+}
+//# sourceMappingURL=tables.js.map

package/dist/procedures/db/tables.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tables.js","sourceRoot":"","sources":["../../../src/procedures/db/tables.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAErE,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEhE;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,KAAoB;IACjD,MAAM,IAAI,GAAG,YAAY,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACxC,mBAAmB,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;IACvC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,mBAAmB,CAAC;IACxE,OAAO,cAAc,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE;QAC7C,EAAE,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC;QAChC,MAAM,MAAM,GAAG,KAAK,CAClB,EAAE,EACF,2DAA2D,KAAK,2DAA2D,CAC5H,CAAC;QACF,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,IAAI,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;IAC1G,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/procedures/db/transaction.d.ts

@@ -0,0 +1,14 @@
+/**
+ * db.transaction procedure (roadmap R44)
+ *
+ * The statements of the input run in order in one transaction. When one fails, the procedure
+ * rolls back the transaction and does not save the file: the database stays as it was. A
+ * statement that gives rows (SELECT, or RETURNING) gives them in its result, so a later
+ * statement can follow an earlier one in the same transaction.
+ */
+import type { DbTransactionInput, DbTransactionOutput } from "../../types.js";
+/**
+ * Run statements in one transaction
+ */
+export declare function dbTransaction(input: DbTransactionInput): Promise<DbTransactionOutput>;
+//# sourceMappingURL=transaction.d.ts.map

package/dist/procedures/db/transaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../../../src/procedures/db/transaction.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAqB,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAGjG;;GAEG;AACH,wBAAsB,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CA0B3F"}

package/dist/procedures/db/transaction.js

@@ -0,0 +1,44 @@
+/**
+ * db.transaction procedure (roadmap R44)
+ *
+ * The statements of the input run in order in one transaction. When one fails, the procedure
+ * rolls back the transaction and does not save the file: the database stays as it was. A
+ * statement that gives rows (SELECT, or RETURNING) gives them in its result, so a later
+ * statement can follow an earlier one in the same transaction.
+ */
+import { withConnection } from "@mark1russell7/docker-sqlite";
+import { databasePath, runStatements } from "./shared.js";
+/**
+ * Run statements in one transaction
+ */
+export async function dbTransaction(input) {
+    return withConnection({ dbPath: databasePath(input.dbPath) }, (db) => {
+        db.run("BEGIN");
+        const results = [];
+        try {
+            input.statements.forEach((statement, index) => {
+                const label = `db.transaction: statements[${index}]`;
+                try {
+                    results.push(runStatements(db, statement.sql, statement.params ?? [], label));
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    throw new Error(message.startsWith(label) ? message : `${label}: ${message}`);
+                }
+            });
+            db.run("COMMIT");
+        }
+        catch (error) {
+            try {
+                db.run("ROLLBACK");
+            }
+            catch {
+                // SQLite ended the transaction already (an ON CONFLICT ROLLBACK)
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`${message}. The transaction was rolled back.`);
+        }
+        return { results, changes: results.reduce((sum, result) => sum + result.changes, 0) };
+    });
+}
+//# sourceMappingURL=transaction.js.map

package/dist/procedures/db/transaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.js","sourceRoot":"","sources":["../../../src/procedures/db/transaction.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAE9D,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE1D;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,KAAyB;IAC3D,OAAO,cAAc,CAAC,EAAE,MAAM,EAAE,YAAY,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE;QACnE,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAChB,MAAM,OAAO,GAAwB,EAAE,CAAC;QACxC,IAAI,CAAC;YACH,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,SAAS,EAAE,KAAK,EAAE,EAAE;gBAC5C,MAAM,KAAK,GAAG,8BAA8B,KAAK,GAAG,CAAC;gBACrD,IAAI,CAAC;oBACH,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC,EAAE,EAAE,SAAS,CAAC,GAAG,EAAE,SAAS,CAAC,MAAM,IAAI,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC;gBAChF,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;oBACvE,MAAM,IAAI,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,KAAK,KAAK,OAAO,EAAE,CAAC,CAAC;gBAChF,CAAC;YACH,CAAC,CAAC,CAAC;YACH,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACnB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC;gBACH,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;YACrB,CAAC;YAAC,MAAM,CAAC;gBACP,iEAAiE;YACnE,CAAC;YACD,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACvE,MAAM,IAAI,KAAK,CAAC,GAAG,OAAO,oCAAoC,CAAC,CAAC;QAClE,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,CAAC,GAAG,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,CAAC;IACxF,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/storage.d.ts

@@ -0,0 +1,123 @@
+/**
+ * A collection storage in SQLite (roadmap R45).
+ *
+ * `SqliteStorage` keeps the items of one collection in one table of a SQLite database: a file,
+ * or `:memory:`. It implements `CollectionStorage` of `@procedures/client`, so a
+ * `ProcedureServer`, an `ApiStorage` server and a `HybridStorage` can use it. The engine is
+ * sql.js (SQLite in WebAssembly), through `@mark1russell7/docker-sqlite`: no native build.
+ *
+ * - The table of a collection has the columns `id` (the key) and `value` (the JSON text of the
+ *   item). A value goes through `JSON.stringify` and `JSON.parse`.
+ * - A change log gives `getChangesSince()`. The table `_storage_log` has the last change of each
+ *   id, and `_storage_versions` has the version of each collection: `<epoch>:<seq>`, as
+ *   `InMemoryStorage` has. The epoch stays in the file, so a version stays valid after a restart.
+ * - Each write runs in a transaction. A batch that fails changes nothing.
+ * - The storage keeps the database in memory and writes the file after each write. A write ends
+ *   after its file write. One file write can hold the changes of several writes.
+ * - The storages of one file in one process share one database, so the storages of two tables in
+ *   one file do not write over the changes of each other.
+ */
+import type { CollectionStorage, StorageChanges, StorageMetadata } from "@procedures/client";
+/** The path of a database that is only in memory. */
+export declare const MEMORY_PATH = ":memory:";
+/** The options of a `SqliteStorage`. */
+export interface SqliteStorageOptions {
+    /**
+     * The database file, or `:memory:` for a database that lives as long as the storage. The
+     * storage makes the file, and its folder, at the first write.
+     */
+    path: string;
+    /**
+     * The table of the collection. The name starts with a letter and has only letters, digits and
+     * underscores, 64 characters or fewer. A name that starts with `sqlite_` is not permitted.
+     */
+    table: string;
+    /**
+     * The number of deletes that the change log keeps. After more deletes, the log drops the
+     * oldest ones, and `getChangesSince` of an older version gives all items.
+     * @default 10000
+     */
+    maxTombstones?: number;
+}
+/**
+ * This function gives the name when it is a permitted table name. Else it throws a `TypeError`. The name goes
+ * into the SQL text, so the check is strict.
+ */
+export declare function checkTableName(name: unknown): string;
+/**
+ * A collection storage in a table of a SQLite database (roadmap R45).
+ *
+ * @example
+ * ```typescript
+ * const users = new SqliteStorage<User>({ path: "./data/app.db", table: "users" });
+ * await users.set("123", { id: "123", name: "John" });
+ * const user = await users.get("123"); // { id: "123", name: "John" }
+ * const changes = await users.getChangesSince(); // { version, full: true, changed, deleted: [] }
+ * await users.close();
+ * ```
+ */
+export declare class SqliteStorage<T> implements CollectionStorage<T> {
+    /** The database file, or `:memory:`. */
+    readonly path: string;
+    /** The table of the items. */
+    readonly table: string;
+    private readonly maxTombstones;
+    /** The quoted table name, for the SQL text. */
+    private readonly quoted;
+    private readonly opening;
+    private closed;
+    constructor(options: SqliteStorageOptions);
+    get(id: string): Promise<T | undefined>;
+    getAll(): Promise<T[]>;
+    /** Every item with its id, in the order of the first write of each id. */
+    getEntries(): Promise<Array<[string, T]>>;
+    /**
+     * The changes after a version (roadmap R28). A version of another storage, of another database
+     * file, or older than the dropped deletes gives all items (`full: true`). A version stays valid
+     * after a restart, because the change log is in the file.
+     */
+    getChangesSince(since?: string): Promise<StorageChanges<T>>;
+    find(predicate: (item: T) => boolean): Promise<T[]>;
+    has(id: string): Promise<boolean>;
+    size(): Promise<number>;
+    set(id: string, value: T): Promise<void>;
+    delete(id: string): Promise<boolean>;
+    clear(): Promise<void>;
+    /** This method sets several items in one transaction. When one value is not JSON, nothing changes. */
+    setBatch(items: Array<[string, T]>): Promise<void>;
+    /** This method deletes several items in one transaction. */
+    deleteBatch(ids: string[]): Promise<number>;
+    getBatch(ids: string[]): Promise<Map<string, T>>;
+    /**
+     * This method writes the database file. Each write ends after its file write already, so a
+     * caller needs it only after a failed file write.
+     */
+    flush(): Promise<void>;
+    /**
+     * This method writes the file and releases the database. The items stay in the file. A new
+     * storage of the same file and table reads them, and the versions of this storage stay valid.
+     * After `close()`, each operation throws.
+     */
+    close(): Promise<void>;
+    getMetadata(): Promise<StorageMetadata>;
+    /** This method opens the database, and makes the tables of the collection and of the change log. */
+    private open;
+    /** The open database. It throws after `close()`. */
+    private database;
+    private checkOpen;
+    private entries;
+    private counter;
+    /**
+     * One write: the change in a transaction with the change log, then the file write. `next` gives
+     * the next number of the change log. A write that changes nothing writes no file.
+     */
+    private write;
+    /** This method writes an item. An existing id keeps its place in the order. */
+    private put;
+    /** This method deletes an item. True when it existed. */
+    private remove;
+    private logChange;
+    /** This method drops the oldest deletes above the limit, and moves the floor of the change log. */
+    private trimTombstones;
+}
+//# sourceMappingURL=storage.d.ts.map

package/dist/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"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"}