zerodrift 1.0.0

package/dist/core/Transaction.js

@@ -0,0 +1,147 @@
+/**
+ * Transaction types with batchId for multi-model grouped undo and rebase support.
+ *
+ * batchId groups transactions from one user action (e.g. moveIssueToTeam
+ * updates Issue.teamId AND Team.issueCount). undo() reverts the entire batch.
+ *
+ * Rebasing (UpdateTransaction): when a delta packet conflicts with our local
+ * change, the server value becomes our new baseline and our value is re-applied.
+ */
+import { TransactionState } from "./types";
+export class BaseTransaction {
+    constructor(modelId, modelName) {
+        this.id = crypto.randomUUID();
+        this.timestamp = Date.now();
+        this.state = TransactionState.Pending;
+        this.batchId = null;
+        this.syncIdNeededForCompletion = null;
+        this.idbKey = null;
+        this.modelId = modelId;
+        this.modelName = modelName;
+    }
+    markCompleted(syncId) {
+        this.syncIdNeededForCompletion = syncId;
+        this.state = TransactionState.CompletedButUnsynced;
+    }
+    isSyncedBy(syncId) {
+        return (this.syncIdNeededForCompletion !== null &&
+            syncId >= this.syncIdNeededForCompletion);
+    }
+}
+export class UpdateTransaction extends BaseTransaction {
+    constructor(modelId, modelName, changes) {
+        super(modelId, modelName);
+        this.action = "U";
+        this.changes = new Map(Object.entries(changes));
+    }
+    revert(model) {
+        for (const [prop, { oldValue }] of this.changes) {
+            model.setQuiet(prop, oldValue);
+        }
+    }
+    /**
+     * Last-writer-wins rebase: update baseline to server value, re-apply ours.
+     * Only rebases fields where the server value differs from our intended newValue —
+     * an echo of our own change (serverValue === newValue) must not overwrite oldValue,
+     * as that would corrupt the undo baseline.
+     */
+    rebase(model, serverData) {
+        for (const [prop, serverValue] of Object.entries(serverData)) {
+            const change = this.changes.get(prop);
+            if (change != null && serverValue !== change.newValue) {
+                change.oldValue = serverValue;
+                // Dynamic property assignment on BaseModel — no better type for runtime field access
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                model[prop] = change.newValue;
+            }
+        }
+    }
+    /** Returns true only when the server data has a field we're changing AND the
+     *  server's value differs from our intended newValue (i.e. a real conflict,
+     *  not just an echo of our own change). */
+    conflictsWith(data) {
+        for (const [k, serverValue] of Object.entries(data)) {
+            const change = this.changes.get(k);
+            if (change != null && serverValue !== change.newValue) {
+                return true;
+            }
+        }
+        return false;
+    }
+    serialize() {
+        return {
+            id: this.id,
+            action: this.action,
+            batchId: this.batchId,
+            modelId: this.modelId,
+            modelName: this.modelName,
+            timestamp: this.timestamp,
+            changes: Object.fromEntries([...this.changes.entries()]),
+        };
+    }
+}
+export class CreateTransaction extends BaseTransaction {
+    constructor(modelId, modelName, data) {
+        super(modelId, modelName);
+        this.action = "I";
+        this.data = data;
+    }
+    revert() {
+        /* pool removal handled by queue */
+    }
+    serialize() {
+        return {
+            id: this.id,
+            action: this.action,
+            batchId: this.batchId,
+            modelId: this.modelId,
+            modelName: this.modelName,
+            timestamp: this.timestamp,
+            data: this.data,
+        };
+    }
+}
+export class DeleteTransaction extends BaseTransaction {
+    constructor(modelId, modelName, snapshot) {
+        super(modelId, modelName);
+        this.action = "D";
+        this.snapshot = snapshot;
+    }
+    revert(model) {
+        model.hydrate(this.snapshot);
+        model.makeModelObservable();
+    }
+    serialize() {
+        return {
+            id: this.id,
+            action: this.action,
+            batchId: this.batchId,
+            modelId: this.modelId,
+            modelName: this.modelName,
+            timestamp: this.timestamp,
+            snapshot: this.snapshot,
+        };
+    }
+}
+export class ArchiveTransaction extends BaseTransaction {
+    constructor(modelId, modelName, snapshot) {
+        super(modelId, modelName);
+        this.action = "A";
+        this.snapshot = snapshot;
+    }
+    revert(model) {
+        model.hydrate(this.snapshot);
+        model.makeModelObservable();
+    }
+    serialize() {
+        return {
+            id: this.id,
+            action: this.action,
+            batchId: this.batchId,
+            modelId: this.modelId,
+            modelName: this.modelName,
+            timestamp: this.timestamp,
+            snapshot: this.snapshot,
+        };
+    }
+}

