shelving 1.274.0 → 1.275.0

package/package.json

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

package/test/basics.d.ts

@@ -1,3 +1,4 @@
+import { Collection } from "../db/collection/Collection.js";
 import type { Item } from "../util/item.js";
 import type { ValidatorType } from "../util/validate.js";
 /**
@@ -97,3 +98,22 @@ export declare const basics: ReadonlyArray<BasicItem>;
  * @see https://shelving.cc/test/basic999
  */
 export declare const basic999: BasicData;
+/**
+ * Collection of `BasicData` items keyed by string id, for testing database providers.
+ *
+ * @see https://shelving.cc/test/BASICS_COLLECTION
+ */
+export declare const BASICS_COLLECTION: Collection<"basics", string, {
+    str: string;
+    num: number;
+    group: "a" | "b" | "c";
+    tags: import("../index.js").ImmutableArray<string>;
+    odd: boolean;
+    even: boolean;
+    sub: {
+        str: /*elided*/ any;
+        num: /*elided*/ any;
+        odd: /*elided*/ any;
+        even: /*elided*/ any;
+    };
+}>;

package/test/basics.js

@@ -1,3 +1,4 @@
+import { Collection } from "../db/collection/Collection.js";
 import { ARRAY } from "../schema/ArraySchema.js";
 import { BOOLEAN } from "../schema/BooleanSchema.js";
 import { CHOICE } from "../schema/ChoiceSchema.js";
@@ -173,3 +174,9 @@ export const basic999 = {
     tags: ["odd", "prime"],
     sub: { str: "zzz", num: 999, even: false, odd: true },
 };
+/**
+ * Collection of `BasicData` items keyed by string id, for testing database providers.
+ *
+ * @see https://shelving.cc/test/BASICS_COLLECTION
+ */
+export const BASICS_COLLECTION = new Collection("basics", STRING, BASIC_SCHEMA);

package/test/index.d.ts

@@ -1,26 +1,5 @@
-import { Collection } from "../db/collection/Collection.js";
 export * from "./basics.js";
 export * from "./people.js";
 export * from "./TransactionTestDBProvider.js";
+export * from "./testDBProvider.js";
 export * from "./util.js";
-export declare const BASICS_COLLECTION: Collection<"basics", string, {
-    str: string;
-    num: number;
-    group: "a" | "b" | "c";
-    tags: import("../index.js").ImmutableArray<string>;
-    odd: boolean;
-    even: boolean;
-    sub: {
-        str: /*elided*/ any;
-        num: /*elided*/ any;
-        odd: /*elided*/ any;
-        even: /*elided*/ any;
-    };
-}>;
-export declare const PEOPLE_COLLECTION: Collection<"people", string, {
-    name: {
-        first: /*elided*/ any;
-        last: /*elided*/ any;
-    };
-    birthday: string | null;
-}>;

package/test/index.js

@@ -1,10 +1,5 @@
-import { Collection } from "../db/collection/Collection.js";
-import { STRING } from "../schema/StringSchema.js";
-import { BASIC_SCHEMA } from "./basics.js";
-import { PERSON_SCHEMA } from "./people.js";
 export * from "./basics.js";
 export * from "./people.js";
 export * from "./TransactionTestDBProvider.js";
+export * from "./testDBProvider.js";
 export * from "./util.js";
-export const BASICS_COLLECTION = new Collection("basics", STRING, BASIC_SCHEMA);
-export const PEOPLE_COLLECTION = new Collection("people", STRING, PERSON_SCHEMA);

package/test/people.d.ts

@@ -1,3 +1,4 @@
+import { Collection } from "../db/collection/Collection.js";
 import type { Item } from "../util/item.js";
 import type { ValidatorType } from "../util/validate.js";
 /**
@@ -60,3 +61,15 @@ export declare const person5: PersonItem;
  * @see https://shelving.cc/test/people
  */
 export declare const people: ReadonlyArray<PersonItem>;
+/**
+ * Collection of `PersonData` items keyed by string id, for testing database providers.
+ *
+ * @see https://shelving.cc/test/PEOPLE_COLLECTION
+ */
+export declare const PEOPLE_COLLECTION: Collection<"people", string, {
+    name: {
+        first: /*elided*/ any;
+        last: /*elided*/ any;
+    };
+    birthday: string | null;
+}>;

