shelving 1.272.0 → 1.273.0

package/db/cache/DBCache.d.ts

@@ -3,7 +3,7 @@ import type { Identifier, Item } from "../../util/item.js";
 import type { Query } from "../../util/query.js";
 import type { Collection } from "../collection/Collection.js";
 import type { DBProvider } from "../provider/DBProvider.js";
-import type { MemoryDBProvider } from "../provider/MemoryDBProvider.js";
+import { MemoryDBProvider } from "../provider/MemoryDBProvider.js";
 import type { ItemStore } from "../store/ItemStore.js";
 import type { QueryStore } from "../store/QueryStore.js";
 import { CollectionCache } from "./CollectionCache.js";

package/db/cache/DBCache.js

@@ -2,6 +2,7 @@ import { awaitDispose } from "../../util/dispose.js";
 import { setMapItem } from "../../util/map.js";
 import { getSource } from "../../util/source.js";
 import { CacheDBProvider } from "../provider/CacheDBProvider.js";
+import { MemoryDBProvider } from "../provider/MemoryDBProvider.js";
 import { CollectionCache } from "./CollectionCache.js";
 /**
  * Cache of `CollectionCache` objects for multiple collections.
@@ -28,8 +29,8 @@ export class DBCache {
     memory;
     constructor(provider) {
         this.provider = provider;
-        // If the provider chain contains a `CacheDBProvider`, reuse its memory so we can seed stores synchronously.
-        this.memory = getSource(CacheDBProvider, provider)?.memory;
+        // If the provider is itself in-memory (e.g. `MemoryDBProvider` or `StorageDBProvider`), or the chain contains a `CacheDBProvider`, reuse its memory so we can seed stores synchronously.
+        this.memory = provider instanceof MemoryDBProvider ? provider : getSource(CacheDBProvider, provider)?.memory;
     }
     _get(collection) {
         return this._collections.get(collection);

package/db/index.d.ts

@@ -14,6 +14,7 @@ export * from "./provider/MockDBProvider.js";
 export * from "./provider/PostgreSQLProvider.js";
 export * from "./provider/SQLiteProvider.js";
 export * from "./provider/SQLProvider.js";
+export * from "./provider/StorageDBProvider.js";
 export * from "./provider/ThroughDBProvider.js";
 export * from "./provider/ValidationDBProvider.js";
 export * from "./store/ItemStore.js";

package/db/index.js

@@ -14,6 +14,7 @@ export * from "./provider/MockDBProvider.js";
 export * from "./provider/PostgreSQLProvider.js";
 export * from "./provider/SQLiteProvider.js";
 export * from "./provider/SQLProvider.js";
+export * from "./provider/StorageDBProvider.js";
 export * from "./provider/ThroughDBProvider.js";
 export * from "./provider/ValidationDBProvider.js";
 export * from "./store/ItemStore.js";

package/db/provider/MemoryDBProvider.d.ts

@@ -16,7 +16,9 @@ import { DBProvider } from "./DBProvider.js";
  */
 export declare class MemoryDBProvider<I extends Identifier = Identifier, T extends Data = Data> extends DBProvider<I, T> {
     /** List of tables in `{ name: MemoryTable }` format. */
-    private _tables;
+    protected _tables: {
+        [K in string]?: MemoryTable<I, T>;
+    };
     /**
      * Get (or lazily create) the `MemoryTable` backing a collection.
      *
@@ -25,6 +27,15 @@ export declare class MemoryDBProvider<I extends Identifier = Identifier, T exten
      * @see https://shelving.cc/db/MemoryDBProvider/getTable
      */
     getTable<II extends I, TT extends T>(collection: Collection<string, II, TT>): MemoryTable<II, TT>;
+    /**
+     * Create a new `MemoryTable` for a collection (without registering it — use `getTable()` for that).
+     * - Override point for subclasses that back collections with a specialised table, e.g. `StorageDBProvider`.
+     *
+     * @param collection Collection to create a table for.
+     * @example provider.createTable(users) // MemoryTable
+     * @see https://shelving.cc/db/MemoryDBProvider/createTable
+     */
+    createTable<II extends I, TT extends T>(collection: Collection<string, II, TT>): MemoryTable<II, TT>;
     getItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): Promise<OptionalItem<II, TT>>;
     getItemSequence<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): OptionalItemSequence<II, TT>;
     addItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, data: TT): Promise<II>;
