@backloghq/opslog 0.3.0 → 0.4.1

package/dist/delta.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Delta encoding for operations.
+ * Instead of storing the full previous record, store only the diff.
+ *
+ * Uses a simplified JSON Patch-like format:
+ * - Only tracks changed/added/removed top-level keys
+ * - prev becomes a patch object: { $set: {...}, $unset: [...] }
+ */
+export interface DeltaPatch {
+    /** Fields that were changed or added (old values). */
+    $set?: Record<string, unknown>;
+    /** Fields that were removed. */
+    $unset?: string[];
+}
+/**
+ * Create a delta patch from an old record to a new record.
+ * The patch, when applied to the new record, produces the old record.
+ * This is the "reverse patch" — stored as `prev` so undo can apply it.
+ */
+export declare function createDelta(oldRecord: Record<string, unknown> | null, newRecord: Record<string, unknown>): DeltaPatch | null;
+/**
+ * Apply a delta patch to a record to produce the previous version.
+ * Used during undo: apply the reverse patch to current record → get old record.
+ */
+export declare function applyDelta(record: Record<string, unknown>, patch: DeltaPatch): Record<string, unknown>;
+/**
+ * Check if a delta patch is smaller than the full record.
+ * Used to decide whether to use delta or full encoding.
+ */
+export declare function isDeltaSmaller(patch: DeltaPatch | null, fullRecord: Record<string, unknown> | null): boolean;

package/dist/delta.js

@@ -0,0 +1,75 @@
+/**
+ * Delta encoding for operations.
+ * Instead of storing the full previous record, store only the diff.
+ *
+ * Uses a simplified JSON Patch-like format:
+ * - Only tracks changed/added/removed top-level keys
+ * - prev becomes a patch object: { $set: {...}, $unset: [...] }
+ */
+/**
+ * Create a delta patch from an old record to a new record.
+ * The patch, when applied to the new record, produces the old record.
+ * This is the "reverse patch" — stored as `prev` so undo can apply it.
+ */
+export function createDelta(oldRecord, newRecord) {
+    if (oldRecord === null)
+        return null; // Create operation — no previous
+    const patch = {};
+    const $set = {};
+    const $unset = [];
+    // Fields in old that differ from new (changed or removed in new)
+    for (const [key, oldVal] of Object.entries(oldRecord)) {
+        if (!(key in newRecord)) {
+            // Field was removed in new → to restore old, we need to $set it
+            $set[key] = oldVal;
+        }
+        else if (JSON.stringify(oldVal) !== JSON.stringify(newRecord[key])) {
+            // Field changed → store old value
+            $set[key] = oldVal;
+        }
+    }
+    // Fields in new that weren't in old (added in new)
+    for (const key of Object.keys(newRecord)) {
+        if (!(key in oldRecord)) {
+            // Field was added in new → to restore old, we need to $unset it
+            $unset.push(key);
+        }
+    }
+    if (Object.keys($set).length > 0)
+        patch.$set = $set;
+    if ($unset.length > 0)
+        patch.$unset = $unset;
+    // If no changes, return empty patch
+    if (!patch.$set && !patch.$unset)
+        return null;
+    return patch;
+}
+/**
+ * Apply a delta patch to a record to produce the previous version.
+ * Used during undo: apply the reverse patch to current record → get old record.
+ */
+export function applyDelta(record, patch) {
+    const result = { ...record };
+    if (patch.$set) {
+        for (const [key, val] of Object.entries(patch.$set)) {
+            result[key] = val;
+        }
+    }
+    if (patch.$unset) {
+        for (const key of patch.$unset) {
+            delete result[key];
+        }
+    }
+    return result;
+}
+/**
+ * Check if a delta patch is smaller than the full record.
+ * Used to decide whether to use delta or full encoding.
+ */
+export function isDeltaSmaller(patch, fullRecord) {
+    if (patch === null || fullRecord === null)
+        return false;
+    const patchSize = JSON.stringify(patch).length;
+    const fullSize = JSON.stringify(fullRecord).length;
+    return patchSize < fullSize;
+}

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export { Store } from "./store.js";
 export { FsBackend } from "./backend.js";
 export { LamportClock } from "./clock.js";
+export { createDelta, applyDelta, isDeltaSmaller } from "./delta.js";
+export type { DeltaPatch } from "./delta.js";
 export { acquireLock, releaseLock } from "./lock.js";
 export { validateOp, validateManifest, validateSnapshot, validateArchiveSegment, } from "./validate.js";
 export type { Operation, Snapshot, Manifest, ManifestStats, ArchiveSegment, StoreOptions, StoreStats, StorageBackend, LockHandle, } from "./types.js";

package/dist/index.js

@@ -1,5 +1,6 @@
 export { Store } from "./store.js";
 export { FsBackend } from "./backend.js";
 export { LamportClock } from "./clock.js";
+export { createDelta, applyDelta, isDeltaSmaller } from "./delta.js";
 export { acquireLock, releaseLock } from "./lock.js";
 export { validateOp, validateManifest, validateSnapshot, validateArchiveSegment, } from "./validate.js";

package/dist/store.d.ts