package/test/people.js

@@ -1,6 +1,7 @@
+import { Collection } from "../db/collection/Collection.js";
 import { DATA } from "../schema/DataSchema.js";
 import { NULLABLE_DATE } from "../schema/DateSchema.js";
-import { REQUIRED_STRING } from "../schema/StringSchema.js";
+import { REQUIRED_STRING, STRING } from "../schema/StringSchema.js";
 /**
  * Schema for a test "person" fixture, with a nested `name` and a nullable `birthday`.
  *
@@ -46,3 +47,9 @@ export const person5 = { id: "person5", name: { first: "Terry", last: "Times" },
  * @see https://shelving.cc/test/people
  */
 export const people = [person1, person2, person3, person4, person5];
+/**
+ * Collection of `PersonData` items keyed by string id, for testing database providers.
+ *
+ * @see https://shelving.cc/test/PEOPLE_COLLECTION
+ */
+export const PEOPLE_COLLECTION = new Collection("people", STRING, PERSON_SCHEMA);

package/test/testDBProvider.d.ts

@@ -0,0 +1,22 @@
+import type { DBProvider } from "../db/provider/DBProvider.js";
+import type { Data } from "../util/data.js";
+/** Options for `testDBProvider()`, declaring the capabilities of the provider under test. */
+export interface TestDBProviderOptions {
+    /** Whether the provider supports realtime sequences — when `false`, sequences are asserted to throw `UnsupportedError`. @default true */
+    readonly realtime?: boolean;
+    /** Whether the provider supports `transact()` — when `false`, it is asserted to throw `UnsupportedError`. @default false */
+    readonly transactions?: boolean;
+}
+/**
+ * Register the universal `DBProvider` contract test suite against a provider, so every backend proves the same behaviour.
+ *
+ * - Calls `createProvider()` fresh for every test and wipes `BASICS_COLLECTION` and `PEOPLE_COLLECTION` first, so persistent backends (e.g. an emulator) start each test clean.
+ * - Declare the provider's capabilities via options — unsupported capabilities are asserted to throw `UnsupportedError` rather than skipped.
+ *
+ * @param name Name for the provider used in the `describe` block.
+ * @param createProvider Create (or return) the provider instance to test.
+ * @param options Capability flags for the provider under test.
+ * @example testDBProvider("MemoryDBProvider", () => new MemoryDBProvider<string>());
+ * @see https://shelving.cc/test/testDBProvider
+ */
+export declare function testDBProvider(name: string, createProvider: () => DBProvider<string, Data> | PromiseLike<DBProvider<string, Data>>, { realtime, transactions }?: TestDBProviderOptions): void;

package/test/testDBProvider.js

