@procedures/sqlite 0.4.0 → 0.6.0

package/dist/storage.d.ts

@@ -3,28 +3,31 @@
  *
  * `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.
+ * `ProcedureServer`, an `ApiStorage` server and a `HybridStorage` can use it.
  *
+ * - The storage has two engines (the option `engine`). The engine `node` is `node:sqlite` of
+ *   Node.js: it writes only the changed pages of the file. The engine `sqljs` is sql.js (SQLite in
+ *   WebAssembly) through `@mark1russell7/docker-sqlite`: it keeps the database in memory and
+ *   writes the whole file after a write. The default `auto` uses `node` when Node.js has it.
+ * - The two engines use the same file format: a file of one engine opens with the other.
  * - 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.
+ * - The storages of one file in one process share one database. Thus the storages of two tables
+ *   in one file keep the changes of each other.
+ * - A storage that only reads does not make the file.
  */
-import type { CollectionStorage, StorageChanges, StorageMetadata } from "@procedures/client";
-/** The path of a database that is only in memory. */
-export declare const MEMORY_PATH = ":memory:";
+import { type CollectionStorage, type Duration, type StorageChanges, type StorageMetadata } from "@procedures/client";
+import { type SqliteEngine, type SqliteEngineName } from "./engines.js";
+export { MEMORY_PATH, isNodeSqliteAvailable, type SqliteEngine, type SqliteEngineName } from "./engines.js";
 /** 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.
+     * storage makes the file, and its folder, at the first write that changes an item.
      */
     path: string;
     /**
@@ -38,6 +41,28 @@ export interface SqliteStorageOptions {
      * @default 10000
      */
     maxTombstones?: number;
+    /**
+     * The SQLite engine.
+     *
+     * - `node`: the module `node:sqlite` of Node.js 22.13 or later. It writes only the changes, and
+     *   the file is in WAL mode. Two processes can use one file.
+     * - `sqljs`: sql.js, SQLite in WebAssembly. It keeps the database in memory, and it writes the
+     *   whole file after a write.
+     * - `auto`: `node` when Node.js has `node:sqlite`, and else `sqljs`.
+     *
+     * The storages of one file in one process share one database, and thus one engine. The first
+     * storage of the file sets it. A storage with another engine than `auto` refuses a database
+     * of the other engine.
+     * @default "auto"
+     */
+    engine?: SqliteEngine;
+    /**
+     * The time that a write of the engine `node` waits for the lock of another process, for example
+     * `seconds(5)`. After it, the write fails with the error `database is locked`. The first
+     * storage of a file sets it.
+     * @default 5 seconds
+     */
+    busyTimeout?: Duration;
 }
 /**
  * This function gives the name when it is a permitted table name. Else it throws a `TypeError`. The name goes
@@ -53,6 +78,7 @@ export declare function checkTableName(name: unknown): string;
  * 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.getEngine(); // "node" on Node.js 22.13 or later, else "sqljs"
  * await users.close();
  * ```
  */
@@ -61,6 +87,8 @@ export declare class SqliteStorage<T> implements CollectionStorage<T> {
     readonly path: string;
     /** The table of the items. */
     readonly table: string;
+    /** The engine choice of the options. `getEngine()` gives the engine that the storage uses. */
+    readonly engine: SqliteEngine;
     private readonly maxTombstones;
     /** The quoted table name, for the SQL text. */
     private readonly quoted;
@@ -71,10 +99,13 @@ export declare class SqliteStorage<T> implements CollectionStorage<T> {
     getAll(): Promise<T[]>;
     /** Every item with its id, in the order of the first write of each id. */
     getEntries(): Promise<Array<[string, T]>>;
+    /** The ids of the items, in the order of the entries. The storage does not read the values. */
+    getIds(): Promise<string[]>;
     /**
      * 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.
+     * after a restart, because the change log is in the file. The reads run in one read
+     * transaction, so a write of another process does not come between them.
      */
     getChangesSince(since?: string): Promise<StorageChanges<T>>;
     find(predicate: (item: T) => boolean): Promise<T[]>;
@@ -88,30 +119,40 @@ export declare class SqliteStorage<T> implements CollectionStorage<T> {
     /** This method deletes several items in one transaction. */
     deleteBatch(ids: string[]): Promise<number>;
     getBatch(ids: string[]): Promise<Map<string, T>>;
+    /** The engine that the storage uses: `node` or `sqljs`. With the option `auto`, the open decides it. */
+    getEngine(): Promise<SqliteEngineName>;
     /**
      * 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.
+     * caller needs it only after a failed file write of the engine `sqljs`. The engine `node`
+     * writes each change at its commit.
      */
     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.
+     * After `close()`, each operation rejects, and a second `close()` does nothing.
      */
     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()`. */
+    /** The open database. It throws after `close()`, so the promise of the operation rejects. */
     private database;
+    private sharedDatabase;
     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.
+     * One write: the change in a transaction with the change log, then the file write of the engine
+     * `sqljs`. `next` gives the next number of the change log. A write that changes nothing writes
+     * no file.
+     *
+     * Before the first write, the engine `node` keeps the database of a missing file in memory, with
+     * no item. A write first tests its change there. When it changes an item, the storage makes the
+     * file and runs the write in it.
      */
     private write;
+    private runWrite;
     /** 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. */

package/dist/storage.d.ts.map

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