@adobe/data 0.9.61 → 0.9.62

package/dist/ecs/database/concurrency/roll-forward-concurrency.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"roll-forward-concurrency.test.js","sourceRoot":"","sources":["../../../../src/ecs/database/concurrency/roll-forward-concurrency.test.ts"],"names":[],"mappings":"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"}

package/dist/ecs/database/database.d.ts

@@ -13,7 +13,8 @@ import { RequiredComponents } from "../required-components.js";
 import { EntitySelectOptions } from "../store/entity-select-options.js";
 import { Index as StoreIndex } from "../store/index-types.js";
 import type { Service } from "../../service/index.js";
-import { createDatabase, type DatabaseSyncOptions } from "./public/create-database.js";
+import { createDatabase } from "./public/create-database.js";
+import type { ConcurrencyStrategy } from "./concurrency/concurrency-strategy.js";
 import { ResourceSchemas } from "../resource-schemas.js";
 import { ComponentSchemas } from "../component-schemas.js";
 import { FromSchemas } from "../../schema/index.js";
@@ -160,13 +161,12 @@ export interface Database<C extends Components = {}, R extends ResourceComponent
      */
     readonly cancel: (id: number, userId?: number | string) => void;
     /**
-     * The sync options the database was created with, or `undefined` for a
-     * local-only database. Sync services read this to (a) confirm the
-     * database was created in sync mode and (b) recover the `userId` for
-     * authentication / logging without having to thread it through
-     * separately.
+     * The concurrency strategy the database was created with. Sync services
+     * read `concurrency.userId` to recover the peer identifier and check
+     * `concurrency.deferredCommit` to confirm the database is in the
+     * appropriate mode for multi-peer operation.
      */
-    readonly sync: DatabaseSyncOptions | undefined;
+    readonly concurrency: ConcurrencyStrategy;
     readonly system: {
         /** System create() return value, or null when create() returns void. Key is always present. */
         readonly functions: {
@@ -175,6 +175,28 @@ export interface Database<C extends Components = {}, R extends ResourceComponent
         /** Tier order for execution. Looser type allows extended dbs to be assignable to base. */
         readonly order: ReadonlyArray<ReadonlyArray<string>>;
     };
+    /**
+     * Serialize the database to a plain data snapshot.
+     *
+     * For a concurrency strategy that replays transients after serialization
+     * (`onAfterToData` — i.e. `createRebaseReplayConcurrency` /
+     * `createRollForwardConcurrency` / the legacy `createReconcilingDatabase`),
+     * this returns a snapshot **detached** from the live store: it rolls the
+     * transients back, serializes a copy of the committed state (`store.toData`
+     * with `copy: true` — columns and the entity table are cloned), then replays.
+     * So a database persisted with optimistic edits in flight contains only
+     * committed state, and the snapshot survives the subsequent replay.
+     *
+     * For strategies with no replay hook (the default `createImmediateConcurrency`),
+     * the faster live-reference snapshot is returned — it shares the store's
+     * buffers and is only valid until the next mutation, so callers must serialize
+     * it before mutating the database again.
+     *
+     * Historical note: the detach above fixes a bug where the live-reference
+     * snapshot was corrupted by the post-serialization replay, silently leaking
+     * in-flight transients into persisted state. The old reconciler tests missed
+     * it because they only asserted the snapshot was truthy, never round-tripped it.
+     */
     toData(): unknown;
     fromData(data: unknown): void;
     extend<P extends Database.Plugin>(plugin: P): Database<C & FromSchemas<RemoveIndex<P['components']>>, R & FromSchemas<RemoveIndex<P['resources']>>, A & RemoveIndex<P['archetypes']>, F & ToTransactionFunctions<RemoveIndex<P['transactions']>>, S | StringKeyof<P['systems']>, AF & ToActionFunctions<RemoveIndex<P['actions']>>, SV & FromServiceFactories<RemoveIndex<P['services']>>, CV & FromComputedFactories<RemoveIndex<P['computed']>>, IX & RemoveIndex<P['indexes']>>;

package/dist/ecs/database/database.index.test.js

@@ -174,6 +174,257 @@ describe("Pattern 4 — sorted children (orderedChildrenOf)", () => {
         expect(ext.indexes.orderedChildrenOf.find(5)).toEqual([a, b, c]);
     });
 });
