@starlove/orbit 1.4.1 → 2.0.0

package/lib/adapters/indexeddb/database.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The IndexedDB database the adapter keeps one Orbit in, and the one way it
+ * talks to it: `transact()`, a transaction whose requests are all made from
+ * IndexedDB's own callbacks. An IndexedDB transaction commits by itself as
+ * soon as its code waits for anything else, so nothing here awaits inside a
+ * transaction; a write's body runs before, against memory (./store.ts).
+ *
+ * Object stores (schema version 1):
+ *
+ *   boards    the list of boards, by id, as { n, board }: `n` counts up as
+ *             boards are made, for the port's "then by when it was made"
+ *   settings  small values, by key
+ *   heads     per board: `revision`, raised by every commit, and `seq`, the
+ *             last sequence number given to a row
+ *   rows      every record of every board, keyed [board id, table, key], as
+ *             { t: table, s: sequence, v: record }; the sequence keeps the
+ *             order records were written in, which the port's lists follow
+ *   blobs     bytes, keyed [board id, path]
+ */
+import { OrbitError } from "../../core/errors.ts";
+import type { RegisteredBoard } from "../../core/model.ts";
+export declare const SCHEMA_VERSION = 1;
+export declare const BOARDS = "boards";
+export declare const SETTINGS = "settings";
+export declare const HEADS = "heads";
+export declare const ROWS = "rows";
+export declare const BLOBS = "blobs";
+/** Per board: what the last commit left. */
+export interface Head {
+    board_id: string;
+    revision: number;
+    seq: number;
+}
+/** A board's listing as stored: `n` is its place in the order boards were made. */
+export interface Listed {
+    n: number;
+    board: RegisteredBoard;
+}
+/** One record as stored: its table, its sequence number, the record. */
+export interface Row {
+    t: string;
+    s: number;
+    v: unknown;
+}
+export type RowKey = [string, string, string];
+/** Every row of a board, or of one of its tables. */
+export declare function rowRange(boardId: string, table?: string): IDBKeyRange;
+/** Every blob of a board. */
+export declare function blobRange(boardId: string): IDBKeyRange;
+/** A browser's own failure as the port's: a full disk is `storage_full`, the rest `storage_failed`. */
+export declare function storageError(error: unknown): OrbitError;
+/** Opens (and on first use makes) the database. A database of a newer schema is refused with `data_from_newer_orbit`. */
+export declare function openDatabase(factory: IDBFactory, name: string): Promise<IDBDatabase>;
+/**
+ * Runs `script` as one transaction. The script makes its requests at once
+ * and from their callbacks, and returns a function that reads its answer
+ * once the transaction has committed. `refuse(error)` aborts it: nothing it
+ * wrote remains, and the promise rejects with that error.
+ */
+export declare function transact<T>(db: IDBDatabase, stores: readonly string[], mode: IDBTransactionMode, script: (tx: IDBTransaction, refuse: (error: OrbitError) => void) => () => T): Promise<T>;

package/lib/adapters/indexeddb/database.js

