@braidlabs/data 0.1.1

package/src/lib/locks.js

@@ -0,0 +1,78 @@
+/**
+ * Cross-context mutual exclusion, for work that must happen once across every tab and realm.
+ *
+ * The motivating case is flushing the outbox. Storage is shared per origin, so without this every
+ * open tab drains the same queue on reconnect — replaying the same mutations several times, against
+ * a server that is by definition just coming back. No storage layer helps: IndexedDB makes each
+ * *write* atomic, and says nothing about who should be doing the writing.
+ *
+ * `navigator.locks` is the only primitive that spans realms and tabs. Where it is missing — Node,
+ * a non-secure context, an older browser — this degrades to an in-process lock, which is honest
+ * about what it can offer: exclusion within one JavaScript context, which is what existed before
+ * this and is still better than nothing.
+ */
+/** True when this context has real cross-tab locks rather than the in-process fallback. */
+export function hasCrossContextLocks() {
+    return typeof navigator !== 'undefined' && navigator.locks !== undefined;
+}
+export async function withLock(name, run, options = {}) {
+    const ifAvailable = options.ifAvailable ?? true;
+    if (!hasCrossContextLocks()) {
+        return withInProcessLock(name, run, ifAvailable);
+    }
+    const request = { mode: 'exclusive', ifAvailable };
+    if (options.signal) {
+        // The spec forbids combining them: a request that is already declining to wait has nothing for
+        // an abort signal to interrupt.
+        delete request.ifAvailable;
+        request.signal = options.signal;
+    }
+    return navigator.locks.request(name, request, async (lock) => {
+        // `ifAvailable` hands back a null lock rather than rejecting when someone else holds it.
+        if (!lock)
+            return { acquired: false };
+        return { acquired: true, value: await run() };
+    });
+}
+/**
+ * Module-level so every holder in this JavaScript context shares it — two services in one Angular
+ * app must exclude each other even when the platform gives us nothing.
+ *
+ * Per realm, though: realms are separate contexts, so this map is not shared between them. That is
+ * precisely the gap `navigator.locks` closes, and the reason the fallback is a fallback.
+ */
+const inProcessLocks = new Map();
+async function withInProcessLock(name, run, ifAvailable) {
+    const held = inProcessLocks.get(name);
+    if (held && ifAvailable)
+        return { acquired: false };
+    const release = (async () => {
+        if (held)
+            await held.catch(() => undefined);
+        return run();
+    })();
+    // Stored before awaiting, so a synchronous second caller sees the lock as held.
+    inProcessLocks.set(name, release.catch(() => undefined));
+    try {
+        return { acquired: true, value: await release };
+    }
+    finally {
+        // Only clear it if nobody queued behind us, or we would release someone else's turn.
+        if (inProcessLocks.get(name) === undefined)
+            inProcessLocks.delete(name);
+        else if (!held)
+            inProcessLocks.delete(name);
+    }
+}
+/**
+ * The lock name for flushing one owner's queue.
+ *
+ * Per **owner**, not one global lock. Two different applications flush disjoint entries, so making
+ * them queue behind each other would serialize work that has no reason to be serialized. The
+ * conflict this prevents is the same application open in two tabs, both replaying the same
+ * mutations.
+ */
+export function outboxFlushLock(owner) {
+    return `skew:outbox:flush:${owner}`;
+}
+//# sourceMappingURL=locks.js.map