@@ -46,6 +57,7 @@ export declare class MemoryDBProvider<I extends Identifier = Identifier, T exten
      * @see https://shelving.cc/db/MemoryDBProvider/setItems
      */
     setItems<II extends I, TT extends T>(collection: Collection<string, II, TT>, items: Items<II, TT>): void;
+    [Symbol.asyncDispose](): Promise<void>;
 }
 /**
  * In-memory table holding the items of a single collection for a `MemoryDBProvider`.
@@ -59,7 +71,7 @@ export declare class MemoryDBProvider<I extends Identifier = Identifier, T exten
  *
  * @see https://shelving.cc/db/MemoryTable
  */
-export declare class MemoryTable<I extends Identifier, T extends Data> {
+export declare class MemoryTable<I extends Identifier, T extends Data> implements AsyncDisposable {
     /** Actual data in this table. */
     protected readonly _data: Map<I, Item<I, T>>;
     /**
@@ -203,4 +215,5 @@ export declare class MemoryTable<I extends Identifier, T extends Data> {
     deleteQuery(query: Query<Item<I, T>>): void;
     setItems(items: Items<I, T>): void;
     setItemsSequence(sequence: AsyncIterable<Items<I, T>>): AsyncIterable<Items<I, T>>;
+    [Symbol.asyncDispose](): Promise<void>;
 }

package/db/provider/MemoryDBProvider.js

@@ -1,6 +1,7 @@
 import { StringSchema } from "../../schema/StringSchema.js";
 import { DeferredSequence } from "../../sequence/DeferredSequence.js";
 import { requireArray } from "../../util/array.js";
+import { awaitDispose } from "../../util/dispose.js";
 import { isArrayEqual } from "../../util/equal.js";
 import { getItem } from "../../util/item.js";
 import { countItems } from "../../util/iterate.js";
@@ -28,7 +29,18 @@ export class MemoryDBProvider extends DBProvider {
      * @see https://shelving.cc/db/MemoryDBProvider/getTable
      */
     getTable(collection) {
-        return (this._tables[collection.name] ||= new MemoryTable(collection));
+        return (this._tables[collection.name] ||= this.createTable(collection));
+    }
+    /**
+     * Create a new `MemoryTable` for a collection (without registering it — use `getTable()` for that).
+     * - Override point for subclasses that back collections with a specialised table, e.g. `StorageDBProvider`.
+     *
+     * @param collection Collection to create a table for.
+     * @example provider.createTable(users) // MemoryTable
+     * @see https://shelving.cc/db/MemoryDBProvider/createTable
+     */
+    createTable(collection) {
+        return new MemoryTable(collection);
     }
     async getItem(collection, id) {
         return this.getTable(collection).getItem(id);
@@ -77,6 +89,11 @@ export class MemoryDBProvider extends DBProvider {
     setItems(collection, items) {
         this.getTable(collection).setItems(items);
     }
+    // Implement `AsyncDisposable`
+    async [Symbol.asyncDispose]() {
+        await awaitDispose(...Object.values(this._tables), // Dispose all tables.
+        super[Symbol.asyncDispose]());
+    }
 }
 /**
  * In-memory table holding the items of a single collection for a `MemoryDBProvider`.
@@ -214,11 +231,7 @@ export class MemoryTable {
         const oldItem = this._data.get(id);
         if (!oldItem)
             return;
-        const nextItem = updateData(oldItem, updates);
-        if (this._data.get(id) !== nextItem) {
-            this._data.set(id, nextItem);
-            this.next.resolve();
-        }
+        this.setItem(id, updateData(oldItem, updates));
     }
     /**
      * Delete an item by its id.
@@ -287,16 +300,8 @@ export class MemoryTable {
      * @see https://shelving.cc/db/MemoryTable/setQuery
      */
     setQuery(query, data) {
-        let changed = false;
-        for (const { id } of queryWritableItems(this._data.values(), query)) {
-            const item = getItem(id, data);
-            if (this._data.get(id) !== item) {
-                this._data.set(id, item);
-                changed = true;
-            }
-        }
-        if (changed)
-            this.next.resolve();
+        for (const { id } of queryWritableItems(this._data.values(), query))
+            this.setItem(id, data);
     }
     /**
      * Apply partial updates to every item matching a query.
@@ -307,41 +312,16 @@ export class MemoryTable {
      * @see https://shelving.cc/db/MemoryTable/updateQuery
      */
     updateQuery(query, updates) {
-        let changed = false;
-        for (const { id } of queryWritableItems(this._data.values(), query)) {
-            const oldItem = this._data.get(id);
-            if (!oldItem)
-                continue;
-            const nextItem = updateData(oldItem, updates);
-            if (this._data.get(id) !== nextItem) {
-                this._data.set(id, nextItem);
-                changed = true;
-            }
-        }
-        if (changed)
-            this.next.resolve();
+        for (const { id } of queryWritableItems(this._data.values(), query))
+            this.updateItem(id, updates);
     }
     deleteQuery(query) {
-        let changed = false;
-        for (const { id } of queryWritableItems(this._data.values(), query)) {
-            if (this._data.has(id)) {
-                this._data.delete(id);
-                changed = true;
-            }
-        }
-        if (changed)
-            this.next.resolve();
+        for (const { id } of queryWritableItems(this._data.values(), query))
+            this.deleteItem(id);
     }
     setItems(items) {
-        let changed = false;
-        for (const item of items) {
-            if (this._data.get(item.id) !== item) {
-                this._data.set(item.id, item);
-                changed = true;
-            }
-        }
-        if (changed)
-            this.next.resolve();
+        for (const item of items)
+            this.setItem(item.id, item);
     }
     async *setItemsSequence(sequence) {
         for await (const items of sequence) {
@@ -349,4 +329,10 @@ export class MemoryTable {
             yield items;
         }
     }
+    // Implement `AsyncDisposable`
+    async [Symbol.asyncDispose]() {
+        await awaitDispose(
+        // Empty by default.
+        );
+    }
 }

package/db/provider/StorageDBProvider.d.ts

@@ -0,0 +1,79 @@
+import type { Data } from "../../util/data.js";
+import type { Identifier, Item } from "../../util/item.js";
+import type { Collection } from "../collection/Collection.js";
+import { MemoryDBProvider, MemoryTable } from "./MemoryDBProvider.js";
+/**
+ * In-memory database provider that persists every collection to a `Storage` — `localStorage`, `sessionStorage`, or anything else with the same interface.
+ *
+ * - Extends `MemoryDBProvider`, so all reads, queries, and realtime sequences are served synchronously from memory, and it can seed `ItemStore` / `QueryStore` and act as the cache inside `CacheDBProvider`. The only difference is that collections are backed by `StorageTable` instead of `MemoryTable`.
+ * - The storage is a required argument (there is no default), so server code that constructs this provider must reference `localStorage` / `sessionStorage` itself — surfacing the mistake at the callsite instead of deep inside this class.
+ * - Treat the persisted data as best-effort: quota is shared across the origin (typically ~5MB) and users can clear it at any time. Data read back from storage is unvalidated — wrap this provider in `ValidationDBProvider` if it may have been written by an older version of your app.
+ * - If the storage is unusable (writes blocked by browser settings, or private browsing with zero quota), the provider degrades to memory-only operation — check the `persistent` flag to warn users their changes won't be saved.
+ *
+ * @example
+ *  const provider = new StorageDBProvider(localStorage);
+ *  if (!provider.persistent) console.warn("Changes won't be saved on this device.");
+ *  const id = await provider.addItem(users, { name: "Dave" });
+ *
+ * @see https://shelving.cc/db/StorageDBProvider
+ */
+export declare class StorageDBProvider<I extends Identifier = Identifier, T extends Data = Data> extends MemoryDBProvider<I, T> {
+    /**
+     * Prefix for every storage key written by this provider.
+     *
+     * @see https://shelving.cc/db/StorageDBProvider/prefix
+     */
+    readonly prefix: string;
+    /**
+     * Whether this provider is actually persisting to storage.
+     * - `false` when storage exists but is unusable (e.g. blocked by browser settings, or private browsing with zero quota) — the provider still works, but data only lives in memory and is lost when the page closes.
+     *
+     * @see https://shelving.cc/db/StorageDBProvider/persistent
+     */
+    readonly persistent: boolean;
+    /** Storage being persisted to, or `undefined` when operating memory-only. */
+    private readonly _storage;
+    /**
+     * @param storage `Storage` instance to persist to, e.g. `localStorage` or `sessionStorage` (required so environments without one, e.g. the server, fail at the callsite).
+     * @param prefix Prefix for every storage key written by this provider, so it can share an origin's storage with other code (defaults to `"shelving:"`).
+     */
+    constructor(storage: Storage, prefix?: string);
+    /** Back collections with a `StorageTable`, or a plain `MemoryTable` when operating memory-only. */
+    createTable<II extends I, TT extends T>(collection: Collection<string, II, TT>): MemoryTable<II, TT>;
+}
+/**
+ * `MemoryTable` that persists its items to a `Storage` instance — self-contained, so it can also be used independently of `StorageDBProvider`.
+ *
+ * - Hydrates itself from storage on construction, then persists each write *before* applying it to memory, so a failed write (e.g. `QuotaExceededError` when the origin's quota is full) throws and leaves memory and storage consistent.
+ * - Items are stored as JSON under keys formatted as `{prefix}{collection}:{id}`, so values must be JSON-serializable. The id in the key is authoritative — an `id` stored inside the JSON is overridden.
+ * - Listens for `storage` events, so changes made in other tabs/windows update memory and notify realtime sequences. Dispose the table (or its provider) to remove the listener.
+ *
+ * @see https://shelving.cc/db/StorageTable
+ */
+export declare class StorageTable<I extends Identifier, T extends Data> extends MemoryTable<I, T> {
+    /** Prefix for every storage key belonging to this table, e.g. `"shelving:users:"`. */
+    private readonly _prefix;
+    /** Storage this table persists to. */
+    private readonly _storage;
+    /** Attached `storage` event listener (so it can be detached on dispose), or `undefined` if none was attached. */
+    private readonly _listener;
+    constructor(collection: Collection<string, I, T>, storage: Storage, prefix?: string);
+    /** Load every persisted item of this table's collection into memory (directly, skipping the persist-back in `setItem()`). */
+    private _hydrate;
+    /** Storage key for an item of this table. */
+    private _key;
+    /** Identifier encoded in a storage key of this table. */
+    private _decodeKey;
+    /** Parse a stored JSON value into an item with the given id, or `undefined` if it's malformed. */
+    private _parse;
+    /**
+     * Apply a `storage` event (a change made in another tab/window) to this table.
+     * - Reuses `setItem()` / `deleteItem()` — re-persisting the value already in storage is a no-op, and same-tab writes don't fire `storage` events, so this can't loop.
+     */
+    private _syncStorage;
+    /** Persist to storage first — a failure (e.g. `QuotaExceededError`) throws before memory changes, keeping the two consistent. */
+    setItem(id: I, data: Item<I, T> | T): void;
+    /** Remove from storage first, keeping storage and memory consistent. */
+    deleteItem(id: I): void;
+    [Symbol.asyncDispose](): Promise<void>;
+}

package/db/provider/StorageDBProvider.js

@@ -0,0 +1,163 @@
+import { UnsupportedError } from "../../error/UnsupportedError.js";
+import { StringSchema } from "../../schema/StringSchema.js";
+import { isData } from "../../util/data.js";
+import { awaitDispose } from "../../util/dispose.js";
+import { getItem } from "../../util/item.js";
+import { MemoryDBProvider, MemoryTable } from "./MemoryDBProvider.js";
+/**
+ * In-memory database provider that persists every collection to a `Storage` — `localStorage`, `sessionStorage`, or anything else with the same interface.
+ *
+ * - Extends `MemoryDBProvider`, so all reads, queries, and realtime sequences are served synchronously from memory, and it can seed `ItemStore` / `QueryStore` and act as the cache inside `CacheDBProvider`. The only difference is that collections are backed by `StorageTable` instead of `MemoryTable`.
+ * - The storage is a required argument (there is no default), so server code that constructs this provider must reference `localStorage` / `sessionStorage` itself — surfacing the mistake at the callsite instead of deep inside this class.
+ * - Treat the persisted data as best-effort: quota is shared across the origin (typically ~5MB) and users can clear it at any time. Data read back from storage is unvalidated — wrap this provider in `ValidationDBProvider` if it may have been written by an older version of your app.
+ * - If the storage is unusable (writes blocked by browser settings, or private browsing with zero quota), the provider degrades to memory-only operation — check the `persistent` flag to warn users their changes won't be saved.
+ *
+ * @example
+ *  const provider = new StorageDBProvider(localStorage);
+ *  if (!provider.persistent) console.warn("Changes won't be saved on this device.");
+ *  const id = await provider.addItem(users, { name: "Dave" });
+ *
+ * @see https://shelving.cc/db/StorageDBProvider
+ */
+export class StorageDBProvider extends MemoryDBProvider {
+    /**
+     * Prefix for every storage key written by this provider.
+     *
+     * @see https://shelving.cc/db/StorageDBProvider/prefix
+     */
+    prefix;
+    /**
+     * Whether this provider is actually persisting to storage.
+     * - `false` when storage exists but is unusable (e.g. blocked by browser settings, or private browsing with zero quota) — the provider still works, but data only lives in memory and is lost when the page closes.
+     *
+     * @see https://shelving.cc/db/StorageDBProvider/persistent
+     */
+    persistent;
+    /** Storage being persisted to, or `undefined` when operating memory-only. */
+    _storage;
+    /**
+     * @param storage `Storage` instance to persist to, e.g. `localStorage` or `sessionStorage` (required so environments without one, e.g. the server, fail at the callsite).
+     * @param prefix Prefix for every storage key written by this provider, so it can share an origin's storage with other code (defaults to `"shelving:"`).
+     */
+    constructor(storage, prefix = "shelving:") {
+        super();
+        this.prefix = prefix;
+        if (!storage)
+            throw new UnsupportedError("StorageDBProvider requires a Storage, e.g. localStorage or sessionStorage", {
+                caller: StorageDBProvider,
+            });
+        // Probe with a write+remove: private browsing can expose a `Storage` whose every write throws.
+        try {
+            const probe = `${prefix}?`;
+            storage.setItem(probe, "?");
+            storage.removeItem(probe);
+            this.persistent = true;
+            this._storage = storage;
+        }
+        catch {
+            // Unusable storage — degrade to memory-only.
+            this.persistent = false;
+            this._storage = undefined;
+        }
+    }
+    /** Back collections with a `StorageTable`, or a plain `MemoryTable` when operating memory-only. */
+    createTable(collection) {
+        return this._storage ? new StorageTable(collection, this._storage, this.prefix) : super.createTable(collection);
+    }
+}
+/**
+ * `MemoryTable` that persists its items to a `Storage` instance — self-contained, so it can also be used independently of `StorageDBProvider`.
+ *
+ * - Hydrates itself from storage on construction, then persists each write *before* applying it to memory, so a failed write (e.g. `QuotaExceededError` when the origin's quota is full) throws and leaves memory and storage consistent.
+ * - Items are stored as JSON under keys formatted as `{prefix}{collection}:{id}`, so values must be JSON-serializable. The id in the key is authoritative — an `id` stored inside the JSON is overridden.
+ * - Listens for `storage` events, so changes made in other tabs/windows update memory and notify realtime sequences. Dispose the table (or its provider) to remove the listener.
+ *
+ * @see https://shelving.cc/db/StorageTable
+ */
+export class StorageTable extends MemoryTable {
+    /** Prefix for every storage key belonging to this table, e.g. `"shelving:users:"`. */
+    _prefix;
+    /** Storage this table persists to. */
+    _storage;
+    /** Attached `storage` event listener (so it can be detached on dispose), or `undefined` if none was attached. */
+    _listener;
+    constructor(collection, storage, prefix = "shelving:") {
+        super(collection);
+        this._storage = storage;
+        this._prefix = `${prefix}${collection.name}:`;
+        this._hydrate();
+        // Changes made in other tabs/windows arrive as `storage` events on the global scope.
+        if (typeof globalThis.addEventListener === "function") {
+            this._listener = event => this._syncStorage(event);
+            globalThis.addEventListener("storage", this._listener);
+        }
+    }
+    /** Load every persisted item of this table's collection into memory (directly, skipping the persist-back in `setItem()`). */
+    _hydrate() {
+        for (let i = 0; i < this._storage.length; i++) {
+            const key = this._storage.key(i);
+            if (key?.startsWith(this._prefix)) {
+                const id = this._decodeKey(key);
+                const item = this._parse(id, this._storage.getItem(key));
+                if (item)
+                    this._data.set(id, item);
+            }
+        }
+    }
+    /** Storage key for an item of this table. */
+    _key(id) {
+        return `${this._prefix}${id}`;
+    }
+    /** Identifier encoded in a storage key of this table. */
+    _decodeKey(key) {
+        const raw = key.slice(this._prefix.length);
+        return (this.collection.id instanceof StringSchema ? raw : Number(raw)); // `as I` needed: TypeScript can't narrow I from the schema check.
+    }
+    /** Parse a stored JSON value into an item with the given id, or `undefined` if it's malformed. */
+    _parse(id, value) {
+        if (value) {
+            try {
+                const data = JSON.parse(value);
+                if (isData(data))
+                    return getItem(id, data); // `as T` needed: stored values are unvalidated — wrap the provider in `ValidationDBProvider` to validate them.
+            }
+            catch {
+                // Malformed values are skipped, not deleted — they may belong to other code sharing the prefix.
+            }
+        }
+    }
+    /**
+     * Apply a `storage` event (a change made in another tab/window) to this table.
+     * - Reuses `setItem()` / `deleteItem()` — re-persisting the value already in storage is a no-op, and same-tab writes don't fire `storage` events, so this can't loop.
+     */
+    _syncStorage({ storageArea, key, newValue }) {
+        if (storageArea !== this._storage)
+            return;
+        if (key === null) {
+            this.deleteQuery({}); // A `null` key means the other tab called `storage.clear()`.
+        }
+        else if (key.startsWith(this._prefix)) {
+            const id = this._decodeKey(key);
+            const item = newValue !== null ? this._parse(id, newValue) : undefined;
+            item ? this.setItem(id, item) : this.deleteItem(id);
+        }
+    }
+    /** Persist to storage first — a failure (e.g. `QuotaExceededError`) throws before memory changes, keeping the two consistent. */
+    setItem(id, data) {
+        const item = getItem(id, data);
+        if (this._data.get(id) !== item)
+            this._storage.setItem(this._key(id), JSON.stringify(item));
+        super.setItem(id, item);
+    }
+    /** Remove from storage first, keeping storage and memory consistent. */
+    deleteItem(id) {
+        if (this._data.has(id))
+            this._storage.removeItem(this._key(id));
+        super.deleteItem(id);
+    }
+    // Implement `AsyncDisposable`
+    async [Symbol.asyncDispose]() {
+        await awaitDispose(() => this._listener && globalThis.removeEventListener("storage", this._listener), // Stop listening for `storage` events.
+        super[Symbol.asyncDispose]());
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.272.0",
+	"version": "1.273.0",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",