@@ -0,0 +1,126 @@
+/// <reference lib="dom" />
+/**
+ * The IndexedDB database the adapter keeps one Orbit in, and the one way it
+ * talks to it: `transact()`, a transaction whose requests are all made from
+ * IndexedDB's own callbacks. An IndexedDB transaction commits by itself as
+ * soon as its code waits for anything else, so nothing here awaits inside a
+ * transaction; a write's body runs before, against memory (./store.ts).
+ *
+ * Object stores (schema version 1):
+ *
+ *   boards    the list of boards, by id, as { n, board }: `n` counts up as
+ *             boards are made, for the port's "then by when it was made"
+ *   settings  small values, by key
+ *   heads     per board: `revision`, raised by every commit, and `seq`, the
+ *             last sequence number given to a row
+ *   rows      every record of every board, keyed [board id, table, key], as
+ *             { t: table, s: sequence, v: record }; the sequence keeps the
+ *             order records were written in, which the port's lists follow
+ *   blobs     bytes, keyed [board id, path]
+ */
+import { OrbitError, isOrbitError } from "../../core/errors.js";
+export const SCHEMA_VERSION = 1;
+export const BOARDS = "boards";
+export const SETTINGS = "settings";
+export const HEADS = "heads";
+export const ROWS = "rows";
+export const BLOBS = "blobs";
+/** Every row of a board, or of one of its tables. */
+export function rowRange(boardId, table) {
+    return table === undefined ? IDBKeyRange.bound([boardId], [boardId, []]) : IDBKeyRange.bound([boardId, table], [boardId, table, []]);
+}
+/** Every blob of a board. */
+export function blobRange(boardId) {
+    return IDBKeyRange.bound([boardId], [boardId, []]);
+}
+/** A browser's own failure as the port's: a full disk is `storage_full`, the rest `storage_failed`. */
+export function storageError(error) {
+    if (isOrbitError(error))
+        return error;
+    const name = error instanceof Error || (typeof DOMException !== "undefined" && error instanceof DOMException) ? error.name : "";
+    return new OrbitError(name === "QuotaExceededError" ? "storage_full" : "storage_failed", { cause: error });
+}
+/** Opens (and on first use makes) the database. A database of a newer schema is refused with `data_from_newer_orbit`. */
+export function openDatabase(factory, name) {
+    return new Promise((resolve, reject) => {
+        let request;
+        try {
+            request = factory.open(name, SCHEMA_VERSION);
+        }
+        catch (error) {
+            reject(storageError(error));
+            return;
+        }
+        request.onupgradeneeded = () => {
+            const db = request.result;
+            const make = (store, options) => {
+                if (!db.objectStoreNames.contains(store))
+                    db.createObjectStore(store, options);
+            };
+            make(BOARDS);
+            make(SETTINGS);
+            make(HEADS, { keyPath: "board_id" });
+            make(ROWS);
+            make(BLOBS);
+        };
+        request.onsuccess = () => {
+            const db = request.result;
+            // Another tab is opening a newer schema: let it.
+            db.onversionchange = () => {
+                db.close();
+            };
+            resolve(db);
+        };
+        request.onerror = () => {
+            reject(request.error?.name === "VersionError" ? new OrbitError("data_from_newer_orbit", { cause: request.error }) : storageError(request.error));
+        };
+    });
+}
+/**
+ * Runs `script` as one transaction. The script makes its requests at once
+ * and from their callbacks, and returns a function that reads its answer
+ * once the transaction has committed. `refuse(error)` aborts it: nothing it
+ * wrote remains, and the promise rejects with that error.
+ */
+export function transact(db, stores, mode, script) {
+    return new Promise((resolve, reject) => {
+        let tx;
+        try {
+            tx = db.transaction(stores, mode);
+        }
+        catch (error) {
+            reject(storageError(error));
+            return;
+        }
+        let refusal = null;
+        const refuse = (error) => {
+            if (refusal)
+                return;
+            refusal = error;
+            try {
+                tx.abort();
+            }
+            catch {
+                // Already finished or aborting.
+            }
+        };
+        let answer = () => undefined;
+        tx.oncomplete = () => {
+            try {
+                resolve(answer());
+            }
+            catch (error) {
+                reject(storageError(error));
+            }
+        };
+        tx.onabort = () => {
+            reject(refusal ?? storageError(tx.error));
+        };
+        try {
+            answer = script(tx, refuse);
+        }
+        catch (error) {
+            refuse(storageError(error));
+        }
+    });
+}

package/lib/adapters/indexeddb/index.d.ts

@@ -0,0 +1,5 @@
+export { openIndexedDbStore } from "./store.ts";
+export type { IndexedDbStore, IndexedDbStoreOptions } from "./store.ts";
+export { createIndexedDbBlobStore } from "./blobs.ts";
+export { createLocalLocks, webLocks } from "./locks.ts";
+export type { Locks } from "./locks.ts";

package/lib/adapters/indexeddb/index.js

@@ -0,0 +1,3 @@
+export { openIndexedDbStore } from "./store.js";
+export { createIndexedDbBlobStore } from "./blobs.js";
+export { createLocalLocks, webLocks } from "./locks.js";