package/dist/core/TransactionQueue.d.ts

@@ -0,0 +1,110 @@
+/**
+ * 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 type { StorageAdapter } from "./Database";
+import { ObjectPool } from "./ObjectPool";
+import { type EngineErrorContext } from "./types";
+import { BaseTransaction, UpdateTransaction, type UndoableAction } from "./Transaction";
+import { type PropertyChange } from "./types";
+import type { BaseModel } from "./BaseModel";
+export interface BatchResponse {
+    success: boolean;
+    lastSyncId: number;
+}
+export type TransactionSender = (batch: ReturnType<BaseTransaction["serialize"]>[]) => Promise<BatchResponse>;
+export type UndoPhase = "undo" | "redo";
+export interface UndoResult {
+    txs: BaseTransaction[];
+    actions: UndoableAction[];
+}
+/** Handlers the consumer supplies via `StoreManagerConfig.undoableActions`.
+ *  Each handler talks to the consumer's backend change-log API and returns the
+ *  compensating action so the engine can place it on the opposite stack.
+ *  Returning `void` reuses the original entry — fine when the same
+ *  `changeLogId` is replayable in either direction. */
+export interface UndoableActionHandlers {
+    undo: (action: UndoableAction) => Promise<UndoableAction | void>;
+    redo?: (action: UndoableAction) => Promise<UndoableAction | void>;
+}
+type Listener = () => void;
+export declare class TransactionQueue {
+    private database;
+    private pool;
+    private sender;
+    private pending;
+    private executing;
+    private awaitingSync;
+    private undoStack;
+    private redoStack;
+    private activeBatchId;
+    private activeBatchEntries;
+    private actionHandlers;
+    private suppressUndoStack;
+    private flushTimer;
+    private flushDelay;
+    private undoLimit;
+    private listeners;
+    private reportError;
+    constructor(database: StorageAdapter, pool: ObjectPool, undoLimit?: number);
+    setErrorReporter(reporter: (err: Error, context: EngineErrorContext) => void): void;
+    setSender(sender: TransactionSender): void;
+    setActionHandlers(handlers: UndoableActionHandlers): void;
+    subscribe(listener: Listener): () => void;
+    private notify;
+    beginBatch(): string;
+    endBatch(batchId: string): void;
+    get hasActiveBatch(): boolean;
+    enqueueUpdate(modelId: string, modelName: string, changes: Record<string, PropertyChange>): Promise<UpdateTransaction>;
+    enqueueCreate(modelId: string, modelName: string, data: Record<string, unknown>): Promise<void>;
+    enqueueDelete(model: BaseModel): Promise<void>;
+    /** 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: UndoableAction): void;
+    enqueueArchive(model: BaseModel): Promise<void>;
+    private enqueue;
+    private scheduleFlush;
+    private flush;
+    resolveBySync(receivedSyncId: number): BaseTransaction[];
+    rebaseAll(modelId: string, modelName: string, serverData: Record<string, unknown>): void;
+    private revertOne;
+    private itemsOf;
+    /** Build the inverse-stack entry from a list of replaced items. Single-item
+     *  entries collapse to `single`, otherwise reuse the original `batchId`. */
+    private wrapEntry;
+    /** 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. */
+    private invokeActionHandler;
+    /** Reverse a single transaction and enqueue the inverse server call. */
+    private revertTx;
+    /** Re-apply a single transaction and enqueue the forward server call. */
+    private replayTx;
+    /** 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. */
+    private processEntry;
+    private partition;
+    undo(): Promise<UndoResult | null>;
+    redo(): Promise<UndoResult | null>;
+    resendCached(): Promise<number>;
+    private rebuildTransaction;
+    destroy(): void;
+    get pendingCount(): number;
+    get executingCount(): number;
+    get awaitingSyncCount(): number;
+    get undoDepth(): number;
+    get redoDepth(): number;
+}
+export {};