shelving 1.273.1 → 1.275.0

package/db/provider/ChangesDBProvider.d.ts

@@ -4,6 +4,7 @@ import type { Identifier, Item } from "../../util/item.js";
 import type { Query } from "../../util/query.js";
 import type { Updates } from "../../util/update.js";
 import type { Collection } from "../collection/Collection.js";
+import type { DBProvider } from "./DBProvider.js";
 import { ThroughDBProvider } from "./ThroughDBProvider.js";
 /**
  * Structured log entry recording a single database write performed through a `ChangesDBProvider`.
@@ -50,4 +51,6 @@ export declare class ChangesDBProvider<I extends Identifier, T extends Data> ext
     updateQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>, updates: Updates<TT>): Promise<void>;
     /** Log a `"delete"` change after writing. */
     deleteQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<void>;
+    cloneWith(source: DBProvider<I, T>): this;
+    transact<X>(callback: (provider: DBProvider<I, T>) => Promise<X>): Promise<X>;
 }

package/db/provider/ChangesDBProvider.js

@@ -53,4 +53,19 @@ export class ChangesDBProvider extends ThroughDBProvider {
         await super.deleteQuery(collection, query);
         this._changes.push({ action: "delete", collection: collection.name, query });
     }
+    // Override so that transaction copies get their own log.
+    cloneWith(source) {
+        const clone = super.cloneWith(source);
+        Object.defineProperty(clone, "_changes", { value: [], enumerable: false });
+        return clone;
+    }
+    // Override to log the transaction's writes after it commits — a failed transaction logs nothing.
+    // The merge must happen after `source.transact()` resolves: backends may retry the callback or fail the commit itself, and only the committed attempt's writes belong in the log.
+    async transact(callback) {
+        let transaction;
+        const result = await this.source.transact(provider => callback((transaction = this.cloneWith(provider))));
+        if (transaction)
+            this._changes.push(...transaction.changes);
+        return result;
+    }
 }

package/db/provider/DBProvider.d.ts

@@ -167,5 +167,22 @@ export declare abstract class DBProvider<I extends Identifier = Identifier, T ex
      * @see https://shelving.cc/db/DBProvider/requireFirst
      */
     requireFirst<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<Item<II, TT>>;
+    /**
+     * Run a callback as a single atomic transaction — every write made through the callback's provider is committed together, or not at all.
+     *
+     * - The callback receives a transaction-scoped `DBProvider`; reads and writes made through it belong to the transaction.
+     * - Reads see a consistent snapshot of the data from before the transaction, and do not see the transaction's own uncommitted writes.
+     * - If the callback throws, nothing is committed and the error is rethrown.
+     * - The callback may run more than once if the backend retries on contention, so it must have no side effects other than through its provider.
+     * - Inside a transaction, realtime sequences and nested `transact()` calls throw `UnsupportedError`.
+     * - Not every provider supports transactions — the base implementation throws `UnsupportedError`.
+     *
+     * @param callback Function that performs the transaction's reads and writes through the provider it receives.
+     * @returns The value returned by the callback.
+     * @throws `UnsupportedError` if this provider does not support transactions.
+     * @example await provider.transact(async db => void (await db.updateItem(users, 123, { logins: { sum: 1 } })));
+     * @see https://shelving.cc/db/DBProvider/transact
+     */
+    transact<X>(callback: (provider: DBProvider<I, T>) => Promise<X>): Promise<X>;
     [Symbol.asyncDispose](): Promise<void>;
 }

package/db/provider/DBProvider.js

@@ -1,4 +1,5 @@
 import { RequiredError } from "../../error/RequiredError.js";
+import { UnsupportedError } from "../../error/UnsupportedError.js";
 import { countArray, getFirst } from "../../util/array.js";
 import { awaitDispose } from "../../util/dispose.js";
 /**
@@ -81,6 +82,29 @@ export class DBProvider {
             });
         return first;
     }
+    /**
+     * Run a callback as a single atomic transaction — every write made through the callback's provider is committed together, or not at all.
+     *
+     * - The callback receives a transaction-scoped `DBProvider`; reads and writes made through it belong to the transaction.
+     * - Reads see a consistent snapshot of the data from before the transaction, and do not see the transaction's own uncommitted writes.
+     * - If the callback throws, nothing is committed and the error is rethrown.
+     * - The callback may run more than once if the backend retries on contention, so it must have no side effects other than through its provider.
+     * - Inside a transaction, realtime sequences and nested `transact()` calls throw `UnsupportedError`.
+     * - Not every provider supports transactions — the base implementation throws `UnsupportedError`.
+     *
+     * @param callback Function that performs the transaction's reads and writes through the provider it receives.
+     * @returns The value returned by the callback.
+     * @throws `UnsupportedError` if this provider does not support transactions.
+     * @example await provider.transact(async db => void (await db.updateItem(users, 123, { logins: { sum: 1 } })));
+     * @see https://shelving.cc/db/DBProvider/transact
+     */
+    transact(callback) {
+        throw new UnsupportedError(`${this.constructor.name} does not support transactions`, {
+            provider: this,
+            received: callback,
+            caller: this.transact,
+        });
+    }
     // Implement `AsyncDisposable`
     async [Symbol.asyncDispose]() {
         await awaitDispose(

package/db/provider/DebugDBProvider.d.ts

@@ -3,6 +3,7 @@ import type { Identifier, Item, Items, ItemsSequence, OptionalItem, OptionalItem
 import type { Query } from "../../util/query.js";
 import type { Updates } from "../../util/update.js";
 import type { Collection } from "../collection/Collection.js";
+import type { DBProvider } from "./DBProvider.js";
 import { ThroughDBProvider } from "./ThroughDBProvider.js";
 /**
  * Database provider that logs every operation it performs to the console for debugging.
@@ -29,4 +30,6 @@ export declare class DebugDBProvider<I extends Identifier, T extends Data> exten
     setQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>, data: TT): Promise<void>;
     updateQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>, updates: Updates<TT>): Promise<void>;
     deleteQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<void>;
+    /** Adds TRANSACT logging around the base behaviour, which re-wraps so operations inside the transaction are logged too. */
+    transact<X>(callback: (provider: DBProvider<I, T>) => Promise<X>): Promise<X>;
 }

package/db/provider/DebugDBProvider.js

@@ -153,4 +153,17 @@ export class DebugDBProvider extends ThroughDBProvider {
             throw reason;
         }
     }
+    /** Adds TRANSACT logging around the base behaviour, which re-wraps so operations inside the transaction are logged too. */
+    async transact(callback) {
+        try {
+            console.debug(`${ANSI_RIGHT} TRANSACT`);
+            const result = await super.transact(callback);
+            console.debug(`${ANSI_SUCCESS} TRANSACT`);
+            return result;
+        }
+        catch (reason) {
+            console.error(`${ANSI_FAILURE} TRANSACT`, reason);
+            throw reason;
+        }
+    }
 }