package/lib/adapters/indexeddb/locks.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The exclusive locks the IndexedDB adapter serialises a board's writes with.
+ * In a browser they are Web Locks (`navigator.locks`), which hold across every
+ * tab of the origin. `createLocalLocks()` is the same promise inside one
+ * JavaScript realm, for tests and for a page that has no Web Locks.
+ */
+export interface Locks {
+    /** Runs `body` once no other holder of `name` is running, and resolves with what it returns. */
+    request<T>(name: string, body: () => Promise<T>): Promise<T>;
+}
+/** The browser's Web Locks, or null where there are none. */
+export declare function webLocks(): Locks | null;
+/** Locks held in this realm only: first come, first served, per name. */
+export declare function createLocalLocks(): Locks;

package/lib/adapters/indexeddb/locks.js

@@ -0,0 +1,40 @@
+/// <reference lib="dom" />
+/**
+ * The exclusive locks the IndexedDB adapter serialises a board's writes with.
+ * In a browser they are Web Locks (`navigator.locks`), which hold across every
+ * tab of the origin. `createLocalLocks()` is the same promise inside one
+ * JavaScript realm, for tests and for a page that has no Web Locks.
+ */
+/** The browser's Web Locks, or null where there are none. */
+export function webLocks() {
+    const manager = globalThis.navigator?.locks;
+    if (!manager)
+        return null;
+    return {
+        request: (name, body) => manager.request(name, () => body())
+    };
+}
+/** Locks held in this realm only: first come, first served, per name. */
+export function createLocalLocks() {
+    const tails = new Map();
+    return {
+        async request(name, body) {
+            const previous = tails.get(name) ?? Promise.resolve();
+            let release = () => undefined;
+            const done = new Promise((resolve) => {
+                release = resolve;
+            });
+            const tail = previous.then(() => done);
+            tails.set(name, tail);
+            await previous;
+            try {
+                return await body();
+            }
+            finally {
+                release();
+                if (tails.get(name) === tail)
+                    tails.delete(name);
+            }
+        }
+    };
+}

package/lib/adapters/indexeddb/store.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The IndexedDB adapter: Orbit's storage port in a browser, shared by every
+ * tab of the origin. `openIndexedDbStore()` gives the store and, as its
+ * `blobs`, the blob store of the same database.
+ *
+ * - **Writes.** An IndexedDB transaction commits by itself once its code
+ *   waits for anything else, so a write can't be one. A write takes the
+ *   board's exclusive lock (a Web Lock, held across tabs), runs its body
+ *   against a copy of the board in memory (the memory adapter's writer, so
+ *   its reads see its own changes and the port's checks are the same), then
+ *   commits what changed in one readwrite transaction. A body that throws
+ *   commits nothing. Card numbers are given under the lock.
+ * - **Reads.** A read loads the board in one readonly transaction, which is
+ *   one committed state, and runs its body against it. It takes no lock, so
+ *   a read never waits for a write. A tab keeps the board it last loaded and
+ *   reuses it while the board's revision is unchanged.
+ * - **watch().** This tab's commits reach its watchers at once; other tabs'
+ *   through a BroadcastChannel, after which the board is read again and the
+ *   events past the last one heard are delivered, in order, once.
+ * - **Search** filters a board's documents in memory, as the memory adapter
+ *   does: a board's documents are few.
+ * - **Backups:** none (`backups` is null); people export a board instead.
+ */
+import type { BlobStore, OrbitStore } from "../../store/types.ts";
+import type { Locks } from "./locks.ts";
+export interface IndexedDbStoreOptions {
+    /** The database's name. Default: `orbit`. */
+    name?: string;
+    /** Default: the page's `indexedDB`. */
+    indexedDB?: IDBFactory;
+    /** The locks that serialise a board's writes. Default: the page's Web Locks (`navigator.locks`), else locks within this page. */
+    locks?: Locks;
+    /** How tabs tell each other about commits. Default: BroadcastChannel; null for none (this tab only). */
+    channel?: ((name: string) => BroadcastChannel) | null;
+}
+export interface IndexedDbStore extends OrbitStore {
+    /** The bytes of the same database. */
+    readonly blobs: BlobStore;
+}
+export declare function openIndexedDbStore(options?: IndexedDbStoreOptions): Promise<IndexedDbStore>;