zerodrift 1.0.0

package/dist/core/TransactionQueue.js

@@ -0,0 +1,601 @@
+/**
+ * TransactionQueue — manages transaction lifecycle and batch undo.
+ *
+ * Three queues:
+ *   pending       → created, not yet sent
+ *   executing     → sent to server, awaiting response
+ *   awaitingSync  → server ACK'd, waiting for delta packet with syncId
+ *
+ * Batch undo:
+ *   beginBatch() opens a batch. All save() calls inside share a batchId.
+ *   endBatch() closes it. undo() pops the entire batch and reverts all.
+ *
+ * The undo stack stores "entries" — either a single tx or a batch of txs.
+ */
+import { ModelRegistry } from "./ModelRegistry";
+import { toError } from "./types";
+import { BaseTransaction, UpdateTransaction, CreateTransaction, DeleteTransaction, ArchiveTransaction, } from "./Transaction";
+import { TransactionState } from "./types";
+const isAction = (e) => !(e instanceof BaseTransaction);
+export class TransactionQueue {
+    constructor(database, pool, undoLimit = 100) {
+        this.sender = null;
+        // The three queues
+        this.pending = [];
+        this.executing = [];
+        this.awaitingSync = [];
+        // Undo/redo
+        this.undoStack = [];
+        this.redoStack = [];
+        // Active batch state. `activeBatchEntries` mixes BaseTransactions and
+        // UndoableActions so a single user action that combines model edits and
+        // remote API calls undoes as one unit, in reverse insertion order.
+        this.activeBatchId = null;
+        this.activeBatchEntries = [];
+        this.actionHandlers = null;
+        // When true, enqueue() and endBatch() skip undo stack mutations.
+        // Set during undo/redo so their inverse operations don't re-enter the stack.
+        this.suppressUndoStack = false;
+        // Flush timer
+        this.flushTimer = null;
+        this.flushDelay = 50; // ms — batches rapid saves
+        this.listeners = new Set();
+        this.reportError = null;
+        this.database = database;
+        this.pool = pool;
+        this.undoLimit = undoLimit;
+    }
+    setErrorReporter(reporter) {
+        this.reportError = reporter;
+    }
+    setSender(sender) {
+        this.sender = sender;
+    }
+    setActionHandlers(handlers) {
+        this.actionHandlers = handlers;
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    notify() {
+        this.listeners.forEach((listener) => listener());
+    }
+    // ── Batch API ─────────────────────────────────────────────────────────────
+    beginBatch() {
+        if (this.activeBatchId != null) {
+            throw new Error(`Nested batches are not supported. Active batch "${this.activeBatchId}" ` +
+                `must end before opening another batch.`);
+        }
+        const batchId = crypto.randomUUID();
+        this.activeBatchId = batchId;
+        this.activeBatchEntries = [];
+        return batchId;
+    }
+    endBatch(batchId) {
+        if (this.activeBatchId !== batchId) {
+            return;
+        }
+        if (this.activeBatchEntries.length > 0 && !this.suppressUndoStack) {
+            this.undoStack.push({
+                kind: "batch",
+                batchId,
+                entries: [...this.activeBatchEntries],
+            });
+            if (this.undoStack.length > this.undoLimit) {
+                this.undoStack.shift();
+            }
+            this.redoStack = [];
+            this.notify();
+        }
+        this.activeBatchId = null;
+        this.activeBatchEntries = [];
+    }
+    get hasActiveBatch() {
+        return this.activeBatchId != null;
+    }
+    // ── Enqueue methods (one per transaction type) ────────────────────────────
+    async enqueueUpdate(modelId, modelName, changes) {
+        const tx = new UpdateTransaction(modelId, modelName, changes);
+        await this.enqueue(tx);
+        return tx;
+    }
+    async enqueueCreate(modelId, modelName, data) {
+        await this.enqueue(new CreateTransaction(modelId, modelName, data));
+    }
+    async enqueueDelete(model) {
+        const meta = ModelRegistry.getMetaForInstance(model);
+        const tx = new DeleteTransaction(model.id, meta?.name ?? "Unknown", model.serialize());
+        if (meta != null) {
+            this.pool.remove(meta.name, model.id);
+        } // optimistic removal
+        await this.enqueue(tx);
+    }
+    /** Record an already-committed remote side-effect on the undo stack. No
+     *  pending/executing/awaitingSync involvement and no IDB caching — the
+     *  consumer's API call already happened, so there's nothing to resend. */
+    enqueueAction(action) {
+        if (this.activeBatchId != null) {
+            this.activeBatchEntries.push(action);
+            return;
+        }
+        if (this.suppressUndoStack) {
+            return;
+        }
+        this.undoStack.push({ kind: "single", item: action });
+        if (this.undoStack.length > this.undoLimit) {
+            this.undoStack.shift();
+        }
+        this.redoStack = [];
+        this.notify();
+    }
+    async enqueueArchive(model) {
+        const meta = ModelRegistry.getMetaForInstance(model);
+        const tx = new ArchiveTransaction(model.id, meta?.name ?? "Unknown", model.serialize());
+        if (meta != null) {
+            this.pool.remove(meta.name, model.id);
+        }
+        await this.enqueue(tx);
+    }
+    async enqueue(tx) {
+        tx.state = TransactionState.Pending;
+        // Tag with batch if one is active
+        if (this.activeBatchId != null) {
+            tx.batchId = this.activeBatchId;
+            this.activeBatchEntries.push(tx);
+        }
+        else if (!this.suppressUndoStack) {
+            this.undoStack.push({ kind: "single", item: tx });
+            if (this.undoStack.length > this.undoLimit) {
+                this.undoStack.shift();
+            }
+            this.redoStack = [];
+            this.notify();
+        }
+        // Add to pending and schedule flush synchronously so callers can immediately
+        // inspect pendingCount without waiting for the IDB cache write to complete.
+        this.pending.push(tx);
+        this.scheduleFlush();
+        // Cache in IDB for offline resilience (async — idbKey needed only for resendCached)
+        tx.idbKey = await this.database.cacheTransaction(tx.serialize());
+    }
+    // ── Flush — send batch to server ──────────────────────────────────────────
+    scheduleFlush() {
+        if (this.flushTimer != null) {
+            return;
+        }
+        this.flushTimer = setTimeout(() => this.flush(), this.flushDelay);
+    }
+    async flush() {
+        this.flushTimer = null;
+        if (this.pending.length === 0 || this.sender == null) {
+            return;
+        }
+        const batch = [...this.pending];
+        this.pending = [];
+        batch.forEach((tx) => (tx.state = TransactionState.Executing));
+        this.executing.push(...batch);
+        try {
+            const response = await this.sender(batch.map((tx) => tx.serialize()));
+            this.executing = this.executing.filter((tx) => !batch.includes(tx));
+            const batchKeys = batch
+                .map((tx) => tx.idbKey)
+                .filter((k) => k != null);
+            if (response.success) {
+                // Don't delete cached records on ACK — flag them as awaiting the
+                // server's syncId. If the client crashes here, recovery checks the
+                // SyncAction store; if the matching delta already arrived, the tx
+                // is dropped without resending. The cached record is removed on
+                // resolveBySync (when the matching SSE delta hits this tab).
+                for (const tx of batch) {
+                    tx.markCompleted(response.lastSyncId);
+                    this.awaitingSync.push(tx);
+                    if (tx.idbKey != null) {
+                        const cached = {
+                            ...tx.serialize(),
+                            syncIdNeededForCompletion: response.lastSyncId,
+                        };
+                        await this.database.updateCachedTransaction(tx.idbKey, cached);
+                    }
+                }
+            }
+            else {
+                // Server rejected — revert first, then remove from IDB so failed
+                // transactions don't replay on next app start via resendCached()
+                for (let i = batch.length - 1; i >= 0; i--) {
+                    batch[i].state = TransactionState.Failed;
+                    this.revertOne(batch[i]);
+                }
+                await this.database.deleteCachedTransactions(batchKeys);
+            }
+        }
+        catch (err) {
+            // Network error — put back in pending for retry
+            this.executing = this.executing.filter((tx) => !batch.includes(tx));
+            batch.forEach((tx) => (tx.state = TransactionState.Pending));
+            this.pending = [...batch, ...this.pending];
+            setTimeout(() => this.scheduleFlush(), 2000);
+            this.reportError?.(toError(err), {
+                kind: "transactionSend",
+                batchSize: batch.length,
+            });
+        }
+    }
+    // ── Sync completion (called by SyncConnection on delta packet) ────────────
+    resolveBySync(receivedSyncId) {
+        if (this.awaitingSync.length === 0) {
+            return [];
+        }
+        const resolved = [];
+        const remaining = [];
+        for (const tx of this.awaitingSync) {
+            if (tx.isSyncedBy(receivedSyncId)) {
+                tx.state = TransactionState.Completed;
+                resolved.push(tx);
+            }
+            else {
+                remaining.push(tx);
+            }
+        }
+        this.awaitingSync = remaining;
+        // Drop the resolved txs' cached records — they're no longer needed for
+        // crash recovery (the awaited delta is now persisted in __syncActions).
+        const idbKeys = resolved
+            .map((tx) => tx.idbKey)
+            .filter((k) => k != null);
+        if (idbKeys.length > 0) {
+            void this.database.deleteCachedTransactions(idbKeys);
+        }
+        return resolved;
+    }
+    // ── Rebasing (called by SyncConnection for I/U/V/C actions) ───────────────
+    rebaseAll(modelId, modelName, serverData) {
+        const model = this.pool.getById(modelName, modelId);
+        if (model == null) {
+            return;
+        }
+        // Check all active queues for conflicting UpdateTransactions
+        const allActive = [
+            ...this.pending,
+            ...this.executing,
+            ...this.awaitingSync,
+        ];
+        for (const tx of allActive) {
+            if (tx instanceof UpdateTransaction &&
+                tx.modelId === modelId &&
+                tx.modelName === modelName &&
+                tx.conflictsWith(serverData)) {
+                tx.rebase(model, serverData);
+            }
+        }
+    }
+    // ── Revert a single transaction ───────────────────────────────────────────
+    revertOne(tx) {
+        if (tx instanceof UpdateTransaction) {
+            const model = this.pool.getById(tx.modelName, tx.modelId);
+            if (model != null) {
+                tx.revert(model);
+                this.pool.put(tx.modelName, model);
+            }
+        }
+        else if (tx instanceof CreateTransaction) {
+            this.pool.remove(tx.modelName, tx.modelId);
+        }
+        else if (tx instanceof DeleteTransaction ||
+            tx instanceof ArchiveTransaction) {
+            const meta = ModelRegistry.getModelMeta(tx.modelName);
+            if (meta != null) {
+                const inst = new meta.ctor();
+                tx.revert(inst);
+                this.pool.put(tx.modelName, inst);
+            }
+        }
+    }
+    // ── Undo/Redo — batch-aware, mixed tx + action entries ──────────────────
+    itemsOf(entry) {
+        return entry.kind === "single" ? [entry.item] : entry.entries;
+    }
+    /** Build the inverse-stack entry from a list of replaced items. Single-item
+     *  entries collapse to `single`, otherwise reuse the original `batchId`. */
+    wrapEntry(original, items) {
+        if (original.kind === "single") {
+            return { kind: "single", item: items[0] };
+        }
+        return { kind: "batch", batchId: original.batchId, entries: items };
+    }
+    /** Run the consumer's action handler, surfacing failures through
+     *  `reportError`. Returns the compensating action for the opposite stack —
+     *  the handler's return value, or the original action on void/error. */
+    async invokeActionHandler(action, phase) {
+        const handler = this.actionHandlers?.[phase];
+        if (handler == null) {
+            this.reportError?.(new Error(`No ${phase} handler configured for undoable actions`), {
+                kind: "undoableAction",
+                phase,
+                changeLogId: action.changeLogId,
+                actionType: action.actionType,
+            });
+            return action;
+        }
+        try {
+            const result = await handler(action);
+            return result ?? action;
+        }
+        catch (err) {
+            this.reportError?.(toError(err), {
+                kind: "undoableAction",
+                phase,
+                changeLogId: action.changeLogId,
+                actionType: action.actionType,
+            });
+            return action;
+        }
+    }
+    /** Reverse a single transaction and enqueue the inverse server call. */
+    async revertTx(tx) {
+        if (tx instanceof UpdateTransaction) {
+            const model = this.pool.getById(tx.modelName, tx.modelId);
+            if (model == null) {
+                return;
+            }
+            tx.revert(model);
+            this.pool.put(tx.modelName, model);
+            const inverse = {};
+            for (const [p, c] of tx.changes) {
+                inverse[p] = { oldValue: c.newValue, newValue: c.oldValue };
+            }
+            await this.enqueueUpdate(tx.modelId, tx.modelName, inverse);
+        }
+        else if (tx instanceof CreateTransaction) {
+            const model = this.pool.getById(tx.modelName, tx.modelId);
+            if (model != null) {
+                await this.enqueueDelete(model);
+            }
+        }
+        else if (tx instanceof DeleteTransaction) {
+            const meta = ModelRegistry.getModelMeta(tx.modelName);
+            if (meta != null) {
+                this.pool.hydrateAndPut(tx.modelName, meta, tx.snapshot);
+                await this.enqueueCreate(tx.modelId, tx.modelName, tx.snapshot);
+            }
+        }
+        // ArchiveTransaction has no inverse enqueue today — pass through.
+    }
+    /** Re-apply a single transaction and enqueue the forward server call. */
+    async replayTx(tx) {
+        if (tx instanceof UpdateTransaction) {
+            const model = this.pool.getById(tx.modelName, tx.modelId);
+            if (model == null) {
+                return;
+            }
+            const changes = {};
+            for (const [p, c] of tx.changes) {
+                // Dynamic property assignment on BaseModel — no better type for runtime field access
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                model[p] = c.newValue;
+                changes[p] = { oldValue: c.oldValue, newValue: c.newValue };
+            }
+            this.pool.put(tx.modelName, model);
+            await this.enqueueUpdate(tx.modelId, tx.modelName, changes);
+        }
+        else if (tx instanceof DeleteTransaction) {
+            const model = this.pool.getById(tx.modelName, tx.modelId);
+            if (model != null) {
+                await this.enqueueDelete(model);
+            }
+        }
+        else if (tx instanceof CreateTransaction) {
+            const meta = ModelRegistry.getModelMeta(tx.modelName);
+            if (meta != null) {
+                this.pool.hydrateAndPut(tx.modelName, meta, tx.data);
+                await this.enqueueCreate(tx.modelId, tx.modelName, tx.data);
+            }
+        }
+    }
+    /** Walk an entry's items in `direction`, applying tx reverts/replays and
+     *  delegating actions to the consumer's handler. Returns the compensating
+     *  items for the opposite stack, in original insertion order. */
+    async processEntry(entry, direction) {
+        const items = this.itemsOf(entry);
+        const swaps = new Map();
+        // suppressUndoStack prevents inverse txs (and any handler-side re-entries)
+        // from polluting the active stack while we replay.
+        this.suppressUndoStack = true;
+        const batchId = this.beginBatch();
+        try {
+            const apply = direction === "undo" ? this.revertTx : this.replayTx;
+            const order = direction === "undo" ? -1 : 1;
+            for (let i = direction === "undo" ? items.length - 1 : 0; i >= 0 && i < items.length; i += order) {
+                const item = items[i];
+                if (isAction(item)) {
+                    swaps.set(item, await this.invokeActionHandler(item, direction));
+                }
+                else {
+                    await apply.call(this, item);
+                }
+            }
+        }
+        finally {
+            this.endBatch(batchId);
+            this.suppressUndoStack = false;
+        }
+        return items.map((x) => (isAction(x) ? swaps.get(x) ?? x : x));
+    }
+    partition(items) {
+        const txs = [];
+        const actions = [];
+        for (const x of items) {
+            if (isAction(x)) {
+                actions.push(x);
+            }
+            else {
+                txs.push(x);
+            }
+        }
+        return { txs, actions };
+    }
+    async undo() {
+        const entry = this.undoStack.pop();
+        if (entry == null) {
+            return null;
+        }
+        const replayed = await this.processEntry(entry, "undo");
+        this.redoStack.push(this.wrapEntry(entry, replayed));
+        this.notify();
+        return this.partition(this.itemsOf(entry));
+    }
+    async redo() {
+        const entry = this.redoStack.pop();
+        if (entry == null) {
+            return null;
+        }
+        const replayed = await this.processEntry(entry, "redo");
+        this.undoStack.push(this.wrapEntry(entry, replayed));
+        this.notify();
+        return this.partition(this.itemsOf(entry));
+    }
+    // ── Reconnection ──────────────────────────────────────────────────────────
+    async resendCached() {
+        const cached = await this.database.getCachedTransactions();
+        if (cached.length === 0) {
+            return 0;
+        }
+        // Build a signature set for transactions already in-flight, pending, or awaiting sync.
+        // If a transaction is currently being sent (executing) or already queued (pending),
+        // re-enqueueing from IDB would send a duplicate to the server.
+        const inFlight = new Set();
+        for (const tx of [
+            ...this.pending,
+            ...this.executing,
+            ...this.awaitingSync,
+        ]) {
+            inFlight.add(`${tx.action}:${tx.modelName}:${tx.modelId}`);
+        }
+        // Walk the cached records once. For each:
+        //   - syncIdNeededForCompletion present + matching SSE delta already
+        //     persisted → drop (server ack'd, delta arrived).
+        //   - syncIdNeededForCompletion present + no matching delta yet →
+        //     restore to awaitingSync (do NOT resend; just wait for the delta).
+        //   - No syncId set → it's still pending. If the target model has been
+        //     deleted/archived since the tx was queued, drop it and emit a
+        //     transactionDiscarded error. Otherwise rebuild and re-enqueue.
+        const dropKeys = [];
+        let count = 0;
+        for (const entry of cached) {
+            const d = entry.data;
+            const idbKey = entry.idbKey;
+            const inFlightKey = `${d.action}:${d.modelName}:${d.modelId}`;
+            if (d.syncIdNeededForCompletion != null) {
+                if (await this.database.hasSyncAction(d.syncIdNeededForCompletion)) {
+                    dropKeys.push(idbKey);
+                    continue;
+                }
+                if (inFlight.has(inFlightKey)) {
+                    dropKeys.push(idbKey);
+                    continue;
+                }
+                const tx = this.rebuildTransaction(d);
+                if (tx == null) {
+                    dropKeys.push(idbKey);
+                    continue;
+                }
+                tx.idbKey = idbKey;
+                tx.markCompleted(d.syncIdNeededForCompletion);
+                this.awaitingSync.push(tx);
+                continue;
+            }
+            if (inFlight.has(inFlightKey)) {
+                dropKeys.push(idbKey);
+                continue;
+            }
+            // Pending tx — check whether the target was deleted/archived in our absence.
+            if (d.action === "U" || d.action === "D" || d.action === "A") {
+                const actions = await this.database.findSyncActionsForModel(d.modelName, d.modelId);
+                if (actions.some((a) => a.action === "D" || a.action === "A")) {
+                    dropKeys.push(idbKey);
+                    this.reportError?.(new Error(`Discarded persisted ${d.action} for ${d.modelName} ${d.modelId}: target was deleted`), {
+                        kind: "transactionDiscarded",
+                        modelName: d.modelName,
+                        modelId: d.modelId,
+                        action: d.action,
+                        reason: "target-deleted",
+                    });
+                    continue;
+                }
+            }
+            const tx = this.rebuildTransaction(d);
+            if (tx == null) {
+                dropKeys.push(idbKey);
+                continue;
+            }
+            tx.idbKey = idbKey;
+            this.pending.push(tx);
+            count++;
+        }
+        if (dropKeys.length > 0) {
+            await this.database.deleteCachedTransactions(dropKeys);
+        }
+        if (count > 0) {
+            this.scheduleFlush();
+        }
+        return count;
+    }
+    rebuildTransaction(d) {
+        let tx;
+        switch (d.action) {
+            case "U":
+                if (d.changes == null) {
+                    return null;
+                }
+                tx = new UpdateTransaction(d.modelId, d.modelName, d.changes);
+                break;
+            case "I":
+                if (d.data == null) {
+                    return null;
+                }
+                tx = new CreateTransaction(d.modelId, d.modelName, d.data);
+                break;
+            case "D":
+                if (d.snapshot == null) {
+                    return null;
+                }
+                tx = new DeleteTransaction(d.modelId, d.modelName, d.snapshot);
+                break;
+            case "A":
+                if (d.snapshot == null) {
+                    return null;
+                }
+                tx = new ArchiveTransaction(d.modelId, d.modelName, d.snapshot);
+                break;
+            default:
+                return null;
+        }
+        tx.batchId = d.batchId ?? null;
+        return tx;
+    }
+    destroy() {
+        if (this.flushTimer != null) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+        this.listeners.clear();
+    }
+    // ── Introspection ─────────────────────────────────────────────────────────
+    get pendingCount() {
+        return this.pending.length;
+    }
+    get executingCount() {
+        return this.executing.length;
+    }
+    get awaitingSyncCount() {
+        return this.awaitingSync.length;
+    }
+    get undoDepth() {
+        return this.undoStack.length;
+    }
+    get redoDepth() {
+        return this.redoStack.length;
+    }
+}

package/dist/core/decorators.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Decorators for defining models and their properties.
+ *
+ * Usage looks like:
+ *
+ *   @ClientModel({ loadStrategy: LoadStrategy.Eager })
+ *   class Issue extends BaseModel {
+ *     @Property() title = "";
+ *     @Reference("User", { nullable: true }) assignee: any;
+ *     @Action moveToTeam(id: string) { ... }
+ *     @Computed get identifier() { ... }
+ *   }
+ *
+ * Each decorator registers metadata in the ModelRegistry at class-definition
+ * time. The engine reads that metadata later for serialization, hydration,
+ * observability, indexing, and reference resolution.
+ */
+import { LoadStrategy } from "./types";
+export declare function ClientModel(opts?: {
+    /**
+     * The registry name — what `ModelMeta.name` becomes, what
+     * cross-references resolve against, and the typed handle for
+     * `useRecord(Model, …)`. Defaults to `ctor.name`, which minifiers
+     * mangle in production: pass an explicit `name` (or configure your
+     * bundler's `keep_classnames`) for any shipped build.
+     */
+    name?: string;
+    loadStrategy?: LoadStrategy;
+    usedForPartialIndexes?: boolean;
+    schemaVersion?: number;
+}): <T extends new (...args: any[]) => any>(ctor: T) => T;
+export declare function Property(opts?: {
+    indexed?: boolean;
+    serializer?: (v: any) => any;
+    deserializer?: (v: any) => any;
+}): (target: any, key: string) => void;
+export declare function EphemeralProperty(): (target: any, key: string) => void;
+interface ReferenceOpts {
+    nullable?: boolean;
+    idField?: string;
+    onDelete?: "cascade" | "nullify" | "restrict";
+}
+export declare function Reference(referenceTo: string, opts?: ReferenceOpts): (target: any, key: string) => void;
+export declare function LazyReference(referenceTo: string, opts?: ReferenceOpts): (target: any, key: string) => void;
+interface ReferenceCollectionOpts {
+    inverseOf?: string;
+    /**
+     * Names of additional FK fields on the parent model that should each become
+     * an extra query when the collection loads. The loader unions the results.
+     * Use for multi-axis lazy queries (e.g. "all comments for this issue PLUS
+     * everything in the sync groups the user belongs to").
+     */
+    coveringIndexes?: string[];
+}
+export declare function ReferenceCollection(referenceTo: string, opts?: ReferenceCollectionOpts): (target: any, key: string) => void;
+export declare function LazyReferenceCollection(referenceTo: string, opts?: ReferenceCollectionOpts): (target: any, key: string) => void;
+export declare function BackReference(referenceTo: string, inverseOf: string): (target: any, key: string) => void;
+export declare function ReferenceArray(referenceTo: string): (target: any, key: string) => void;
+interface OwnedCollectionOpts {
+    idsField: string;
+}
+export declare function OwnedCollection(referenceTo: string, opts: OwnedCollectionOpts): (target: any, key: string) => void;
+export declare function LazyOwnedCollection(referenceTo: string, opts: OwnedCollectionOpts): (target: any, key: string) => void;
+export declare function Action(target: any, key: string, _d: PropertyDescriptor): void;
+export declare function Computed(target: any, key: string, _d: PropertyDescriptor): void;
+export {};