package/src/lib/locks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"locks.js","sourceRoot":"","sources":["../../../../../libs/data/src/lib/locks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAiBH,2FAA2F;AAC3F,MAAM,UAAU,oBAAoB;IAClC,OAAO,OAAO,SAAS,KAAK,WAAW,IAAI,SAAS,CAAC,KAAK,KAAK,SAAS,CAAC;AAC3E,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,IAAY,EACZ,GAAqB,EACrB,UAAuB,EAAE;IAEzB,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,IAAI,CAAC;IAEhD,IAAI,CAAC,oBAAoB,EAAE,EAAE,CAAC;QAC5B,OAAO,iBAAiB,CAAC,IAAI,EAAE,GAAG,EAAE,WAAW,CAAC,CAAC;IACnD,CAAC;IAED,MAAM,OAAO,GAAqC,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC;IACrF,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACnB,+FAA+F;QAC/F,gCAAgC;QAChC,OAAQ,OAAqC,CAAC,WAAW,CAAC;QACzD,OAAoC,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAChE,CAAC;IAED,OAAO,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,OAAsB,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;QAC1E,yFAAyF;QACzF,IAAI,CAAC,IAAI;YAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAmB,CAAC;QACvD,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,EAAE,EAAmB,CAAC;IACjE,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACH,MAAM,cAAc,GAAG,IAAI,GAAG,EAA4B,CAAC;AAE3D,KAAK,UAAU,iBAAiB,CAC9B,IAAY,EACZ,GAAqB,EACrB,WAAoB;IAEpB,MAAM,IAAI,GAAG,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAEtC,IAAI,IAAI,IAAI,WAAW;QAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;IAEpD,MAAM,OAAO,GAAG,CAAC,KAAK,IAAI,EAAE;QAC1B,IAAI,IAAI;YAAE,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAC5C,OAAO,GAAG,EAAE,CAAC;IACf,CAAC,CAAC,EAAE,CAAC;IAEL,gFAAgF;IAChF,cAAc,CAAC,GAAG,CAChB,IAAI,EACJ,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAC/B,CAAC;IAEF,IAAI,CAAC;QACH,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,OAAO,EAAE,CAAC;IAClD,CAAC;YAAS,CAAC;QACT,qFAAqF;QACrF,IAAI,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,SAAS;YAAE,cAAc,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;aACnE,IAAI,CAAC,IAAI;YAAE,cAAc,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC9C,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,OAAO,qBAAqB,KAAK,EAAE,CAAC;AACtC,CAAC"}

package/src/lib/memory-driver.d.ts

@@ -0,0 +1,10 @@
+import type { RecordDriver } from './record-store.js';
+/**
+ * An in-memory driver.
+ *
+ * The reference implementation and the one tests run against — every behavior the IndexedDB driver
+ * must exhibit is pinned here first, where it is observable without a browser.
+ *
+ * Not durable, so never the primary store for anything the user would mind losing.
+ */
+export declare function memoryRecordDriver(): RecordDriver;

package/src/lib/memory-driver.js

@@ -0,0 +1,53 @@
+/**
+ * An in-memory driver.
+ *
+ * The reference implementation and the one tests run against — every behavior the IndexedDB driver
+ * must exhibit is pinned here first, where it is observable without a browser.
+ *
+ * Not durable, so never the primary store for anything the user would mind losing.
+ */
+export function memoryRecordDriver() {
+    const collections = new Map();
+    const of = (collection) => {
+        let records = collections.get(collection);
+        if (!records) {
+            records = new Map();
+            collections.set(collection, records);
+        }
+        return records;
+    };
+    return {
+        async put(collection, record) {
+            // Structured-cloned on the way in so a caller mutating the object it passed cannot reach
+            // back into the store — the same rule the real driver gets for free from IndexedDB.
+            of(collection).set(record.id, structuredClone(record));
+        },
+        async get(collection, id) {
+            const record = of(collection).get(id);
+            return record ? structuredClone(record) : null;
+        },
+        async delete(collection, id) {
+            of(collection).delete(id);
+        },
+        async list(collection, partition) {
+            return [...of(collection).values()]
+                .filter((record) => record.partition === partition)
+                .sort((a, b) => a.seq - b.seq)
+                .map((record) => structuredClone(record));
+        },
+        async clearPartition(collection, partition) {
+            const records = of(collection);
+            for (const [id, record] of records) {
+                if (record.partition === partition)
+                    records.delete(id);
+            }
+        },
+        async highestSeq(collection) {
+            let highest = 0;
+            for (const record of of(collection).values())
+                highest = Math.max(highest, record.seq);
+            return highest;
+        },
+    };
+}
+//# sourceMappingURL=memory-driver.js.map