+describe("Pattern 4 — observe(arg): reactive sorted bucket view", () => {
+    const plugin = () => Database.Plugin.create({
+        components: {
+            parent: { type: "number" },
+            fractIndex: { type: "string" },
+        },
+        archetypes: { Child: ["parent", "fractIndex"] },
+        indexes: {
+            orderedChildrenOf: {
+                key: "parent",
+                order: { by: ["fractIndex"] },
+            },
+        },
+        transactions: {
+            add: (t, args) => t.archetypes.Child.insert(args),
+            move: (t, args) => t.update(args.entity, { fractIndex: args.fractIndex }),
+            reparent: (t, args) => t.update(args.entity, { parent: args.parent }),
+            delete: (t, e) => t.delete(e),
+        },
+    });
+    it("emits the initial sorted list synchronously on subscribe", () => {
+        const db = Database.create(plugin());
+        const c = db.transactions.add({ parent: 7, fractIndex: "c" });
+        const a = db.transactions.add({ parent: 7, fractIndex: "a" });
+        const b = db.transactions.add({ parent: 7, fractIndex: "b" });
+        const emissions = [];
+        const unsub = db.indexes.orderedChildrenOf.observe(7)((entities) => { emissions.push([...entities]); });
+        expect(emissions).toEqual([[a, b, c]]);
+        unsub();
+    });
+    it("emits the re-sorted list when an entity is inserted into the bucket", async () => {
+        const db = Database.create(plugin());
+        const a = db.transactions.add({ parent: 7, fractIndex: "a" });
+        const c = db.transactions.add({ parent: 7, fractIndex: "c" });
+        const emissions = [];
+        const unsub = db.indexes.orderedChildrenOf.observe(7)((entities) => { emissions.push([...entities]); });
+        const b = db.transactions.add({ parent: 7, fractIndex: "b" });
+        await Promise.resolve();
+        expect(emissions[0]).toEqual([a, c]);
+        expect(emissions[emissions.length - 1]).toEqual([a, b, c]);
+        unsub();
+    });
+    it("emits a reorder when only the sort key changes (regression case)", async () => {
+        const db = Database.create(plugin());
+        const a = db.transactions.add({ parent: 7, fractIndex: "a" });
+        const b = db.transactions.add({ parent: 7, fractIndex: "b" });
+        const c = db.transactions.add({ parent: 7, fractIndex: "c" });
+        const emissions = [];
+        const unsub = db.indexes.orderedChildrenOf.observe(7)((entities) => { emissions.push([...entities]); });
+        expect(emissions[0]).toEqual([a, b, c]);
+        // Reorder-only transaction: parent (the bucket key) is untouched, so a
+        // `where`-only observe.select would never see this. The index does.
+        db.transactions.move({ entity: b, fractIndex: "z" });
+        await Promise.resolve();
+        expect(emissions[emissions.length - 1]).toEqual([a, c, b]);
+        unsub();
+    });
+    it("emits the shrunken list when an entity is deleted from the bucket", async () => {
+        const db = Database.create(plugin());
+        const a = db.transactions.add({ parent: 7, fractIndex: "a" });
+        const b = db.transactions.add({ parent: 7, fractIndex: "b" });
+        const emissions = [];
+        const unsub = db.indexes.orderedChildrenOf.observe(7)((entities) => { emissions.push([...entities]); });
+        db.transactions.delete(b);
+        await Promise.resolve();
+        expect(emissions[emissions.length - 1]).toEqual([a]);
+        unsub();
+    });
+    it("does NOT emit when an unrelated bucket's entity changes", async () => {
+        const db = Database.create(plugin());
+        db.transactions.add({ parent: 7, fractIndex: "a" });
+        const other = db.transactions.add({ parent: 9, fractIndex: "a" });
+        const emissions = [];
+        const unsub = db.indexes.orderedChildrenOf.observe(7)((entities) => { emissions.push([...entities]); });
+        expect(emissions).toHaveLength(1);
+        // A child of a *different* parent moves. Same component (`fractIndex`)
+        // changes, so the observer is woken and recomputes — but its own
+        // bucket is unchanged, so no second emission.
+        db.transactions.move({ entity: other, fractIndex: "z" });
+        await Promise.resolve();
+        expect(emissions).toHaveLength(1);
+        unsub();
+    });
+    it("emits on both buckets when an entity reparents between them", async () => {
+        const db = Database.create(plugin());
+        const a = db.transactions.add({ parent: 7, fractIndex: "a" });
+        const m = db.transactions.add({ parent: 7, fractIndex: "b" });
+        const fromSeven = [];
+        const toNine = [];
+        const unsub7 = db.indexes.orderedChildrenOf.observe(7)((e) => fromSeven.push([...e]));
+        const unsub9 = db.indexes.orderedChildrenOf.observe(9)((e) => toNine.push([...e]));
+        db.transactions.reparent({ entity: m, parent: 9 });
+        await Promise.resolve();
+        expect(fromSeven[fromSeven.length - 1]).toEqual([a]);
+        expect(toNine[toNine.length - 1]).toEqual([m]);
+        unsub7();
+        unsub9();
+    });
+    it("unsubscribe stops further emissions", async () => {
+        const db = Database.create(plugin());
+        db.transactions.add({ parent: 7, fractIndex: "a" });
+        const emissions = [];
+        const unsub = db.indexes.orderedChildrenOf.observe(7)((entities) => { emissions.push([...entities]); });
+        expect(emissions).toHaveLength(1);
+        unsub();
+        db.transactions.add({ parent: 7, fractIndex: "b" });
+        await Promise.resolve();
+        expect(emissions).toHaveLength(1);
+    });
+});
+describe("observe(arg) — additional edge cases", () => {
+    const sortedPlugin = () => Database.Plugin.create({
+        components: {
+            parent: { type: "number" },
+            fractIndex: { type: "string" },
+        },
+        archetypes: { Child: ["parent", "fractIndex"] },
+        indexes: {
+            orderedChildrenOf: { key: "parent", order: { by: ["fractIndex"] } },
+            childrenOf: { key: "parent" },
+        },
+        transactions: {
+            add: (t, args) => t.archetypes.Child.insert(args),
+            move: (t, args) => t.update(args.entity, { fractIndex: args.fractIndex }),
+            delete: (t, e) => t.delete(e),
+        },
+    });
+    it("emits [] for an initially-empty bucket, then the entity once populated", async () => {
+        const db = Database.create(sortedPlugin());
+        const emissions = [];
+        const unsub = db.indexes.orderedChildrenOf.observe(42)((e) => emissions.push([...e]));
+        expect(emissions).toEqual([[]]);
+        const e = db.transactions.add({ parent: 42, fractIndex: "a" });
+        await Promise.resolve();
+        expect(emissions[emissions.length - 1]).toEqual([e]);
+        unsub();
+    });
+    it("emits [] when the last entity leaves the bucket", async () => {
+        const db = Database.create(sortedPlugin());
+        const only = db.transactions.add({ parent: 7, fractIndex: "a" });
+        const emissions = [];
+        const unsub = db.indexes.orderedChildrenOf.observe(7)((e) => emissions.push([...e]));
+        db.transactions.delete(only);
+        await Promise.resolve();
+        expect(emissions[emissions.length - 1]).toEqual([]);
+        unsub();
+    });
+    it("notifies every subscriber of the same bucket", async () => {
+        const db = Database.create(sortedPlugin());
+        const a = db.transactions.add({ parent: 7, fractIndex: "a" });
+        const first = [];
+        const second = [];
+        const unsub1 = db.indexes.orderedChildrenOf.observe(7)((e) => first.push([...e]));
+        const unsub2 = db.indexes.orderedChildrenOf.observe(7)((e) => second.push([...e]));
+        const b = db.transactions.add({ parent: 7, fractIndex: "b" });
+        await Promise.resolve();
+        expect(first[first.length - 1]).toEqual([a, b]);
+        expect(second[second.length - 1]).toEqual([a, b]);
+        unsub1();
+        unsub2();
+    });
+    it("coalesces several transactions before the microtask into one emission", async () => {
+        const db = Database.create(sortedPlugin());
+        const a = db.transactions.add({ parent: 7, fractIndex: "a" });
+        const emissions = [];
+        const unsub = db.indexes.orderedChildrenOf.observe(7)((e) => emissions.push([...e]));
+        // Three synchronous transactions, no awaits in between.
+        const c = db.transactions.add({ parent: 7, fractIndex: "c" });
+        const b = db.transactions.add({ parent: 7, fractIndex: "b" });
+        db.transactions.move({ entity: c, fractIndex: "d" });
+        await Promise.resolve();
+        // Initial emit + exactly one coalesced emit reflecting the final state.
+        expect(emissions).toHaveLength(2);
+        expect(emissions[1]).toEqual([a, b, c]);
+        unsub();
+    });
+    it("does not re-emit when a touched bucket ends a transaction unchanged", async () => {
+        const db = Database.create(sortedPlugin());
+        const a = db.transactions.add({ parent: 7, fractIndex: "a" });
+        const emissions = [];
+        const unsub = db.indexes.orderedChildrenOf.observe(7)((e) => emissions.push([...e]));
+        // Move the only child to a new sort key and back within the same
+        // microtask window: the bucket is woken but its final sequence is
+        // identical, so no second emission.
+        db.transactions.move({ entity: a, fractIndex: "z" });
+        db.transactions.move({ entity: a, fractIndex: "a" });
+        await Promise.resolve();
+        expect(emissions).toHaveLength(1);
+        unsub();
+    });
+    it("works on a non-sorted index — membership changes still emit", async () => {
+        const db = Database.create(sortedPlugin());
+        const a = db.transactions.add({ parent: 7, fractIndex: "a" });
+        const emissions = [];
+        const unsub = db.indexes.childrenOf.observe(7)((e) => emissions.push([...e].sort()));
+        expect(emissions[0]).toEqual([a]);
+        const b = db.transactions.add({ parent: 7, fractIndex: "b" });
+        await Promise.resolve();
+        expect(emissions[emissions.length - 1]).toEqual([a, b].sort());
+        unsub();
+    });
+    const priorityPlugin = () => Database.Plugin.create({
+        components: {
+            owner: { type: "number" },
+            priority: { type: "number" },
+            due: { type: "number" },
+        },
+        archetypes: { Task: ["owner", "priority", "due"] },
+        indexes: {
+            tasksByPriority: {
+                key: "owner",
+                order: {
+                    by: ["priority", "due"],
+                    compare: (a, b) => b.priority - a.priority || a.due - b.due,
+                },
+            },
+        },
+        transactions: {
+            add: (t, args) => t.archetypes.Task.insert(args),
+            setPriority: (t, args) => t.update(args.entity, { priority: args.priority }),
+            setDue: (t, args) => t.update(args.entity, { due: args.due }),
+        },
+    });
+    it("re-sorts under a custom comparator when the primary sort key changes", async () => {
+        const db = Database.create(priorityPlugin());
+        const low = db.transactions.add({ owner: 1, priority: 1, due: 100 });
+        const high = db.transactions.add({ owner: 1, priority: 3, due: 50 });
+        const emissions = [];
+        const unsub = db.indexes.tasksByPriority.observe(1)((e) => emissions.push([...e]));
+        // priority desc → [high, low].
+        expect(emissions[0]).toEqual([high, low]);
+        db.transactions.setPriority({ entity: low, priority: 5 });
+        await Promise.resolve();
+        expect(emissions[emissions.length - 1]).toEqual([low, high]);
+        unsub();
+    });
+    it("re-sorts when only the secondary (tie-break) sort component changes", async () => {
+        const db = Database.create(priorityPlugin());
+        // Equal priority → ordered by `due` asc.
+        const early = db.transactions.add({ owner: 1, priority: 2, due: 10 });
+        const late = db.transactions.add({ owner: 1, priority: 2, due: 20 });
+        const emissions = [];
+        const unsub = db.indexes.tasksByPriority.observe(1)((e) => emissions.push([...e]));
+        expect(emissions[0]).toEqual([early, late]);
+        // Push `early`'s due past `late`'s — flips the tie-break order.
+        db.transactions.setDue({ entity: early, due: 30 });
+        await Promise.resolve();
+        expect(emissions[emissions.length - 1]).toEqual([late, early]);
+        unsub();
+    });
+});
 describe("Pattern 5 — multi-value (array column → fan-out): tasksByAssignee", () => {
     const plugin = () => Database.Plugin.create({
         components: {
@@ -569,6 +820,135 @@ describe("auto-routing of db.observe.select", () => {
         }
     });
 });
+describe("auto-routing of ordered select through a sorted index", () => {
+    // Two indexes on the same key, distinct shapes: one unsorted, one sorted
+    // ascending by `priority` (default comparator). An ordered query must route
+    // to the *sorted* one (never the unsorted one), and a query whose order the
+    // index can't serve must fall back to the scan.
+    const plugin = () => Database.Plugin.create({
+        components: {
+            owner: { type: "number" },
+            priority: { type: "number" },
+            due: { type: "number" },
+            title: { type: "string" },
+        },
+        archetypes: { Task: ["owner", "priority", "due", "title"] },
+        indexes: {
+            byOwner: { key: "owner" },
+            byOwnerSorted: { key: "owner", order: { by: ["priority"] } },
+        },
+        transactions: {
+            add: (t, a) => t.archetypes.Task.insert(a),
+        },
+    });
+    const spyFind = (handle) => {
+        const original = handle.find;
+        const state = { calls: 0 };
+        handle.find = (v) => { state.calls += 1; return original(v); };
+        return { state, restore: () => { handle.find = original; } };
+    };
+    const seed = (db) => {
+        const mid = db.transactions.add({ owner: 1, priority: 2, due: 10, title: "mid" });
+        const low = db.transactions.add({ owner: 1, priority: 1, due: 20, title: "low" });
+        const high = db.transactions.add({ owner: 1, priority: 3, due: 30, title: "high" });
+        db.transactions.add({ owner: 2, priority: 1, due: 40, title: "other" });
+        return { low, mid, high };
+    };
+    it("routes an ascending ordered query to the sorted index (and returns it sorted)", () => {
+        const db = Database.create(plugin());
+        const { low, mid, high } = seed(db);
+        const sorted = spyFind(db.indexes.byOwnerSorted);
+        try {
+            const result = db.select(["owner", "priority"], { where: { owner: 1 }, order: { priority: true } });
+            // GREEN: the ordered query was served by the sorted index...
+            expect(sorted.state.calls).toBe(1);
+            // ...and the result is in the index's ascending priority order.
+            expect([...result]).toEqual([low, mid, high]);
+        }
+        finally {
+            sorted.restore();
+        }
+    });
+    it("routes the ordered query to the sorted index, never the unsorted one on the same key", () => {
+        const db = Database.create(plugin());
+        seed(db);
+        const unsorted = spyFind(db.indexes.byOwner);
+        const sorted = spyFind(db.indexes.byOwnerSorted);
+        try {
+            db.select(["owner", "priority"], { where: { owner: 1 }, order: { priority: true } });
+            expect(sorted.state.calls).toBe(1);
+            expect(unsorted.state.calls).toBe(0);
+        }
+        finally {
+            unsorted.restore();
+            sorted.restore();
+        }
+    });
+    it("falls back to scan for a descending order (sorted index only materializes ascending)", () => {
+        const db = Database.create(plugin());
+        const { low, mid, high } = seed(db);
+        const sorted = spyFind(db.indexes.byOwnerSorted);
+        try {
+            const result = db.select(["owner", "priority"], { where: { owner: 1 }, order: { priority: false } });
+            // Not routed — the index can't serve descending without re-sorting.
+            expect(sorted.state.calls).toBe(0);
+            // The scan still produces a correct descending result.
+            expect([...result]).toEqual([high, mid, low]);
+        }
+        finally {
+            sorted.restore();
+        }
+    });
+    it("falls back to scan when the requested order column is not the index's sort column", () => {
+        const db = Database.create(plugin());
+        seed(db);
+        const sorted = spyFind(db.indexes.byOwnerSorted);
+        try {
+            // Index sorts by `priority`; this asks for `due`.
+            const result = db.select(["owner", "due"], { where: { owner: 1 }, order: { due: true } });
+            expect(sorted.state.calls).toBe(0);
+            expect(result).toHaveLength(3);
+        }
+        finally {
+            sorted.restore();
+        }
+    });
+    it("still routes a plain (no-order) equality query — unaffected by the order support", () => {
+        const db = Database.create(plugin());
+        seed(db);
+        // No order: the first matching key index (byOwner) serves it.
+        const unsorted = spyFind(db.indexes.byOwner);
+        try {
+            const result = db.select(["owner"], { where: { owner: 1 } });
+            expect(unsorted.state.calls).toBe(1);
+            expect(result).toHaveLength(3);
+        }
+        finally {
+            unsorted.restore();
+        }
+    });
+    it("routes the ordered query through db.observe.select too (initial snapshot + requery)", async () => {
+        const db = Database.create(plugin());
+        const { low, mid, high } = seed(db);
+        const sorted = spyFind(db.indexes.byOwnerSorted);
+        try {
+            const emissions = [];
+            const unsub = db.observe.select(["owner", "priority"], { where: { owner: 1 }, order: { priority: true } })((entities) => { emissions.push([...entities]); });
+            // Initial snapshot routed and sorted.
+            expect(sorted.state.calls).toBe(1);
+            expect(emissions[0]).toEqual([low, mid, high]);
+            // A new task for owner 1 with the lowest priority sorts to the front.
+            const lowest = db.transactions.add({ owner: 1, priority: 0, due: 5, title: "lowest" });
+            await Promise.resolve();
+            expect(sorted.state.calls).toBe(2);
+            expect(emissions[emissions.length - 1]).toEqual([lowest, low, mid, high]);
+            unsub();
+        }
+        finally {
+            sorted.restore();
+        }
+    });
+});
 describe("t.indexes — eager maintenance inside transactions", () => {
     const plugin = () => Database.Plugin.create({
         components: {