@convex-localfirst/core 0.1.0

package/dist/view.js

@@ -0,0 +1,74 @@
+import { compareOperations } from "./ordering.js";
+import { rebaseAndReplay } from "./rebase.js";
+/** Ops whose effect is not yet folded into canonical, so they must be replayed. */
+const REPLAYED_STATUSES = new Set(["pending", "pushing", "acked"]);
+/**
+ * Derive the live view for one table (Invariant I1): canonical snapshot with the
+ * deterministically-ordered pending operations replayed on top. Shared by every
+ * LocalStore implementation so the rebase logic lives in exactly one place.
+ */
+export function deriveView(table, canonicalRows, operations) {
+    const ops = operations.filter((operation) => operation.table === table);
+    const replayed = ops.filter((operation) => REPLAYED_STATUSES.has(operation.status)).sort(compareOperations);
+    const { rows, conflicts } = rebaseAndReplay({
+        canonicalRows,
+        serverChanges: [],
+        pendingOperations: replayed
+    });
+    const byId = new Map(rows.map((row) => [row._id, row]));
+    // Replay failures (e.g. patch over a missing row) surface as row conflicts.
+    for (const conflict of conflicts) {
+        const op = ops.find((operation) => operation.opId === conflict.opId);
+        const row = op ? byId.get(op.id) : undefined;
+        if (row) {
+            row._conflict = { kind: "mergeFailed", message: conflict.message, opId: conflict.opId };
+        }
+    }
+    // Server rejections surface on the (now reverted) canonical row. A rejected
+    // INSERT has no canonical row to annotate — the optimistic row correctly
+    // reverts (the insert never happened); the rejection is still observable via
+    // the op's "rejected" status and status.lastError. ponytail: surfacing a
+    // dismissable "ghost" row for a rejected insert is a deferred UX enhancement.
+    for (const op of ops) {
+        if (op.status !== "rejected") {
+            continue;
+        }
+        const row = byId.get(op.id);
+        if (row) {
+            row._conflict = { kind: "serverRejected", message: op.error ?? "Server rejected the operation", opId: op.opId };
+        }
+    }
+    return Array.from(byId.values());
+}
+/**
+ * Compute the next canonical row for a server change, or "stale" if the change
+ * must be ignored because its version does not advance the row (Invariant I5).
+ */
+export function nextCanonicalRow(current, change) {
+    if (current && typeof current._version === "number" && change.version <= current._version) {
+        return "stale";
+    }
+    if (change.kind === "delete") {
+        const base = current ?? { _id: change.id, _table: change.table };
+        return { ...base, _id: change.id, _table: change.table, _deleted: true, _version: change.version };
+    }
+    if (change.kind === "patch") {
+        const base = current ?? { _id: change.id, _table: change.table };
+        return {
+            ...base,
+            ...(change.patch ?? {}),
+            _id: change.id,
+            _table: change.table,
+            _version: change.version,
+            _deleted: false
+        };
+    }
+    // insert | replace: the canonical row becomes exactly the server value.
+    return {
+        ...(change.value ?? {}),
+        _id: change.id,
+        _table: change.table,
+        _version: change.version,
+        _deleted: false
+    };
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@convex-localfirst/core",
+  "version": "0.1.0",
+  "description": "Local-first engine, store contract, and sync protocol for Convex — optimistic writes, offline cache, rebase/replay.",
+  "license": "MIT",
+  "keywords": [
+    "convex",
+    "local-first",
+    "offline",
+    "sync",
+    "optimistic"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./internal": {
+      "types": "./dist/internal.d.ts",
+      "import": "./dist/internal.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "fake-indexeddb": "^6.2.5",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json --noEmit false --emitDeclarationOnly false",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}