package/src/lib/memory-driver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-driver.js","sourceRoot":"","sources":["../../../../../libs/data/src/lib/memory-driver.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB;IAChC,MAAM,WAAW,GAAG,IAAI,GAAG,EAAqC,CAAC;IAEjE,MAAM,EAAE,GAAG,CAAC,UAAkB,EAA6B,EAAE;QAC3D,IAAI,OAAO,GAAG,WAAW,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QAC1C,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,GAAG,IAAI,GAAG,EAAE,CAAC;YACpB,WAAW,CAAC,GAAG,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;QACvC,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC,CAAC;IAEF,OAAO;QACL,KAAK,CAAC,GAAG,CAAC,UAAU,EAAE,MAAM;YAC1B,yFAAyF;YACzF,oFAAoF;YACpF,EAAE,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,EAAE,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC;QACzD,CAAC;QAED,KAAK,CAAC,GAAG,CAAC,UAAU,EAAE,EAAE;YACtB,MAAM,MAAM,GAAG,EAAE,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACtC,OAAO,MAAM,CAAC,CAAC,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QACjD,CAAC;QAED,KAAK,CAAC,MAAM,CAAC,UAAU,EAAE,EAAE;YACzB,EAAE,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAC5B,CAAC;QAED,KAAK,CAAC,IAAI,CAAC,UAAU,EAAE,SAAS;YAC9B,OAAO,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,CAAC,MAAM,EAAE,CAAC;iBAChC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,SAAS,KAAK,SAAS,CAAC;iBAClD,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC;iBAC7B,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC;QAC9C,CAAC;QAED,KAAK,CAAC,cAAc,CAAC,UAAU,EAAE,SAAS;YACxC,MAAM,OAAO,GAAG,EAAE,CAAC,UAAU,CAAC,CAAC;YAC/B,KAAK,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;gBACnC,IAAI,MAAM,CAAC,SAAS,KAAK,SAAS;oBAAE,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YACzD,CAAC;QACH,CAAC;QAED,KAAK,CAAC,UAAU,CAAC,UAAU;YACzB,IAAI,OAAO,GAAG,CAAC,CAAC;YAChB,KAAK,MAAM,MAAM,IAAI,EAAE,CAAC,UAAU,CAAC,CAAC,MAAM,EAAE;gBAAE,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;YACtF,OAAO,OAAO,CAAC;QACjB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/src/lib/outbox.d.ts

