@braidlabs/angular-data 0.1.1

package/fesm2022/braidlabs-angular-data.mjs

@@ -0,0 +1,953 @@
+import * as i0 from '@angular/core';
+import { signal, computed, Injectable, inject, InjectionToken, DestroyRef, makeEnvironmentProviders, provideEnvironmentInitializer, PLATFORM_ID, DOCUMENT } from '@angular/core';
+import { indexedDbRecordDriver, memoryRecordDriver, createOutbox, drainOutbox } from '@braidlabs/data';
+import { isPlatformBrowser } from '@angular/common';
+
+/**
+ * Entity identity.
+ *
+ * The gap this closes: `httpResource()` and friends are *per-call* caches. Two
+ * requests that return the same record produce two independent copies, and
+ * updating one leaves the other stale. Deduplicating them requires knowing that
+ * both payloads describe the same thing — which requires a declared identity.
+ */
+/**
+ * Declares an entity type.
+ *
+ * ```ts
+ * export const Bulletin = entity<Bulletin>({ name: 'bulletin', key: (b) => b.id });
+ * ```
+ *
+ * Declare each type once and export it — identity is only useful if every
+ * query and mutation agrees on it.
+ */
+function entity(definition) {
+    if (!definition.name) {
+        throw new TypeError('[skew/data] entity() requires a name');
+    }
+    if (typeof definition.key !== 'function') {
+        throw new TypeError(`[skew/data] entity "${definition.name}" requires a key function`);
+    }
+    return { name: definition.name, key: definition.key };
+}
+/** Tag helpers, so invalidation reads the same way everywhere. */
+const tag = {
+    /** A single record: `bulletin#42`. */
+    entity(type, id) {
+        return `${type.name}#${id}`;
+    },
+    /** Every record of a type: `bulletin#*`. */
+    all(type) {
+        return `${type.name}#*`;
+    },
+    /** An arbitrary named collection or view. */
+    collection(name) {
+        return name;
+    },
+};
+
+class PendingWrites {
+    groups = signal([], /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "groups" }] : /* istanbul ignore next */ []));
+    /** Every pending overlay on the page, in the order the writes were made. */
+    overlays = computed(() => this.groups().flatMap((group) => group.overlays), /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "overlays" }] : /* istanbul ignore next */ []));
+    /** Whether anything on screen is showing work the server has not confirmed. */
+    hasPending = computed(() => this.groups().length > 0, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "hasPending" }] : /* istanbul ignore next */ []));
+    /**
+     * Records a write's prediction.
+     *
+     * Applied synchronously, before the entry reaches storage: a UI that waits for IndexedDB to show
+     * what the user just typed is a UI that flickers. Storage remains the truth — `syncFromQueue`
+     * replaces this the moment the queue is next read.
+     */
+    add(id, overlays, options) {
+        if (overlays.length === 0)
+            return;
+        this.groups.update((groups) => [
+            ...groups.filter((group) => group.id !== id),
+            { id, durable: options.durable, overlays },
+        ]);
+    }
+    /** Drops a group: a confirmation, or a rollback. There is no difference at this level. */
+    settle(id) {
+        this.groups.update((groups) => groups.filter((group) => group.id !== id));
+    }
+    /** Re-keys a group once its entry id is known, so the queue's copy replaces the same group. */
+    rename(from, to) {
+        this.groups.update((groups) => groups.map((group) => (group.id === from ? { ...group, id: to, durable: true } : group)));
+    }
+    /**
+     * Rebuilds every durable group from the queue.
+     *
+     * This is the derivation. Called on every outbox refresh — including the one after rehydrating
+     * from storage, which is how a reload gets the overlay back without anything in memory having
+     * survived, and how one app comes to show another's unsent edits.
+     */
+    syncFromQueue(entries) {
+        const fromQueue = entries
+            .filter((entry) => (entry.optimistic ?? []).length > 0)
+            .map((entry) => ({
+            id: entry.id,
+            durable: true,
+            overlays: (entry.optimistic ?? []).map(fromOutboxOverlay),
+        }));
+        this.groups.update((groups) => [...groups.filter((group) => !group.durable), ...fromQueue]);
+    }
+    /** Sign-out, and tests. */
+    clear() {
+        this.groups.set([]);
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.8", ngImport: i0, type: PendingWrites, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "22.0.8", ngImport: i0, type: PendingWrites, providedIn: 'root' });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.8", ngImport: i0, type: PendingWrites, decorators: [{
+            type: Injectable,
+            args: [{ providedIn: 'root' }]
+        }] });
+/** `bulletin#42` — the same key `tag.entity` produces, so one write's tag and overlay agree. */
+function overlayKey(typeName, id) {
+    return `${typeName}#${id}`;
+}
+function toOutboxOverlay(overlay) {
+    return {
+        key: overlayKey(overlay.typeName, overlay.id),
+        patch: overlay.patch,
+        ...(overlay.removed ? { removed: true } : {}),
+    };
+}
+/**
+ * Splits at the *first* `#`, because an id may contain one and a type name may not.
+ */
+function fromOutboxOverlay(overlay) {
+    const at = overlay.key.indexOf('#');
+    return {
+        typeName: at === -1 ? overlay.key : overlay.key.slice(0, at),
+        id: at === -1 ? '' : overlay.key.slice(at + 1),
+        patch: overlay.patch,
+        ...(overlay.removed ? { removed: true } : {}),
+    };
+}
+/** Applies the overlays for one record, in order. `undefined` means pending removal. */
+function applyOverlays(confirmed, overlays) {
+    let value = confirmed;
+    for (const overlay of overlays) {
+        value = overlay.removed ? undefined : { ...(value ?? {}), ...overlay.patch };
+    }
+    return value;
+}
+function recordOverlays(apply) {
+    const recorded = [];
+    const types = new Map();
+    const remember = (type) => types.set(type.name, type);
+    const tx = {
+        upsert(type, values) {
+            remember(type);
+            const list = Array.isArray(values) ? values : [values];
+            for (const value of list) {
+                recorded.push({
+                    typeName: type.name,
+                    id: type.key(value),
+                    patch: value,
+                });
+            }
+        },
+        patch(type, id, partial) {
+            remember(type);
+            recorded.push({ typeName: type.name, id, patch: partial });
+        },
+        remove(type, id) {
+            remember(type);
+            recorded.push({ typeName: type.name, id, patch: {}, removed: true });
+        },
+    };
+    apply(tx);
+    return { overlays: recorded, types };
+}
+
+class EntityStore {
+    state = signal(new Map(), /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "state" }] : /* istanbul ignore next */ []));
+    pending = inject(PendingWrites);
+    /**
+     * Memoized per `type#id`. Without this, calling `select()` inside a template
+     * would mint a fresh computed on every change-detection pass — a subtle and
+     * expensive footgun.
+     */
+    selectCache = new Map();
+    allCache = new Map();
+    /** A single record as this page shows it: confirmed, with any pending write applied. */
+    select(type, id) {
+        const cacheKey = `${type.name}#${id}`;
+        const existing = this.selectCache.get(cacheKey);
+        if (existing)
+            return existing;
+        const derived = computed(() => this.view(type, id), /* @ts-ignore */
+        ...(ngDevMode ? [{ debugName: "derived" }] : /* istanbul ignore next */ []));
+        this.selectCache.set(cacheKey, derived);
+        return derived;
+    }
+    /**
+     * Every record of a type, in insertion order, with pending writes applied.
+     *
+     * A pending record nothing has confirmed yet still appears, and a pending removal does not: a
+     * list that omits what the user just created, or keeps what they just deleted, is the same bug
+     * seen from either end.
+     */
+    selectAll(type) {
+        const existing = this.allCache.get(type.name);
+        if (existing)
+            return existing;
+        const derived = computed(() => {
+            const table = this.state().get(type.name);
+            const overlaid = this.pending.overlays().filter((overlay) => overlay.typeName === type.name);
+            const ids = new Set([...(table?.keys() ?? []), ...overlaid.map((overlay) => overlay.id)]);
+            const rows = [];
+            for (const id of ids) {
+                const value = this.view(type, id);
+                if (value !== undefined)
+                    rows.push(value);
+            }
+            return rows;
+        }, /* @ts-ignore */
+        ...(ngDevMode ? [{ debugName: "derived" }] : /* istanbul ignore next */ []));
+        this.allCache.set(type.name, derived);
+        return derived;
+    }
+    /**
+     * A filtered view. Not memoized by predicate — call it once and keep the
+     * result, as you would any other `computed`.
+     */
+    query(type, predicate) {
+        const all = this.selectAll(type);
+        return computed(() => all().filter(predicate));
+    }
+    /**
+     * Reads a record without subscribing. For use inside effects and handlers.
+     *
+     * The same value `select` would give, pending writes included — a read that disagrees with the
+     * subscribed read depending on which one you happened to call is a trap, not an optimization.
+     * {@link peekConfirmed} is the one that skips the overlay.
+     */
+    peek(type, id) {
+        return this.view(type, id);
+    }
+    /**
+     * The record as the server last reported it, ignoring anything queued.
+     *
+     * What a conflict is measured against: "the server disagreed with you" is a claim about the
+     * prediction, so comparing against a value that already includes the prediction would answer a
+     * different question.
+     */
+    peekConfirmed(type, id) {
+        return this.state().get(type.name)?.get(id);
+    }
+    upsert(type, values) {
+        this.applyWrites(this.toWrites(type, values));
+    }
+    patch(type, id, partial) {
+        const current = this.peek(type, id);
+        if (current === undefined)
+            return;
+        this.applyWrites([{ typeName: type.name, id, value: { ...current, ...partial } }]);
+    }
+    remove(type, id) {
+        this.applyWrites([{ typeName: type.name, id, value: undefined }]);
+    }
+    /** Empties a type, or the whole store. Mainly for sign-out and tests. */
+    clear(type) {
+        if (!type) {
+            this.state.set(new Map());
+            return;
+        }
+        const next = new Map(this.state());
+        next.delete(type.name);
+        this.state.set(next);
+    }
+    /**
+     * Applies writes that can be undone as a unit.
+     *
+     * ```ts
+     * const tx = store.transaction();
+     * tx.apply((t) => t.patch(Bulletin, id, { status: 'published' }));
+     * // …server says no…
+     * tx.rollback();
+     * ```
+     */
+    transaction() {
+        const undoLog = [];
+        let rolledBack = false;
+        const record = (typeName, id) => {
+            // Only the *first* prior value matters; later writes in the same
+            // transaction are intermediate states we never want to restore to.
+            if (undoLog.some((entry) => entry.typeName === typeName && entry.id === id))
+                return;
+            undoLog.push({ typeName, id, previous: this.state().get(typeName)?.get(id) });
+        };
+        const tx = {
+            upsert: (type, values) => {
+                const writes = this.toWrites(type, values);
+                for (const write of writes)
+                    record(write.typeName, write.id);
+                this.applyWrites(writes);
+            },
+            patch: (type, id, partial) => {
+                record(type.name, id);
+                const current = this.peek(type, id);
+                if (current === undefined)
+                    return;
+                this.applyWrites([{ typeName: type.name, id, value: { ...current, ...partial } }]);
+            },
+            remove: (type, id) => {
+                record(type.name, id);
+                this.applyWrites([{ typeName: type.name, id, value: undefined }]);
+            },
+        };
+        return {
+            apply(fn) {
+                fn(tx);
+            },
+            rollback: () => {
+                if (rolledBack)
+                    return;
+                rolledBack = true;
+                this.applyWrites(
+                // Restore in reverse so overlapping writes unwind correctly.
+                [...undoLog].reverse().map((entry) => ({
+                    typeName: entry.typeName,
+                    id: entry.id,
+                    value: entry.previous,
+                })));
+            },
+            get committed() {
+                return !rolledBack;
+            },
+        };
+    }
+    // --- internals ---------------------------------------------------------
+    /** `confirmed ⊕ pending` for one record. The single place the two halves meet. */
+    view(type, id) {
+        const confirmed = this.state().get(type.name)?.get(id);
+        const overlays = this.pending
+            .overlays()
+            .filter((overlay) => overlay.typeName === type.name && overlay.id === id);
+        if (overlays.length === 0)
+            return confirmed;
+        return applyOverlays(confirmed, overlays);
+    }
+    toWrites(type, values) {
+        const list = Array.isArray(values) ? values : [values];
+        return list.map((value) => ({
+            typeName: type.name,
+            id: type.key(value),
+            value,
+        }));
+    }
+    /**
+     * Single write path, so every mutation produces exactly one signal
+     * notification regardless of how many records it touched.
+     */
+    applyWrites(writes) {
+        if (writes.length === 0)
+            return;
+        const next = new Map(this.state());
+        const touched = new Map();
+        for (const { typeName, id, value } of writes) {
+            let table = touched.get(typeName);
+            if (!table) {
+                table = new Map(next.get(typeName) ?? []);
+                touched.set(typeName, table);
+            }
+            if (value === undefined)
+                table.delete(id);
+            else
+                table.set(id, value);
+        }
+        for (const [typeName, table] of touched)
+            next.set(typeName, table);
+        this.state.set(next);
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.8", ngImport: i0, type: EntityStore, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "22.0.8", ngImport: i0, type: EntityStore, providedIn: 'root' });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.8", ngImport: i0, type: EntityStore, decorators: [{
+            type: Injectable,
+            args: [{ providedIn: 'root' }]
+        }] });
+
+/**
+ * Tag-based invalidation.
+ *
+ * Tags rather than TTLs, because a time-to-live is a guess about when data went
+ * stale, whereas a mutation *knows*. `bulletin#42` and `bulletins` are claims
+ * about what a query depends on; invalidating a tag re-runs exactly the queries
+ * that said they cared.
+ *
+ * Wildcards are supported in one direction only: invalidating `bulletin#*`
+ * matches every `bulletin#…` subscriber. A subscriber may also register the
+ * wildcard itself, in which case any invalidation of that type reaches it.
+ */
+class CacheRegistry {
+    subscribers = new Map();
+    /**
+     * Registers interest in a set of tags. Returns a disposer.
+     *
+     * Tags are supplied as a getter and re-read on each invalidation, so a query
+     * whose tags depend on signals (a route param, a filter) stays correct
+     * without having to re-subscribe.
+     */
+    subscribe(getTags, notify) {
+        const token = Symbol('skew-cache-subscriber');
+        this.subscribers.set(token, { getTags, notify });
+        return () => void this.subscribers.delete(token);
+    }
+    /**
+     * Marks tags stale, notifying every matching subscriber.
+     *
+     * Notification is synchronous but failure-isolated: one subscriber throwing
+     * must not prevent the others from refreshing.
+     */
+    invalidate(...tags) {
+        if (tags.length === 0)
+            return;
+        for (const subscriber of [...this.subscribers.values()]) {
+            let interested = false;
+            try {
+                interested = subscriber.getTags().some((owned) => tags.some((t) => tagsMatch(owned, t)));
+            }
+            catch {
+                // A tag getter that throws (a signal read outside its context, say)
+                // must not take down invalidation for everyone else.
+                interested = false;
+            }
+            if (!interested)
+                continue;
+            try {
+                subscriber.notify();
+            }
+            catch {
+                // A refresh that throws is that query's problem, not this loop's.
+            }
+        }
+    }
+    /** Subscriber count. Diagnostics and tests only. */
+    get size() {
+        return this.subscribers.size;
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.8", ngImport: i0, type: CacheRegistry, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "22.0.8", ngImport: i0, type: CacheRegistry, providedIn: 'root' });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.8", ngImport: i0, type: CacheRegistry, decorators: [{
+            type: Injectable,
+            args: [{ providedIn: 'root' }]
+        }] });
+/**
+ * `bulletin#*` matches `bulletin#42` in either position, so a mutation can
+ * invalidate a whole type without enumerating ids, and a list query can
+ * subscribe to a whole type without knowing which ids it will receive.
+ */
+function tagsMatch(a, b) {
+    if (a === b)
+        return true;
+    const wildcardOf = (tag) => (tag.endsWith('#*') ? tag.slice(0, -1) : null);
+    const aPrefix = wildcardOf(a);
+    if (aPrefix && b.startsWith(aPrefix))
+        return true;
+    const bPrefix = wildcardOf(b);
+    if (bPrefix && a.startsWith(bPrefix))
+        return true;
+    return false;
+}
+
+const DATA_OPTIONS = new InjectionToken('SKEW_DATA_OPTIONS');
+const OUTBOX_COLLECTION = 'outbox';
+/**
+ * Whether this environment can persist at all.
+ *
+ * False during server rendering, where there is no IndexedDB — and no point in one, since the
+ * outbox exists to survive a *client* reload. Falling back to memory keeps `persistOutbox: true` a
+ * safe thing to write in a config shared by both bootstraps, which is where it naturally goes.
+ */
+function canPersist() {
+    return typeof globalThis.indexedDB !== 'undefined';
+}
+function persistentDriver(input) {
+    return indexedDbRecordDriver({
+        collections: [OUTBOX_COLLECTION, ...(input.collections ?? [])],
+        ...(input.database === undefined ? {} : { database: input.database }),
+    });
+}
+function resolveDataOptions(input = {}) {
+    const persisting = input.persistOutbox === true || input.driver !== undefined;
+    if (persisting && !input.owner) {
+        throw new Error('[skew/data] a persisted outbox needs `owner`: a string identifying this application.\n' +
+            'The outbox is shared across every app on the origin, and ownership is what stops one app ' +
+            "from replaying or discarding another's queued mutations. Defaulting it would put every app " +
+            'under the same name, which is the collision it exists to prevent.');
+    }
+    return {
+        driver: input.driver ?? (input.persistOutbox && canPersist() ? persistentDriver(input) : memoryRecordDriver()),
+        owner: input.owner ?? 'app',
+        maxOutboxAttempts: input.maxOutboxAttempts ?? 5,
+        ...(input.onOutboxError === undefined ? {} : { onOutboxError: input.onOutboxError }),
+        flushOnReconnect: input.flushOnReconnect ?? true,
+        ...(input.buildId === undefined ? {} : { buildId: input.buildId }),
+    };
+}
+
+class OutboxService {
+    options = inject(DATA_OPTIONS);
+    pending = inject(PendingWrites);
+    runners = new Map();
+    mineSignal = signal([], /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "mineSignal" }] : /* istanbul ignore next */ []));
+    foreignSignal = signal([], /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "foreignSignal" }] : /* istanbul ignore next */ []));
+    flushingSignal = signal(false, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "flushingSignal" }] : /* istanbul ignore next */ []));
+    /** This app's queued work, oldest first — what it can actually replay. */
+    entries = this.mineSignal.asReadonly();
+    /**
+     * Work queued by another app on this page. Waiting, not stuck: it replays when its owner is
+     * mounted. Surfaced so an app can render "someone has unsent changes" honestly rather than
+     * reporting only what it can see of the queue.
+     */
+    foreignEntries = this.foreignSignal.asReadonly();
+    /**
+     * Unsent work across the whole page, not just this app's.
+     *
+     * "Are there unsent changes?" is a page-wide question, and each app answering only for itself is
+     * how the indicator was wrong before. Use {@link entries} when you need what *this* app owns.
+     */
+    pendingCount = computed(() => this.mineSignal().length + this.foreignSignal().length, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "pendingCount" }] : /* istanbul ignore next */ []));
+    hasPendingWork = computed(() => this.pendingCount() > 0, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "hasPendingWork" }] : /* istanbul ignore next */ []));
+    isFlushing = this.flushingSignal.asReadonly();
+    outbox = null;
+    loaded = false;
+    get queue() {
+        this.outbox ??= createOutbox({
+            driver: this.options.driver,
+            owner: this.options.owner,
+            collection: OUTBOX_COLLECTION,
+            ...(this.options.buildId === undefined ? {} : { buildId: this.options.buildId }),
+        });
+        return this.outbox;
+    }
+    /**
+     * Registers how a mutation id replays. Called by `mutation()` at creation, which is why outbox
+     * mutations must be constructed during app start-up rather than lazily inside a click handler —
+     * otherwise a queued entry has nothing to replay into after a reload.
+     */
+    register(mutationId, runner) {
+        this.runners.set(mutationId, runner);
+    }
+    /** Rehydrates from storage. Safe to call repeatedly. */
+    async load() {
+        if (this.loaded)
+            return;
+        this.loaded = true;
+        await this.refresh();
+    }
+    async enqueue(entry) {
+        await this.load();
+        const id = await this.queue.enqueue(entry);
+        await this.refresh();
+        const queued = this.mineSignal().find((candidate) => candidate.id === id);
+        if (!queued)
+            throw new Error(`[skew/data] the outbox did not retain entry "${id}"`);
+        return queued;
+    }
+    /**
+     * Drains this app's queue in order.
+     *
+     * The rules — sequential, stop at the first failure, one drain per owner across every tab, give up
+     * loudly — live in `@braidlabs/data`'s `drainOutbox`, because this service used to carry a second
+     * copy of them and the two had already drifted apart on what to do with an entry nobody can
+     * replay. What stays here is the Angular half: signals, and re-reading the shared store into them.
+     *
+     * Only this app's entries are touched. Another app's queued work is left exactly where it is.
+     */
+    async flush() {
+        await this.load();
+        if (this.flushingSignal())
+            return { sent: 0, failed: 0, remaining: this.pendingCount(), skipped: true };
+        this.flushingSignal.set(true);
+        try {
+            const result = await drainOutbox({
+                outbox: this.queue,
+                owner: this.options.owner,
+                runnerFor: (mutationId) => this.runners.get(mutationId),
+                maxAttempts: this.options.maxOutboxAttempts,
+                ...(this.options.onOutboxError === undefined ? {} : { onError: this.options.onOutboxError }),
+            });
+            // Whatever happened — this app drained, or another tab did — the shared store moved, so the
+            // signals have to be re-read from it rather than adjusted from the counts.
+            await this.refresh();
+            return { ...result, remaining: this.pendingCount() };
+        }
+        finally {
+            this.flushingSignal.set(false);
+        }
+    }
+    /**
+     * Removes one entry, and with it the overlay derived from it.
+     *
+     * What a confirmation does, and equally what a rollback does — at this level they are the same
+     * operation, which is the point of deriving the optimistic view rather than keeping an undo log.
+     */
+    async remove(id) {
+        await this.load();
+        await this.queue.remove(id);
+        await this.refresh();
+    }
+    /**
+     * Discards this app's queued work. Sign-out, or an explicit "abandon my changes".
+     *
+     * Another app's entries survive: discarding work this app never queued and cannot replay would be
+     * deciding on someone else's behalf.
+     */
+    async clear() {
+        await this.load();
+        for (const entry of await this.queue.mine())
+            await this.queue.remove(entry.id);
+        await this.refresh();
+    }
+    /**
+     * Re-reads the shared store into signals. The store is the truth; signals are a view of it.
+     *
+     * The optimistic overlay is rebuilt here too, from the same read. That is what makes the overlay
+     * derived rather than remembered: a reload, another app's write, and a rolled-back entry all reach
+     * the screen through this one path, because all three are just a different queue.
+     */
+    async refresh() {
+        const [mine, foreign] = await Promise.all([this.queue.mine(), this.queue.foreign()]);
+        this.mineSignal.set(mine);
+        this.foreignSignal.set(foreign);
+        this.pending.syncFromQueue([...mine, ...foreign]);
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.8", ngImport: i0, type: OutboxService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "22.0.8", ngImport: i0, type: OutboxService, providedIn: 'root' });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.8", ngImport: i0, type: OutboxService, decorators: [{
+            type: Injectable,
+            args: [{ providedIn: 'root' }]
+        }] });
+
+/**
+ * Creates a query. Must be called in an injection context.
+ *
+ * ```ts
+ * readonly bulletins = query({
+ *   loader: () => firstValueFrom(this.http.get<Bulletin[]>('/api/bulletins')),
+ *   normalize: Bulletin,
+ *   tags: () => ['bulletins'],
+ * });
+ *
+ * // Read through the store, not through `bulletins.value()`:
+ * readonly rows = this.store.selectAll(Bulletin);
+ * ```
+ */
+function query(config) {
+    const store = inject(EntityStore);
+    const registry = inject(CacheRegistry);
+    const destroyRef = inject(DestroyRef);
+    const value = signal(undefined, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "value" }] : /* istanbul ignore next */ []));
+    const status = signal('idle', /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "status" }] : /* istanbul ignore next */ []));
+    const error = signal(undefined, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "error" }] : /* istanbul ignore next */ []));
+    /**
+     * Guards against a slow earlier request resolving after a newer one and
+     * overwriting fresher data — the classic out-of-order response bug.
+     */
+    let generation = 0;
+    async function run() {
+        const current = ++generation;
+        status.set('loading');
+        error.set(undefined);
+        try {
+            const result = await config.loader();
+            if (current !== generation)
+                return;
+            if (config.normalize)
+                normalizeInto(store, config.normalize, result);
+            value.set(result);
+            status.set('success');
+        }
+        catch (caught) {
+            if (current !== generation)
+                return;
+            error.set(caught);
+            status.set('error');
+        }
+    }
+    if (config.tags) {
+        const dispose = registry.subscribe(config.tags, () => void run());
+        destroyRef.onDestroy(dispose);
+    }
+    if (config.immediate ?? true)
+        void run();
+    return {
+        value: value.asReadonly(),
+        status: status.asReadonly(),
+        error: error.asReadonly(),
+        isLoading: computed(() => status() === 'loading'),
+        reload: run,
+    };
+}
+/**
+ * Walks a payload and writes every recognised entity into the store.
+ *
+ * Handles the shapes real APIs return: a bare record, an array, or an envelope
+ * such as `{ items: [...] }`. Anything unrecognised is left alone rather than
+ * guessed at — a wrong write into the shared graph is worse than no write.
+ */
+function normalizeInto(store, types, payload) {
+    const list = Array.isArray(types) ? types : [types];
+    for (const type of list) {
+        for (const candidate of collectCandidates(payload)) {
+            let id;
+            try {
+                id = type.key(candidate);
+            }
+            catch {
+                continue; // not this type
+            }
+            if (typeof id === 'string' && id.length > 0)
+                store.upsert(type, candidate);
+        }
+    }
+}
+function collectCandidates(payload) {
+    if (payload === null || payload === undefined)
+        return [];
+    if (Array.isArray(payload))
+        return payload.filter(isRecord);
+    if (!isRecord(payload))
+        return [];
+    // A single record, plus one level of common envelope shapes.
+    const nested = Object.values(payload).filter(Array.isArray).flat().filter(isRecord);
+    return [payload, ...nested];
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Creates a mutation. Must be called in an injection context.
+ *
+ * ```ts
+ * readonly publish = mutation({
+ *   id: 'bulletin.publish',
+ *   operation: (b: Bulletin) => firstValueFrom(this.http.post(`/api/bulletins/${b.id}/publish`, b)),
+ *   optimistic: (tx, b) => tx.patch(Bulletin, b.id, { status: 'published' }),
+ *   invalidates: (b) => [tag.entity(Bulletin, b.id), 'bulletins'],
+ *   durability: 'outbox',
+ *   schemaVersion: 41,
+ * });
+ * ```
+ */
+function mutation(config) {
+    const store = inject(EntityStore);
+    const registry = inject(CacheRegistry);
+    const outbox = inject(OutboxService);
+    const pending = inject(PendingWrites);
+    const durability = config.durability ?? 'memory';
+    if (durability === 'outbox' && !config.id) {
+        throw new TypeError('[skew/data] a mutation with durability: "outbox" requires a stable `id`. ' +
+            'Queued entries outlive the closure and are matched back to their operation by id.');
+    }
+    const status = signal('idle', /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "status" }] : /* istanbul ignore next */ []));
+    const error = signal(undefined, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "error" }] : /* istanbul ignore next */ []));
+    const conflict = signal(null, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "conflict" }] : /* istanbul ignore next */ []));
+    const applied = signal(0, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "applied" }] : /* istanbul ignore next */ []));
+    // Replay path. Registered eagerly so a queue rehydrated at start-up has
+    // somewhere to go — this is why outbox mutations must be created during
+    // bootstrap rather than lazily inside a handler.
+    if (durability === 'outbox' && config.id) {
+        outbox.register(config.id, async (input) => config.operation(input));
+    }
+    async function mutate(input) {
+        status.set('pending');
+        error.set(undefined);
+        conflict.set(null);
+        const recorded = config.optimistic
+            ? recordOverlays((tx) => config.optimistic?.(tx, input))
+            : { overlays: [], types: new Map() };
+        // Applied synchronously and only here: the confirmed graph is never touched by a prediction.
+        let groupId = `local:${crypto.randomUUID()}`;
+        pending.add(groupId, recorded.overlays, { durable: durability === 'outbox' });
+        if (recorded.overlays.length > 0)
+            applied.update((n) => n + 1);
+        // What the screen showed, captured before the server answers, so a conflict is measured against
+        // the prediction rather than against whatever the record has become since.
+        const expected = new Map();
+        for (const overlay of recorded.overlays) {
+            const type = recorded.types.get(overlay.typeName);
+            if (type)
+                expected.set(overlayId(overlay), store.peek(type, overlay.id));
+        }
+        // Queued *before* sending, not on failure. The entry is what readers overlay, so a write only
+        // recorded once it fails is a write nobody can see while it is in flight — and one that a crash
+        // mid-request loses entirely.
+        let entryId = null;
+        if (durability === 'outbox' && config.id) {
+            const entry = await outbox.enqueue({
+                mutationId: config.id,
+                input,
+                schemaVersion: config.schemaVersion ?? 1,
+                optimistic: recorded.overlays.map(toOutboxOverlay),
+            });
+            entryId = entry.id;
+            // Re-keyed so the queue's own copy of this group replaces it rather than doubling it.
+            pending.rename(groupId, entry.id);
+            groupId = entry.id;
+        }
+        try {
+            const result = await config.operation(input);
+            const found = detectConflict(recorded, expected, result, store);
+            let confirmed = result;
+            if (found) {
+                const policy = config.onConflict ?? 'raise';
+                if (typeof policy === 'function')
+                    confirmed = policy(found);
+                else if (policy === 'raise')
+                    conflict.set(found);
+            }
+            config.onSuccess?.(store, confirmed, input);
+            // The overlay lifts only after the confirmed value is in the store, so the value on screen
+            // never drops back to the old one for a frame between the two.
+            await settle(entryId, groupId);
+            const tags = config.invalidates?.(input, result);
+            if (tags?.length)
+                registry.invalidate(...tags);
+            status.set('success');
+            return result;
+        }
+        catch (caught) {
+            if (entryId) {
+                // Keep the prediction and keep the entry: from the user's point of view the change happened,
+                // and the queue is what will make that true when the network returns.
+                status.set('success');
+                return undefined;
+            }
+            // Rollback is deletion. Nothing was written to the confirmed graph, so there is nothing to
+            // restore and no undo log that could have gone stale while the request was in flight.
+            await settle(null, groupId);
+            error.set(caught);
+            status.set('error');
+            throw caught;
+        }
+    }
+    /** Drops the group, and the entry behind it when there is one. */
+    async function settle(entryId, groupId) {
+        if (entryId)
+            await outbox.remove(entryId);
+        pending.settle(groupId);
+        applied.update((n) => (n > 0 ? n - 1 : 0));
+    }
+    return {
+        mutate,
+        status: status.asReadonly(),
+        error: error.asReadonly(),
+        isPending: computed(() => status() === 'pending'),
+        hasPendingWrite: computed(() => applied() > 0),
+        conflict: conflict.asReadonly(),
+        acknowledgeConflict: () => conflict.set(null),
+    };
+}
+const overlayId = (overlay) => `${overlay.typeName}#${overlay.id}`;
+/**
+ * Finds the disagreement, if the server's answer is one that can disagree.
+ *
+ * A conflict is only decidable when the response *is* the record: an operation resolving with
+ * `void`, an id, or a receipt has not contradicted anything, and reporting one would be inventing a
+ * disagreement out of a shape mismatch.
+ */
+function detectConflict(recorded, expected, result, store) {
+    if (result === null || typeof result !== 'object')
+        return null;
+    for (const overlay of recorded.overlays) {
+        if (overlay.removed)
+            continue;
+        const type = recorded.types.get(overlay.typeName);
+        if (!type || !describes(type, overlay.id, result))
+            continue;
+        const predicted = (expected.get(overlayId(overlay)) ?? store.peekConfirmed(type, overlay.id));
+        const actual = result;
+        const paths = Object.keys(overlay.patch).filter((path) => !same(predicted?.[path], actual[path]));
+        if (paths.length > 0) {
+            return {
+                expected: predicted,
+                actual: result,
+                paths,
+                entity: { typeName: overlay.typeName, id: overlay.id },
+            };
+        }
+    }
+    return null;
+}
+/** Whether the response is this record. A `key` that throws on a foreign shape is a "no". */
+function describes(type, id, result) {
+    try {
+        return type.key(result) === id;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Structural equality, by serialization — adequate because both sides are values that came off the
+ * wire moments ago, and a deep-equality helper would be code defending against inputs this path
+ * cannot receive.
+ */
+function same(a, b) {
+    return a === b || JSON.stringify(a) === JSON.stringify(b);
+}
+
+/**
+ * Enables the data layer.
+ *
+ * ```ts
+ * provideSkewData({
+ *   owner: 'bulletin',
+ *   persistOutbox: true,
+ *   buildId: BUILD_ID,
+ *   onOutboxError: (message, detail) => telemetry.error(message, detail),
+ * });
+ * ```
+ */
+function provideSkewData(input = {}) {
+    const options = resolveDataOptions(input);
+    return makeEnvironmentProviders([
+        { provide: DATA_OPTIONS, useValue: options },
+        provideEnvironmentInitializer(() => {
+            const outbox = inject(OutboxService);
+            const isBrowser = isPlatformBrowser(inject(PLATFORM_ID));
+            if (!isBrowser)
+                return;
+            // Rehydrate immediately: work queued before the last reload should reach
+            // the server as soon as this build is running, not on the next mutation.
+            void outbox.load().then(() => outbox.flush());
+            if (options.flushOnReconnect) {
+                const view = inject(DOCUMENT).defaultView;
+                view?.addEventListener('online', () => void outbox.flush());
+            }
+        }),
+    ]);
+}
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { CacheRegistry, DATA_OPTIONS, EntityStore, OUTBOX_COLLECTION, OutboxService, PendingWrites, applyOverlays, entity, fromOutboxOverlay, mutation, normalizeInto, overlayKey, provideSkewData, query, recordOverlays, resolveDataOptions, tag, tagsMatch, toOutboxOverlay };
+//# sourceMappingURL=braidlabs-angular-data.mjs.map