@@ -0,0 +1,272 @@
+import { describe, expect, test } from "bun:test";
+import { RequiredError } from "../error/RequiredError.js";
+import { UnsupportedError } from "../error/UnsupportedError.js";
+import { runMicrotasks } from "../util/async.js";
+import { runSequence } from "../util/sequence.js";
+import { BASICS_COLLECTION, basic1, basic2, basic3, basic999, basics } from "./basics.js";
+import { PEOPLE_COLLECTION, person1 } from "./people.js";
+import { expectOrderedItems, expectUnorderedItems } from "./util.js";
+/**
+ * Register the universal `DBProvider` contract test suite against a provider, so every backend proves the same behaviour.
+ *
+ * - Calls `createProvider()` fresh for every test and wipes `BASICS_COLLECTION` and `PEOPLE_COLLECTION` first, so persistent backends (e.g. an emulator) start each test clean.
+ * - Declare the provider's capabilities via options — unsupported capabilities are asserted to throw `UnsupportedError` rather than skipped.
+ *
+ * @param name Name for the provider used in the `describe` block.
+ * @param createProvider Create (or return) the provider instance to test.
+ * @param options Capability flags for the provider under test.
+ * @example testDBProvider("MemoryDBProvider", () => new MemoryDBProvider<string>());
+ * @see https://shelving.cc/test/testDBProvider
+ */
+export function testDBProvider(name, createProvider, { realtime = true, transactions = false } = {}) {
+    // Create the provider and wipe both fixture collections so each test starts clean.
+    async function init() {
+        const provider = await createProvider();
+        await provider.deleteQuery(BASICS_COLLECTION, {});
+        await provider.deleteQuery(PEOPLE_COLLECTION, {});
+        return provider;
+    }
+    describe(`DBProvider contract: ${name}`, () => {
+        test("sets, gets, and deletes items", async () => {
+            const db = await init();
+            // Set and get.
+            await db.setItem(BASICS_COLLECTION, "basic1", basic1);
+            await db.setItem(BASICS_COLLECTION, "basic2", basic2);
+            await db.setItem(PEOPLE_COLLECTION, "person1", person1);
+            expect(await db.getItem(BASICS_COLLECTION, "basic1")).toMatchObject(basic1);
+            expect(await db.getItem(BASICS_COLLECTION, "basic2")).toMatchObject(basic2);
+            expect(await db.getItem(BASICS_COLLECTION, "basicNone")).toBe(undefined);
+            expect(await db.getItem(PEOPLE_COLLECTION, "person1")).toMatchObject(person1);
+            // Overwrite.
+            await db.setItem(BASICS_COLLECTION, "basic1", { ...basic1, str: "NEW" });
+            expect(await db.getItem(BASICS_COLLECTION, "basic1")).toMatchObject({ ...basic1, str: "NEW" });
+            // Require.
+            expect(await db.requireItem(BASICS_COLLECTION, "basic2")).toMatchObject(basic2);
+            try {
+                await db.requireItem(BASICS_COLLECTION, "basicNone");
+                expect.unreachable();
+            }
+            catch (thrown) {
+                expect(thrown).toBeInstanceOf(RequiredError);
+            }
+            // Delete (including a missing item, which is a no-op).
+            await db.deleteItem(BASICS_COLLECTION, "basic1");
+            await db.deleteItem(BASICS_COLLECTION, "basicNone");
+            expect(await db.getItem(BASICS_COLLECTION, "basic1")).toBe(undefined);
+            expect(await db.countQuery(BASICS_COLLECTION, {})).toBe(1);
+            expect(await db.countQuery(PEOPLE_COLLECTION, {})).toBe(1);
+        });
+        test("adds items with generated ids", async () => {
+            const db = await init();
+            const id1 = await db.addItem(BASICS_COLLECTION, basic999);
+            const id2 = await db.addItem(BASICS_COLLECTION, basic999);
+            expect(typeof id1).toBe("string");
+            expect(typeof id2).toBe("string");
+            expect(id1).not.toBe(id2);
+            expect(await db.getItem(BASICS_COLLECTION, id1)).toMatchObject(basic999);
+            expect(await db.countQuery(BASICS_COLLECTION, {})).toBe(2);
+        });
+        test("updates items with set, sum, and array updates", async () => {
+            const db = await init();
+            await db.setItem(BASICS_COLLECTION, "basic1", basic1);
+            // Set and sum updates.
+            await db.updateItem(BASICS_COLLECTION, "basic1", { str: "NEW", "+=num": 100 });
+            expect(await db.getItem(BASICS_COLLECTION, "basic1")).toMatchObject({ ...basic1, str: "NEW", num: basic1.num + 100 });
+            // Array with/omit updates.
+            await db.updateItem(BASICS_COLLECTION, "basic1", { "+[]tags": "extra" });
+            expect((await db.requireItem(BASICS_COLLECTION, "basic1")).tags).toEqual([...basic1.tags, "extra"]);
+            await db.updateItem(BASICS_COLLECTION, "basic1", { "-[]tags": "extra" });
+            expect((await db.requireItem(BASICS_COLLECTION, "basic1")).tags).toEqual(basic1.tags);
+        });
+        test("gets queries with filters", async () => {
+            const db = await init();
+            for (const { id, ...data } of basics)
+                await db.setItem(BASICS_COLLECTION, id, data);
+            // Equality filters.
+            expectUnorderedItems(await db.getQuery(BASICS_COLLECTION, { str: "aaa" }), ["basic1"]);
+            expectUnorderedItems(await db.getQuery(BASICS_COLLECTION, { str: "NOPE" }), []);
+            expectUnorderedItems(await db.getQuery(BASICS_COLLECTION, { num: 300 }), ["basic3"]);
+            expectUnorderedItems(await db.getQuery(BASICS_COLLECTION, { group: "a" }), ["basic1", "basic2", "basic3"]);
+            expectUnorderedItems(await db.getQuery(BASICS_COLLECTION, { group: "b" }), ["basic4", "basic5", "basic6"]);
+            // ArrayContains filters.
+            expectUnorderedItems(await db.getQuery(BASICS_COLLECTION, { "tags[]": "odd" }), ["basic1", "basic3", "basic5", "basic7", "basic9"]);
+            expectUnorderedItems(await db.getQuery(BASICS_COLLECTION, { "tags[]": "NOPE" }), []);
+            // In filters.
+            expectUnorderedItems(await db.getQuery(BASICS_COLLECTION, { num: [200, 600, 900, 999999] }), ["basic2", "basic6", "basic9"]);
+            expectUnorderedItems(await db.getQuery(BASICS_COLLECTION, { id: ["basic1", "basic5", "basicNone"] }), ["basic1", "basic5"]);
+            expectUnorderedItems(await db.getQuery(BASICS_COLLECTION, { num: [] }), []);
+            // Range filters.
+            expectUnorderedItems(await db.getQuery(BASICS_COLLECTION, { "num<": 300 }), ["basic1", "basic2"]);
+            expectUnorderedItems(await db.getQuery(BASICS_COLLECTION, { "num<=": 300 }), ["basic1", "basic2", "basic3"]);
+            expectUnorderedItems(await db.getQuery(BASICS_COLLECTION, { "num>": 700 }), ["basic8", "basic9"]);
+            expectUnorderedItems(await db.getQuery(BASICS_COLLECTION, { "num>=": 700 }), ["basic7", "basic8", "basic9"]);
+            expectUnorderedItems(await db.getQuery(BASICS_COLLECTION, { "str<": "ccc" }), ["basic1", "basic2"]);
+        });
+        test("gets queries with sorts and limits", async () => {
+            const db = await init();
+            for (const { id, ...data } of basics)
+                await db.setItem(BASICS_COLLECTION, id, data);
+            const keysAsc = ["basic1", "basic2", "basic3", "basic4", "basic5", "basic6", "basic7", "basic8", "basic9"];
+            const keysDesc = [...keysAsc].reverse();
+            expectOrderedItems(await db.getQuery(BASICS_COLLECTION, { $order: "id" }), keysAsc);
+            expectOrderedItems(await db.getQuery(BASICS_COLLECTION, { $order: "!id" }), keysDesc);
+            expectOrderedItems(await db.getQuery(BASICS_COLLECTION, { $order: "str" }), keysAsc);
+            expectOrderedItems(await db.getQuery(BASICS_COLLECTION, { $order: "!str" }), keysDesc);
+            expectOrderedItems(await db.getQuery(BASICS_COLLECTION, { $order: "num" }), keysAsc);
+            expectOrderedItems(await db.getQuery(BASICS_COLLECTION, { $order: "!num" }), keysDesc);
+            expectOrderedItems(await db.getQuery(BASICS_COLLECTION, { $order: "id", $limit: 2 }), ["basic1", "basic2"]);
+            expectOrderedItems(await db.getQuery(BASICS_COLLECTION, { $order: "!id", $limit: 1 }), ["basic9"]);
+            expectOrderedItems(await db.getQuery(BASICS_COLLECTION, { "tags[]": "prime", $order: "!id", $limit: 2 }), ["basic7", "basic5"]);
+        });
+        test("counts queries", async () => {
+            const db = await init();
+            for (const { id, ...data } of basics)
+                await db.setItem(BASICS_COLLECTION, id, data);
+            expect(await db.countQuery(BASICS_COLLECTION)).toBe(9);
+            expect(await db.countQuery(BASICS_COLLECTION, {})).toBe(9);
+            expect(await db.countQuery(BASICS_COLLECTION, { group: "a" })).toBe(3);
+            expect(await db.countQuery(BASICS_COLLECTION, { str: "NOPE" })).toBe(0);
+            expect(await db.countQuery(BASICS_COLLECTION, { $limit: 4 })).toBe(4);
+        });
+        test("gets first items", async () => {
+            const db = await init();
+            for (const { id, ...data } of basics)
+                await db.setItem(BASICS_COLLECTION, id, data);
+            expect(await db.getFirst(BASICS_COLLECTION, { $order: "num" })).toMatchObject(basic1);
+            expect(await db.getFirst(BASICS_COLLECTION, { str: "NOPE", $order: "num" })).toBe(undefined);
+            expect(await db.requireFirst(BASICS_COLLECTION, { $order: "num" })).toMatchObject(basic1);
+            try {
+                await db.requireFirst(BASICS_COLLECTION, { str: "NOPE", $order: "num" });
+                expect.unreachable();
+            }
+            catch (thrown) {
+                expect(thrown).toBeInstanceOf(RequiredError);
+            }
+        });
+        test("sets, updates, and deletes queries", async () => {
+            const db = await init();
+            for (const { id, ...data } of basics)
+                await db.setItem(BASICS_COLLECTION, id, data);
+            // Set every matching item to the same data.
+            await db.setQuery(BASICS_COLLECTION, { group: "a" }, basic999);
+            expect(await db.getItem(BASICS_COLLECTION, "basic1")).toMatchObject(basic999);
+            expect(await db.getItem(BASICS_COLLECTION, "basic2")).toMatchObject(basic999);
+            expect(await db.getItem(BASICS_COLLECTION, "basic4")).toMatchObject({ id: "basic4", group: "b" }); // Non-matching items unchanged.
+            // Update every matching item.
+            await db.updateQuery(BASICS_COLLECTION, { group: "b" }, { str: "UPDATED" });
+            expectUnorderedItems(await db.getQuery(BASICS_COLLECTION, { str: "UPDATED" }), ["basic4", "basic5", "basic6"]);
+            // Delete every matching item.
+            await db.deleteQuery(BASICS_COLLECTION, { group: "c" });
+            expect(await db.countQuery(BASICS_COLLECTION, {})).toBe(6);
+            await db.deleteQuery(BASICS_COLLECTION, {});
+            expect(await db.countQuery(BASICS_COLLECTION, {})).toBe(0);
+        });
+        if (realtime) {
+            test("subscribes to an item", async () => {
+                const db = await init();
+                const calls = [];
+                const stop = runSequence(db.getItemSequence(BASICS_COLLECTION, "basic1"), v => void calls.push(v));
+                await runMicrotasks();
+                expect(calls.length).toBe(1);
+                expect(calls[0]).toBe(undefined);
+                await db.setItem(BASICS_COLLECTION, "basic1", basic1);
+                await runMicrotasks();
+                expect(calls.length).toBe(2);
+                expect(calls[1]).toMatchObject(basic1);
+                await db.deleteItem(BASICS_COLLECTION, "basic1");
+                await runMicrotasks();
+                expect(calls.length).toBe(3);
+                expect(calls[2]).toBe(undefined);
+                stop();
+            });
+            test("subscribes to a query", async () => {
+                const db = await init();
+                const calls = [];
+                const stop = runSequence(db.getQuerySequence(BASICS_COLLECTION, { $order: "id" }), v => void calls.push(v));
+                await runMicrotasks();
+                expectOrderedItems(calls[0] ?? [], []);
+                await db.setItem(BASICS_COLLECTION, "basic1", basic1);
+                await runMicrotasks();
+                expectOrderedItems(calls[1] ?? [], ["basic1"]);
+                await db.setItem(BASICS_COLLECTION, "basic2", basic2);
+                await runMicrotasks();
+                expectOrderedItems(calls[2] ?? [], ["basic1", "basic2"]);
+                stop();
+            });
+        }
+        else {
+            test("sequences are not supported", async () => {
+                const db = await init();
+                expect(() => db.getItemSequence(BASICS_COLLECTION, "basic1")).toThrow(UnsupportedError);
+                expect(() => db.getQuerySequence(BASICS_COLLECTION, {})).toThrow(UnsupportedError);
+            });
+        }
+        if (transactions) {
+            test("transact(): commits reads and writes atomically", async () => {
+                const db = await init();
+                await db.setItem(BASICS_COLLECTION, "basic1", basic1);
+                await db.setItem(BASICS_COLLECTION, "basic2", basic2);
+                const id = await db.transact(async (tx) => {
+                    // Reads inside the transaction see committed items.
+                    expect(await tx.getItem(BASICS_COLLECTION, "basic1")).toMatchObject(basic1);
+                    expect(await tx.countQuery(BASICS_COLLECTION, {})).toBe(2);
+                    expectUnorderedItems(await tx.getQuery(BASICS_COLLECTION, { group: "a" }), ["basic1", "basic2"]);
+                    // Writes commit together when the callback resolves.
+                    await tx.setItem(BASICS_COLLECTION, "basic3", basic3);
+                    await tx.updateItem(BASICS_COLLECTION, "basic1", { str: "TX", "+=num": 1 });
+                    await tx.deleteItem(BASICS_COLLECTION, "basic2");
+                    return await tx.addItem(BASICS_COLLECTION, basic999);
+                });
+                expect(typeof id).toBe("string");
+                expect(await db.getItem(BASICS_COLLECTION, "basic3")).toMatchObject(basic3);
+                expect(await db.getItem(BASICS_COLLECTION, "basic1")).toMatchObject({ ...basic1, str: "TX", num: basic1.num + 1 });
+                expect(await db.getItem(BASICS_COLLECTION, "basic2")).toBe(undefined);
+                expect(await db.getItem(BASICS_COLLECTION, id)).toMatchObject(basic999);
+            });
+            test("transact(): commits nothing when the callback throws", async () => {
+                const db = await init();
+                await db.setItem(BASICS_COLLECTION, "basic1", basic1);
+                try {
+                    await db.transact(async (tx) => {
+                        await tx.setItem(BASICS_COLLECTION, "basic2", basic2);
+                        await tx.deleteItem(BASICS_COLLECTION, "basic1");
+                        throw new Error("nope");
+                    });
+                    expect.unreachable();
+                }
+                catch (thrown) {
+                    expect(thrown).toBeInstanceOf(Error);
+                    expect(thrown.message).toBe("nope");
+                }
+                expect(await db.getItem(BASICS_COLLECTION, "basic1")).toMatchObject(basic1);
+                expect(await db.getItem(BASICS_COLLECTION, "basic2")).toBe(undefined);
+            });
+            test("transact(): supports query writes", async () => {
+                const db = await init();
+                for (const { id, ...data } of basics)
+                    await db.setItem(BASICS_COLLECTION, id, data);
+                await db.transact(async (tx) => {
+                    await tx.updateQuery(BASICS_COLLECTION, { group: "a" }, { str: "TX" });
+                    await tx.deleteQuery(BASICS_COLLECTION, { group: "c" });
+                });
+                expectUnorderedItems(await db.getQuery(BASICS_COLLECTION, { str: "TX" }), ["basic1", "basic2", "basic3"]);
+                expect(await db.countQuery(BASICS_COLLECTION, {})).toBe(6);
+            });
+            test("transact(): sequences and nested transactions are unsupported inside a transaction", async () => {
+                const db = await init();
+                expect(await db.transact(async () => 123)).toBe(123);
+                await db.transact(async (tx) => {
+                    expect(() => tx.getItemSequence(BASICS_COLLECTION, "basic1")).toThrow(UnsupportedError);
+                    expect(() => tx.getQuerySequence(BASICS_COLLECTION, {})).toThrow(UnsupportedError);
+                    expect(() => tx.transact(async () => undefined)).toThrow(UnsupportedError);
+                });
+            });
+        }
+        else {
+            test("transactions are not supported", async () => {
+                const db = await init();
+                expect(() => db.transact(async () => undefined)).toThrow(UnsupportedError);
+            });
+        }
+    });
+}