@@ -0,0 +1,146 @@
+import type { RecordDriver } from './record-store.js';
+/**
+ * The offline mutation outbox: durable, shared across every app on the origin, and **owned**.
+ *
+ * Ownership is the correctness fix, not a refinement. Previously the queue was a single blob under
+ * one key, so two applications on one origin overwrote each other's; the second would rehydrate the
+ * first's entries, find no registered runner for them, and **drop the user's unsent work** through a
+ * reporting hook that was optional. An entry that names its owner is instead simply left alone by
+ * everyone else, and waits.
+ *
+ * One record per entry, so enqueue is a `put` and dequeue is a `delete`. Nothing reads before
+ * writing, so nothing can be lost to a concurrent writer.
+ */
+/**
+ * What a queued entry predicts about a record while it waits.
+ *
+ * Data, not a closure, for the same reason `input` is: the overlay has to be reconstructible by a
+ * build that never ran the code which queued it. A shallow patch over the confirmed value is the
+ * most an entry can promise honestly — anything richer would be a function, and a function cannot
+ * survive a reload.
+ */
+export interface OptimisticOverlay {
+    /** The query key this entry changes. */
+    key: string;
+    /** Applied over the confirmed record while the entry is queued. */
+    patch: Record<string, unknown>;
+    /**
+     * The tenant partition this prediction belongs to.
+     *
+     * The queue is deliberately *session*-scoped — a queued write belongs to the session that made it,
+     * not to whichever client was on screen — but the **overlay is not**. Without this, an advisor with
+     * an unsent trade for one client sees it applied to the identically-keyed record of the next client
+     * they open, in another tab, because the two share a record key and a queue.
+     *
+     * Absent on entries written before this existed, which keeps their overlay behaving as it did.
+     */
+    partition?: string;
+    /**
+     * True when the write deletes the record rather than changing it.
+     *
+     * A patch cannot express absence, and a deletion a reader cannot see is a row that stays on
+     * screen after the user removed it — so the overlay carries the fact rather than leaving each
+     * reader to infer it from an empty patch.
+     */
+    removed?: boolean;
+}
+export interface OutboxEntry {
+    /** Identifies the mutation *kind*, so the owner can find its runner. */
+    mutationId: string;
+    /** Replayable input. Never a closure — the build that replays may not be the one that queued. */
+    input: unknown;
+    attempts: number;
+    queuedAt: string;
+    lastError?: string;
+    /**
+     * Contract version of `input`, when the caller declares one.
+     *
+     * Distinct from the envelope's version, which covers this entry's own shape: an entry queued
+     * under one deploy and replayed against a later one may need its *payload* migrated before it
+     * can be sent, and only the caller knows which contract that payload belongs to.
+     */
+    schemaVersion?: number;
+    /**
+     * What readers should show until this entry is confirmed.
+     *
+     * A list because one write routinely changes more than one record — accept an order and the
+     * position moves too — and an entry that could only predict one of them would leave the rest of
+     * the screen showing values the user has already changed.
+     */
+    optimistic?: OptimisticOverlay[];
+}
+interface OutboxEntryV1 {
+    mutationId: string;
+    input: unknown;
+    attempts: number;
+    queuedAt: string;
+    lastError?: string;
+    schemaVersion?: number;
+}
+interface OutboxEntryV2 extends OutboxEntryV1 {
+    optimistic?: OptimisticOverlay[];
+}
+/**
+ * The entry contract, versioned from the first commit.
+ *
+ * A queued mutation can outlive the build that queued it — the user goes offline, the app deploys,
+ * they come back. So even this small internal shape gets an envelope: a shared store is a shared
+ * contract, and treating it as "just some JSON" because it is internal is how a coordination layer
+ * becomes a fate-sharing vector.
+ *
+ * v2 adds the overlay. An entry queued by v1 migrates up without one and simply does not tint any
+ * reader's view — which is the honest answer, since that build never recorded what it predicted.
+ * The queue itself is unaffected either way, so an old entry still sends.
+ */
+export declare const OutboxEntrySchema: import("@braidlabs/skew").VersionedSchema<OutboxEntryV2>;
+export interface QueuedEntry extends OutboxEntry {
+    id: string;
+    owner: string;
+    seq: number;
+}
+export interface OutboxOptions {
+    driver: RecordDriver;
+    /** Which fragment or app this instance speaks for. Only its own entries are replayable by it. */
+    owner: string;
+    /** Tenant partition. The outbox is page-scoped, so this is usually a constant. */
+    partition?: string;
+    buildId?: string;
+    collection?: string;
+}
+export interface Outbox {
+    /** Queues a mutation, returning its id. */
+    enqueue(entry: {
+        mutationId: string;
+        input: unknown;
+        id?: string;
+        schemaVersion?: number;
+        optimistic?: OptimisticOverlay[];
+    }): Promise<string>;
+    /**
+     * Every queued overlay for a key, oldest first, **whoever owns it**.
+     *
+     * Ownership governs who may *send* an entry; it does not govern who may see its effect. A user
+     * who typed a name into one app and looks at another expects to see the name they typed, and an
+     * overlay filtered by owner would show them the stale value with no indication why.
+     *
+     * Tenancy is the one thing that *does* filter. Pass the partition being read and an overlay
+     * belonging to a different one is left out — same key, different client, different answer.
+     */
+    pendingFor(key: string, partition?: string): Promise<OptimisticOverlay[]>;
+    /** Entries this instance owns and may replay, oldest first. */
+    mine(): Promise<QueuedEntry[]>;
+    /**
+     * Every entry in the queue, whoever owns it.
+     *
+     * What "3 unsent changes" is counted from — a page-wide fact needs a page-wide read, and each app
+     * answering only for itself is how the indicator became wrong in the first place.
+     */
+    all(): Promise<QueuedEntry[]>;
+    /** Entries owned by someone else. They are waiting, not stuck, and must not be replayed here. */
+    foreign(): Promise<QueuedEntry[]>;
+    remove(id: string): Promise<void>;
+    /** Records a failed attempt, keeping the entry queued. */
+    recordFailure(id: string, error: string): Promise<number>;
+}
+export declare function createOutbox(options: OutboxOptions): Outbox;
+export {};