@@ -47,11 +47,30 @@ export declare class Store<T = Record<string, unknown>> {
     loadArchive(segment: string): Promise<Map<string, T>>;
     stats(): StoreStats;
     /**
-     * Reload state from the backend (multi-writer mode).
-     * Re-reads the manifest, snapshot, and all agent WAL files.
-     * Use this to pick up writes from other agents.
+     * Reload state from the backend.
+     * In multi-writer mode: re-reads manifest, snapshot, and all agent WAL files.
+     * In single-writer/readOnly mode: re-reads the active ops file for new entries.
+     * Use this to pick up writes from other agents or processes.
      */
     refresh(): Promise<void>;
+    private watchTimer;
+    private watchCallback;
+    /**
+     * Tail the WAL for new operations.
+     * In single-writer/readOnly: re-reads the active ops file for new entries.
+     * In multi-writer: re-reads ALL agent WAL files from the manifest.
+     * Returns the newly applied operations.
+     */
+    tail(): Promise<Operation<T>[]>;
+    /**
+     * Watch for new operations on an interval.
+     * Calls the callback with new operations whenever they appear.
+     * @param callback Called with new operations
+     * @param intervalMs Polling interval in milliseconds (default: 1000)
+     */
+    watch(callback: (ops: Operation<T>[]) => void, intervalMs?: number): void;
+    /** Stop watching for new operations. */
+    unwatch(): void;
     private makeOp;
     private _set;
     private _setSync;

package/dist/store.js

@@ -1,6 +1,7 @@
 import { createDefaultManifest } from "./manifest.js";
 import { FsBackend } from "./backend.js";
 import { LamportClock } from "./clock.js";
+import { createDelta, applyDelta, isDeltaSmaller } from "./delta.js";
 export class Store {
     dir = "";
     records = new Map();
@@ -181,6 +182,7 @@ export class Store {
     }
     async close() {
         this.ensureOpen();
+        this.unwatch();
         if (!this.coreOpts.readOnly &&
             this.coreOpts.checkpointOnClose &&
             this.ops.length > 0) {
@@ -297,16 +299,81 @@ export class Store {
         };
     }
     /**
-     * Reload state from the backend (multi-writer mode).
-     * Re-reads the manifest, snapshot, and all agent WAL files.
-     * Use this to pick up writes from other agents.
+     * Reload state from the backend.
+     * In multi-writer mode: re-reads manifest, snapshot, and all agent WAL files.
+     * In single-writer/readOnly mode: re-reads the active ops file for new entries.
+     * Use this to pick up writes from other agents or processes.
      */
     async refresh() {
         this.ensureOpen();
-        if (!this.isMultiWriter()) {
-            throw new Error("refresh() is only available in multi-writer mode");
+        if (this.isMultiWriter()) {
+            return this.serialize(() => this._refresh());
+        }
+        // Single-writer / readOnly: just tail the active ops file
+        await this.tail();
+    }
+    // --- WAL tailing ---
+    watchTimer = null;
+    watchCallback = null;
+    /**
+     * Tail the WAL for new operations.
+     * In single-writer/readOnly: re-reads the active ops file for new entries.
+     * In multi-writer: re-reads ALL agent WAL files from the manifest.
+     * Returns the newly applied operations.
+     */
+    async tail() {
+        this.ensureOpen();
+        const prevCount = this.ops.length;
+        if (this.isMultiWriter()) {
+            // Multi-writer: full refresh to pick up all agents' writes
+            await this.serialize(() => this._refresh());
+            // Return the difference
+            if (this.ops.length > prevCount) {
+                return this.ops.slice(prevCount);
+            }
+            return [];
+        }
+        // Single-writer / readOnly: just re-read our ops file
+        const allOps = (await this.backend.readOps(this.activeOpsPath));
+        if (allOps.length <= prevCount)
+            return [];
+        const newOps = allOps.slice(prevCount);
+        for (const op of newOps) {
+            this.applyOp(op);
+        }
+        this.ops.push(...newOps);
+        return newOps;
+    }
+    /**
+     * Watch for new operations on an interval.
+     * Calls the callback with new operations whenever they appear.
+     * @param callback Called with new operations
+     * @param intervalMs Polling interval in milliseconds (default: 1000)
+     */
+    watch(callback, intervalMs = 1000) {
+        this.ensureOpen();
+        if (this.watchTimer)
+            this.unwatch();
+        this.watchCallback = callback;
+        this.watchTimer = setInterval(async () => {
+            try {
+                const newOps = await this.tail();
+                if (newOps.length > 0 && this.watchCallback) {
+                    this.watchCallback(newOps);
+                }
+            }
+            catch {
+                // Silently ignore tail errors during watch
+            }
+        }, intervalMs);
+    }
+    /** Stop watching for new operations. */
+    unwatch() {
+        if (this.watchTimer) {
+            clearInterval(this.watchTimer);
+            this.watchTimer = null;
         }
-        return this.serialize(() => this._refresh());
+        this.watchCallback = null;
     }
     // --- Private mutation implementations ---
     makeOp(type, id, data, prev) {
@@ -322,6 +389,14 @@ export class Store {
             op.agent = this.agentId;
             op.clock = this.clock.tick();
         }
+        // Try delta encoding for updates (not creates or deletes)
+        if (type === "set" && prev !== null && data !== undefined) {
+            const delta = createDelta(prev, data);
+            if (delta && isDeltaSmaller(delta, prev)) {
+                op.prev = delta;
+                op.encoding = "delta";
+            }
+        }
         return op;
     }
     async _set(id, value) {
@@ -560,12 +635,23 @@ export class Store {
     }
     reverseOp(op) {
         if (op.prev === null) {
+            // Was a create — reverse by deleting
             this.records.delete(op.id);
         }
+        else if (op.encoding === "delta") {
+            // Delta-encoded: apply the reverse patch to the current record
+            const current = this.records.get(op.id);
+            if (current) {
+                const restored = applyDelta(current, op.prev);
+                this.records.set(op.id, restored);
+            }
+        }
         else if (op.op === "delete") {
+            // Was a delete — reverse by restoring full prev
             this.records.set(op.id, op.prev);
         }
         else {
+            // Was an update — reverse by restoring full prev
             this.records.set(op.id, op.prev);
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backloghq/opslog",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Embedded event-sourced document store. Append-only operation log with immutable snapshots, zero native dependencies.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",