package/db/provider/ThroughDBProvider.d.ts

@@ -36,5 +36,8 @@ export declare class ThroughDBProvider<I extends Identifier, T extends Data> imp
     deleteQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<void>;
     getFirst<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<OptionalItem<II, TT>>;
     requireFirst<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<Item<II, TT>>;
+    transact<X>(callback: (provider: DBProvider<I, T>) => Promise<X>): Promise<X>;
+    /** Clone this provider with different `source`. */
+    cloneWith(source: DBProvider<I, T>): this;
     [Symbol.asyncDispose](): Promise<void>;
 }

package/db/provider/ThroughDBProvider.js

@@ -62,6 +62,14 @@ export class ThroughDBProvider {
     requireFirst(collection, query) {
         return this.source.requireFirst(collection, query);
     }
+    // Run the transaction against the wrapped `source` provider, keeping this provider's behaviour inside the transaction.
+    transact(callback) {
+        return this.source.transact(transaction => callback(this.cloneWith(transaction)));
+    }
+    /** Clone this provider with different `source`. */
+    cloneWith(source) {
+        return Object.create(this, { source: { value: source, enumerable: true } });
+    }
     // Implement `AsyncDisposable`
     async [Symbol.asyncDispose]() {
         await awaitDispose(this.source);

package/db/provider/ValidationDBProvider.d.ts

@@ -10,6 +10,7 @@ import { ThroughDBProvider } from "./ThroughDBProvider.js";
  * - Wraps a `source` provider (which may have any type, because validation guarantees the type) and runs every value through the relevant `Collection` schema before writing and after reading.
  * - Written data is validated against the collection's data schema; read data is validated against the item schema, so trusted, correctly-typed values reach the rest of the app.
  * - Validation failures here are program-state errors, so they throw a typed `ValueError` rather than a raw validation `string`.
+ * - Applies inside `transact()` too — the transaction provider the callback receives validates its reads and writes the same way.
  *
  * @see https://shelving.cc/db/ValidationDBProvider
  */

package/db/provider/ValidationDBProvider.js

@@ -8,6 +8,7 @@ import { ThroughDBProvider } from "./ThroughDBProvider.js";
  * - Wraps a `source` provider (which may have any type, because validation guarantees the type) and runs every value through the relevant `Collection` schema before writing and after reading.
  * - Written data is validated against the collection's data schema; read data is validated against the item schema, so trusted, correctly-typed values reach the rest of the app.
  * - Validation failures here are program-state errors, so they throw a typed `ValueError` rather than a raw validation `string`.
+ * - Applies inside `transact()` too — the transaction provider the callback receives validates its reads and writes the same way.
  *
  * @see https://shelving.cc/db/ValidationDBProvider
  */

package/package.json

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

package/test/TransactionTestDBProvider.d.ts

@@ -0,0 +1,15 @@
+import type { DBProvider } from "../db/provider/DBProvider.js";
+import { MemoryDBProvider } from "../db/provider/MemoryDBProvider.js";
+import type { Data } from "../util/data.js";
+import type { Identifier } from "../util/item.js";
+/**
+ * In-memory provider for testing wrapping providers' `transact()` — runs the callback directly against itself.
+ *
+ * - No atomicity or rollback: writes apply immediately and are kept even if the callback throws.
+ * - Use it as the `source` of a wrapping provider to test how the wrapper behaves inside transactions, not to test transaction semantics themselves.
+ *
+ * @see https://shelving.cc/test/TransactionTestDBProvider
+ */
+export declare class TransactionTestDBProvider<I extends Identifier = Identifier, T extends Data = Data> extends MemoryDBProvider<I, T> {
+    transact<X>(callback: (provider: DBProvider<I, T>) => Promise<X>): Promise<X>;
+}

package/test/TransactionTestDBProvider.js

@@ -0,0 +1,14 @@
+import { MemoryDBProvider } from "../db/provider/MemoryDBProvider.js";
+/**
+ * In-memory provider for testing wrapping providers' `transact()` — runs the callback directly against itself.
+ *
+ * - No atomicity or rollback: writes apply immediately and are kept even if the callback throws.
+ * - Use it as the `source` of a wrapping provider to test how the wrapper behaves inside transactions, not to test transaction semantics themselves.
+ *
+ * @see https://shelving.cc/test/TransactionTestDBProvider
+ */
+export class TransactionTestDBProvider extends MemoryDBProvider {
+    async transact(callback) {
+        return await callback(this);
+    }
+}

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,25 +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,9 +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);
+            });
+        }
+    });
+}