package/src/lib/outbox.js

@@ -0,0 +1,89 @@
+import { versioned } from '@braidlabs/skew';
+import { createRecordStore } from './record-store.js';
+/**
+ * The entry contract, versioned from the first commit.
+ *
+ * A queued mutation can outlive the build that queued it — the user goes offline, the app deploys,
+ * they come back. So even this small internal shape gets an envelope: a shared store is a shared
+ * contract, and treating it as "just some JSON" because it is internal is how a coordination layer
+ * becomes a fate-sharing vector.
+ *
+ * v2 adds the overlay. An entry queued by v1 migrates up without one and simply does not tint any
+ * reader's view — which is the honest answer, since that build never recorded what it predicted.
+ * The queue itself is unaffected either way, so an old entry still sends.
+ */
+export const OutboxEntrySchema = versioned('skew-outbox-entry').next('carry the optimistic overlay', {
+    up: (entry) => entry,
+    down: ({ optimistic: _optimistic, ...rest }) => rest,
+    lossy: ['optimistic'],
+});
+const DEFAULT_COLLECTION = 'outbox';
+const DEFAULT_PARTITION = 'session';
+export function createOutbox(options) {
+    const partition = options.partition ?? DEFAULT_PARTITION;
+    const store = createRecordStore({
+        driver: options.driver,
+        collection: options.collection ?? DEFAULT_COLLECTION,
+        schema: OutboxEntrySchema,
+        ...(options.buildId === undefined ? {} : { buildId: options.buildId }),
+    });
+    const toQueued = (record) => ({
+        id: record.id,
+        owner: record.owner ?? '',
+        seq: record.seq,
+        ...record.value,
+    });
+    async function entries() {
+        return (await store.list(partition)).map(toQueued);
+    }
+    return {
+        async enqueue({ mutationId, input, id, schemaVersion, optimistic }) {
+            const entryId = id ?? crypto.randomUUID();
+            await store.put({
+                id: entryId,
+                partition,
+                owner: options.owner,
+                value: {
+                    mutationId,
+                    input,
+                    attempts: 0,
+                    queuedAt: new Date().toISOString(),
+                    ...(schemaVersion === undefined ? {} : { schemaVersion }),
+                    ...(optimistic === undefined ? {} : { optimistic }),
+                },
+            });
+            return entryId;
+        },
+        async pendingFor(key, forPartition) {
+            return (await entries()).flatMap((entry) => (entry.optimistic ?? []).filter((overlay) => overlay.key === key &&
+                // An overlay that names no partition predates this and applies as it always did.
+                (overlay.partition === undefined || forPartition === undefined || overlay.partition === forPartition)));
+        },
+        async mine() {
+            return (await entries()).filter((entry) => entry.owner === options.owner);
+        },
+        all: entries,
+        async foreign() {
+            return (await entries()).filter((entry) => entry.owner !== options.owner);
+        },
+        remove: (id) => store.delete(id, partition),
+        async recordFailure(id, error) {
+            const record = await store.get(id, partition);
+            // Already gone — a concurrent flush removed it. Not an error worth raising: the entry is in
+            // the state the caller wanted it in.
+            if (!record)
+                return 0;
+            const attempts = record.value.attempts + 1;
+            await store.put({
+                id,
+                partition: record.partition,
+                ...(record.owner === undefined ? {} : { owner: record.owner }),
+                // Preserved so a retry does not jump the queue ahead of entries queued after it.
+                seq: record.seq,
+                value: { ...record.value, attempts, lastError: error },
+            });
+            return attempts;
+        },
+    };
+}
+//# sourceMappingURL=outbox.js.map

package/src/lib/outbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbox.js","sourceRoot":"","sources":["../../../../../libs/data/src/lib/outbox.ts"],"names":[],"mappings":"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"}

package/src/lib/partitions.d.ts

@@ -0,0 +1,70 @@
+import { type RecordDriver } from './record-store.js';
+/**
+ * Moving records from one partition to another.
+ *
+ * A partition is a hard boundary — no read crosses one, which is what makes purge complete and a
+ * tenant switch a pointer move. That is the right default and it leaves one real case unserved:
+ * **a guest who signs in.** Their cart, their draft, their half-finished form all live in the guest
+ * partition, and the signed-in customer is a different partition by construction. Somebody has to
+ * carry it across, and "somebody" was previously every application, by hand, differently.
+ *
+ * The important decision here is what gets copied. **Records move as stored bytes — envelope
+ * untouched.** Reading each record through a typed store and writing it back would re-envelope it at
+ * *this* build's version, so a record written by a newer app would be silently down-projected on the
+ * way across, or dropped for being unreadable. Copying the envelope verbatim means a v3 record
+ * arrives as a v3 record: a reader that could project it still can, and one that cannot still gets an
+ * honest `ahead` rather than quietly lossy data.
+ */
+export type PartitionConflictPolicy = 'skip' | 'overwrite';
+export interface CopyPartitionOptions {
+    driver: RecordDriver;
+    /** Where the records are now — a guest partition, usually. */
+    from: string;
+    /** Where they should end up. */
+    to: string;
+    /**
+     * Which collections to carry across.
+     *
+     * Named rather than "all", because the answer is rarely all of them: a cart should follow its
+     * owner, and a queued mutation usually should not — the outbox belongs to the session that made
+     * it, and replaying a guest's queued writes as a signed-in customer changes who performed them.
+     */
+    collections: readonly string[];
+    /**
+     * What to do when the destination already holds a record with the same id.
+     *
+     * `'skip'` by default, and the default matters: the destination is the account the person has
+     * actually signed in to, so its own saved cart is the more authoritative of the two. Overwriting
+     * it with whatever a guest session left on this device is how someone's real basket disappears.
+     */
+    onConflict?: PartitionConflictPolicy;
+    /**
+     * `'move'` clears the source afterwards; `'copy'` (default) leaves it alone.
+     *
+     * Copy is the safer default because the operation is not atomic — an interrupted move that had
+     * already deleted the source would lose the records outright, whereas an interrupted copy leaves
+     * two readable partitions and a second attempt to make.
+     */
+    mode?: 'copy' | 'move';
+}
+export interface CopyPartitionResult {
+    copied: number;
+    /** Records the destination already had, left as they were. */
+    skipped: number;
+    /** Records overwritten in the destination, under `onConflict: 'overwrite'`. */
+    replaced: number;
+}
+/**
+ * Copies (or moves) every record in `from` into `to`, across the named collections.
+ *
+ * ```ts
+ * await copyPartition({
+ *   driver,
+ *   from: guestPartition,
+ *   to: tenancy.partition(),
+ *   collections: ['cart'],
+ *   mode: 'move',
+ * });
+ * ```
+ */
+export declare function copyPartition(options: CopyPartitionOptions): Promise<CopyPartitionResult>;

package/src/lib/partitions.js

@@ -0,0 +1,62 @@
+import { withLock } from './locks.js';
+import { storageKey } from './record-store.js';
+/**
+ * Copies (or moves) every record in `from` into `to`, across the named collections.
+ *
+ * ```ts
+ * await copyPartition({
+ *   driver,
+ *   from: guestPartition,
+ *   to: tenancy.partition(),
+ *   collections: ['cart'],
+ *   mode: 'move',
+ * });
+ * ```
+ */
+export async function copyPartition(options) {
+    const result = { copied: 0, skipped: 0, replaced: 0 };
+    // Copying a partition onto itself is a no-op rather than an error: the caller is usually deriving
+    // both ends from a sign-in that may not have changed anything.
+    if (options.from === options.to)
+        return result;
+    const onConflict = options.onConflict ?? 'skip';
+    const mode = options.mode ?? 'copy';
+    // Held so a sign-out purge cannot run through the destination while records are landing in it.
+    // Keyed on the destination, which is the partition whose contents this changes.
+    const outcome = await withLock(`skew:data:partition:${options.to}`, async () => {
+        for (const collection of options.collections) {
+            for (const record of await options.driver.list(collection, options.from)) {
+                const destinationId = storageKey(options.to, record.key);
+                const existing = await options.driver.get(collection, destinationId);
+                if (existing && onConflict === 'skip') {
+                    result.skipped += 1;
+                    continue;
+                }
+                await options.driver.put(collection, {
+                    // Only the address changes. `envelope` is carried verbatim, so the record keeps the
+                    // version its writer stamped on it.
+                    ...record,
+                    id: destinationId,
+                    partition: options.to,
+                });
+                if (existing)
+                    result.replaced += 1;
+                else
+                    result.copied += 1;
+            }
+        }
+        if (mode === 'move') {
+            // After every collection, not per collection: a failure partway through has then left the
+            // source intact rather than half-emptied.
+            for (const collection of options.collections) {
+                await options.driver.clearPartition(collection, options.from);
+            }
+        }
+        return result;
+    }, { ifAvailable: false });
+    if (!outcome.acquired) {
+        throw new Error(`[skew/data] could not take the lock for partition "${options.to}" — nothing was copied`);
+    }
+    return outcome.value;
+}
+//# sourceMappingURL=partitions.js.map

package/src/lib/partitions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"partitions.js","sourceRoot":"","sources":["../../../../../libs/data/src/lib/partitions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,UAAU,EAAqB,MAAM,mBAAmB,CAAC;AA6DlE;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,OAA6B;IAC/D,MAAM,MAAM,GAAwB,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;IAE3E,kGAAkG;IAClG,+DAA+D;IAC/D,IAAI,OAAO,CAAC,IAAI,KAAK,OAAO,CAAC,EAAE;QAAE,OAAO,MAAM,CAAC;IAE/C,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,MAAM,CAAC;IAChD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,MAAM,CAAC;IAEpC,+FAA+F;IAC/F,gFAAgF;IAChF,MAAM,OAAO,GAAG,MAAM,QAAQ,CAC5B,uBAAuB,OAAO,CAAC,EAAE,EAAE,EACnC,KAAK,IAAI,EAAE;QACT,KAAK,MAAM,UAAU,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;YAC7C,KAAK,MAAM,MAAM,IAAI,MAAM,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;gBACzE,MAAM,aAAa,GAAG,UAAU,CAAC,OAAO,CAAC,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;gBACzD,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,UAAU,EAAE,aAAa,CAAC,CAAC;gBAErE,IAAI,QAAQ,IAAI,UAAU,KAAK,MAAM,EAAE,CAAC;oBACtC,MAAM,CAAC,OAAO,IAAI,CAAC,CAAC;oBACpB,SAAS;gBACX,CAAC;gBAED,MAAM,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,UAAU,EAAE;oBACnC,oFAAoF;oBACpF,oCAAoC;oBACpC,GAAG,MAAM;oBACT,EAAE,EAAE,aAAa;oBACjB,SAAS,EAAE,OAAO,CAAC,EAAE;iBACtB,CAAC,CAAC;gBAEH,IAAI,QAAQ;oBAAE,MAAM,CAAC,QAAQ,IAAI,CAAC,CAAC;;oBAC9B,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC;YAC1B,CAAC;QACH,CAAC;QAED,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;YACpB,0FAA0F;YAC1F,0CAA0C;YAC1C,KAAK,MAAM,UAAU,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;gBAC7C,MAAM,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,UAAU,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;YAChE,CAAC;QACH,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC,EACD,EAAE,WAAW,EAAE,KAAK,EAAE,CACvB,CAAC;IAEF,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CACb,sDAAsD,OAAO,CAAC,EAAE,wBAAwB,CACzF,CAAC;IACJ,CAAC;IAED,OAAO,OAAO,CAAC,KAAK,CAAC;AACvB,CAAC"}