state-sync-log 0.9.0

package/src/draft.ts

@@ -0,0 +1,288 @@
+import { failure } from "./error"
+import type { JSONObject, JSONRecord, JSONValue, Path } from "./json"
+import type { Op, ValidateFn } from "./operations"
+import { TxRecord } from "./TxRecord"
+import { deepEqual, isObject } from "./utils"
+
+/**
+ * A draft context for copy-on-write immutable updates.
+ *
+ * This provides Immer/Mutative-like semantics without the proxy overhead:
+ * - The original base state is never mutated
+ * - Objects are cloned lazily on first mutation (copy-on-write)
+ * - Once an object is cloned ("owned"), it can be mutated directly
+ * - If no changes are made, the original reference is preserved (structural sharing)
+ */
+export interface DraftContext<T extends JSONObject> {
+  /** The current root (may be the original base or a cloned version) */
+  root: T
+  /** The original base state (never mutated) */
+  base: T
+  /** Set of objects that have been cloned and are safe to mutate */
+  ownedObjects: WeakSet<object>
+  /** Optimization: fast check if root is already owned */
+  isRootOwned: boolean
+}
+
+/**
+ * Creates a new draft context from a base state.
+ * The base state will never be mutated.
+ */
+export function createDraft<T extends JSONObject>(base: T): DraftContext<T> {
+  return {
+    root: base,
+    base,
+    ownedObjects: new Set(),
+    isRootOwned: false,
+  }
+}
+
+/**
+ * Checks if the draft was modified (root !== base).
+ */
+export function isDraftModified<T extends JSONObject>(ctx: DraftContext<T>): boolean {
+  return ctx.root !== ctx.base
+}
+
+function shallowClone<T extends object>(obj: T): T {
+  if (Array.isArray(obj)) {
+    return obj.slice() as unknown as T
+  }
+  const clone = {} as T
+  const keys = Object.keys(obj)
+  for (let i = 0; i < keys.length; i++) {
+    const key = keys[i]
+    ;(clone as any)[key] = (obj as any)[key]
+  }
+  return clone
+}
+
+/**
+ * Ensures an object is owned (cloned if necessary) and returns the owned version.
+ * Also updates the parent to point to the cloned child.
+ */
+function ensureOwned<T extends JSONObject>(
+  ctx: DraftContext<T>,
+  parent: JSONObject,
+  key: string | number,
+  child: JSONRecord | JSONValue[]
+): JSONRecord | JSONValue[] {
+  if (ctx.ownedObjects.has(child)) {
+    return child
+  }
+  const cloned = shallowClone(child)
+  ;(parent as any)[key] = cloned
+  ctx.ownedObjects.add(cloned)
+  return cloned
+}
+
+/**
+ * Ensures all objects along the path are owned (cloned if necessary).
+ * Returns the container at the end of the path.
+ * Throws if the path is invalid.
+ */
+function ensureOwnedPath<T extends JSONObject>(
+  ctx: DraftContext<T>,
+  path: Path
+): JSONRecord | JSONValue[] {
+  // Ensure root is owned first
+  if (!ctx.isRootOwned) {
+    ctx.root = shallowClone(ctx.root as unknown as object) as T
+    ctx.ownedObjects.add(ctx.root)
+    ctx.isRootOwned = true
+  }
+
+  if (path.length === 0) {
+    return ctx.root
+  }
+
+  let current: JSONRecord | JSONValue[] = ctx.root
+
+  for (let i = 0; i < path.length; i++) {
+    const segment = path[i]
+    const isArrayIndex = typeof segment === "number"
+
+    // Validate container type
+    if (isArrayIndex) {
+      if (!Array.isArray(current)) {
+        failure(`Expected array at path segment ${segment}`)
+      }
+      if (segment < 0 || segment >= current.length) {
+        failure(`Index ${segment} out of bounds`)
+      }
+    } else {
+      if (!isObject(current) || Array.isArray(current)) {
+        failure(`Expected object at path segment "${segment}"`)
+      }
+      if (!(segment in current)) {
+        failure(`Property "${segment}" does not exist`)
+      }
+    }
+
+    const child: JSONValue = (current as any)[segment]
+
+    // Validate child is traversable
+    if (child === null || typeof child !== "object") {
+      failure(`Cannot traverse through primitive at path segment ${segment}`)
+    }
+
+    // Ensure child is owned and continue
+    current = ensureOwned(ctx, current, segment, child as JSONRecord | JSONValue[])
+  }
+
+  return current
+}
+
+/**
+ * Applies a single "set" operation to the draft with copy-on-write.
+ */
+export function draftSet<T extends JSONObject>(
+  ctx: DraftContext<T>,
+  path: Path,
+  key: string,
+  value: JSONValue
+): void {
+  const container = ensureOwnedPath(ctx, path)
+  if (Array.isArray(container)) {
+    failure("set requires object container")
+  }
+  ;(container as JSONRecord)[key] = value
+}
+
+/**
+ * Applies a single "delete" operation to the draft with copy-on-write.
+ */
+export function draftDelete<T extends JSONObject>(
+  ctx: DraftContext<T>,
+  path: Path,
+  key: string
+): void {
+  const container = ensureOwnedPath(ctx, path)
+  if (Array.isArray(container)) {
+    failure("delete requires object container")
+  }
+  delete (container as JSONRecord)[key]
+}
+
+/**
+ * Applies a single "splice" operation to the draft with copy-on-write.
+ */
+export function draftSplice<T extends JSONObject>(
+  ctx: DraftContext<T>,
+  path: Path,
+  index: number,
+  deleteCount: number,
+  inserts: readonly JSONValue[]
+): void {
+  const container = ensureOwnedPath(ctx, path)
+  if (!Array.isArray(container)) {
+    failure("splice requires array container")
+  }
+  const safeIndex = Math.min(index, container.length)
+  if (inserts.length === 0) {
+    container.splice(safeIndex, deleteCount)
+  } else if (inserts.length === 1) {
+    container.splice(safeIndex, deleteCount, inserts[0])
+  } else {
+    container.splice(safeIndex, deleteCount, ...inserts)
+  }
+}
+
+/**
+ * Applies a single "addToSet" operation to the draft with copy-on-write.
+ */
+export function draftAddToSet<T extends JSONObject>(
+  ctx: DraftContext<T>,
+  path: Path,
+  value: JSONValue
+): void {
+  const container = ensureOwnedPath(ctx, path)
+  if (!Array.isArray(container)) {
+    failure("addToSet requires array container")
+  }
+  if (!container.some((item) => deepEqual(item, value))) {
+    container.push(value)
+  }
+}
+
+/**
+ * Applies a single "deleteFromSet" operation to the draft with copy-on-write.
+ */
+export function draftDeleteFromSet<T extends JSONObject>(
+  ctx: DraftContext<T>,
+  path: Path,
+  value: JSONValue
+): void {
+  const container = ensureOwnedPath(ctx, path)
+  if (!Array.isArray(container)) {
+    failure("deleteFromSet requires array container")
+  }
+  // Remove all matching items (iterate backwards to avoid index shifting)
+  for (let i = container.length - 1; i >= 0; i--) {
+    if (deepEqual(container[i], value)) {
+      container.splice(i, 1)
+    }
+  }
+}
+
+/**
+ * Applies a single operation to the draft with copy-on-write.
+ */
+export function applyOpToDraft<T extends JSONObject>(ctx: DraftContext<T>, op: Op): void {
+  switch (op.kind) {
+    case "set":
+      draftSet(ctx, op.path, op.key, op.value)
+      break
+    case "delete":
+      draftDelete(ctx, op.path, op.key)
+      break
+    case "splice":
+      draftSplice(ctx, op.path, op.index, op.deleteCount, op.inserts)
+      break
+    case "addToSet":
+      draftAddToSet(ctx, op.path, op.value)
+      break
+    case "deleteFromSet":
+      draftDeleteFromSet(ctx, op.path, op.value)
+      break
+    default:
+      throw failure(`Unknown operation kind: ${(op as any).kind}`)
+  }
+}
+
+/**
+ * Applies a single transaction to a base state immutably.
+ *
+ * Key benefits over Mutative/Immer:
+ * - No proxy overhead - direct object access and copy-on-write cloning
+ * - Structural sharing - unchanged subtrees keep their references
+ * - Zero-copy on failure - if validation fails, returns original base unchanged
+ *
+ * @param base - The base state (never mutated)
+ * @param tx - The transaction to apply
+ * @param validateFn - Optional validation function
+ * @returns The final state (if valid) or the original base (if invalid or empty)
+ */
+export function applyTxImmutable<T extends JSONObject>(
+  base: T,
+  tx: Pick<TxRecord, "ops">,
+  validateFn?: ValidateFn<T>
+): T {
+  if (tx.ops.length === 0) return base
+
+  const ctx = createDraft(base)
+
+  try {
+    for (const op of tx.ops) {
+      applyOpToDraft(ctx, op)
+    }
+
+    if (validateFn && !validateFn(ctx.root)) {
+      return base
+    }
+
+    return ctx.root
+  } catch {
+    return base
+  }
+}

package/src/error.ts

@@ -0,0 +1,12 @@
+export class StateSyncLogError extends Error {
+  constructor(msg: string) {
+    super(msg)
+
+    // Set the prototype explicitly for better instanceof support
+    Object.setPrototypeOf(this, StateSyncLogError.prototype)
+  }
+}
+
+export function failure(message: string): never {
+  throw new StateSyncLogError(message)
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export type { CheckpointKey, CheckpointRecord } from "./checkpoints"
+export {
+  createStateSyncLog,
+  type StateSyncLogController,
+  type StateSyncLogOptions,
+} from "./createStateSyncLog"
+export type { JSONObject, JSONValue, Path } from "./json"
+export { type ApplyOpsOptions, applyOps, type Op, type ValidateFn } from "./operations"

package/src/json.ts

@@ -0,0 +1,25 @@
+/**
+ * A unique path to a value within the JSON document.
+ * Resolution fails if any segment is missing or type mismatch occurs.
+ */
+export type Path = readonly (string | number)[]
+
+/**
+ * A JSON primitive.
+ */
+export type JSONPrimitive = null | boolean | number | string
+
+/**
+ * A JSON record.
+ */
+export type JSONRecord = { [k: string]: JSONValue }
+
+/**
+ * A JSON object.
+ */
+export type JSONObject = JSONRecord | JSONValue[]
+
+/**
+ * A JSON value.
+ */
+export type JSONValue = JSONPrimitive | JSONObject

package/src/operations.ts

@@ -0,0 +1,157 @@
+import { failure } from "./error"
+import { JSONObject, JSONValue, Path } from "./json"
+import { deepClone, deepEqual, isObject } from "./utils"
+
+/**
+ * Supported operations.
+ * Applied sequentially within a tx.
+ */
+export type Op =
+  | { kind: "set"; path: Path; key: string; value: JSONValue }
+  | { kind: "delete"; path: Path; key: string }
+  | { kind: "splice"; path: Path; index: number; deleteCount: number; inserts: JSONValue[] }
+  | { kind: "addToSet"; path: Path; value: JSONValue }
+  | { kind: "deleteFromSet"; path: Path; value: JSONValue }
+
+/**
+ * Validation function type.
+ *
+ * Rules:
+ * - Validation MUST depend only on candidateState (and deterministic code).
+ * - Validation runs once per tx, after all ops apply.
+ * - If validation fails, the x is rejected (state reverts to previous).
+ * - If no validator is provided, validation defaults to true.
+ *
+ * IMPORTANT: Validation outcome is **derived local state** and MUST NOT be replicated.
+ * All clients MUST use the same validation logic to ensure consistency.
+ */
+export type ValidateFn<State extends JSONObject> = (candidateState: State) => boolean
+
+/**
+ * Resolves a path within the state.
+ * Throws if any segment is missing or has wrong type.
+ */
+function resolvePath(state: JSONObject, path: Path): JSONValue {
+  let current: JSONValue = state
+  for (const segment of path) {
+    if (typeof segment === "string") {
+      if (!isObject(current) || Array.isArray(current)) {
+        failure(`Expected object at path segment "${segment}"`)
+      }
+      if (!(segment in current)) {
+        failure(`Property "${segment}" does not exist`)
+      }
+      current = current[segment]
+    } else {
+      if (!Array.isArray(current)) {
+        failure(`Expected array at path segment ${segment}`)
+      }
+      if (segment < 0 || segment >= current.length) {
+        failure(`Index ${segment} out of bounds`)
+      }
+      current = current[segment]
+    }
+  }
+  return current
+}
+
+/**
+ * Applies a single operation.
+ * (Reference implementation for standard JSON-patch behavior)
+ */
+function applyOp(state: JSONObject, op: Op, cloneValues: boolean): void {
+  // Special case: if path is empty, we can't resolve "container".
+  // The caller must handle root-level replacement if necessary, but
+  // standard Ops usually act ON a container.
+  // Exception: if we act on root, handle explicitly or assume path length > 0.
+  // For this spec, Ops modify *fields* or *indices*.
+  // If path is empty, it means we are acting ON the root object itself?
+  // The spec's "set" example: container[op.key] = op.value.
+  // This implies we resolve path to get the PARENT container.
+
+  const container = resolvePath(state, op.path)
+
+  switch (op.kind) {
+    case "set":
+      if (!isObject(container) || Array.isArray(container)) {
+        failure("set requires object container")
+      }
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      ;(container as any)[op.key] = cloneValues ? deepClone(op.value) : op.value
+      break
+
+    case "delete":
+      if (!isObject(container) || Array.isArray(container)) {
+        failure("delete requires object container")
+      }
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      delete (container as any)[op.key]
+      break
+
+    case "splice": {
+      if (!Array.isArray(container)) {
+        failure("splice requires array container")
+      }
+      const safeIndex = Math.min(op.index, container.length)
+      container.splice(
+        safeIndex,
+        op.deleteCount,
+        ...(cloneValues ? op.inserts.map((v) => deepClone(v)) : op.inserts)
+      )
+      break
+    }
+
+    case "addToSet":
+      if (!Array.isArray(container)) {
+        failure("addToSet requires array container")
+      }
+      if (!container.some((item) => deepEqual(item, op.value))) {
+        container.push(cloneValues ? deepClone(op.value) : op.value)
+      }
+      break
+
+    case "deleteFromSet":
+      if (!Array.isArray(container)) {
+        failure("deleteFromSet requires array container")
+      }
+      // Remove all matching items using splice (from end to avoid index shifting)
+      for (let i = container.length - 1; i >= 0; i--) {
+        if (deepEqual(container[i], op.value)) {
+          container.splice(i, 1)
+        }
+      }
+      break
+
+    default:
+      throw failure(`Unknown operation kind: ${(op as any).kind}`)
+  }
+}
+
+/**
+ * Options for applyOps.
+ */
+export interface ApplyOpsOptions {
+  /**
+   * Whether to deep clone values before inserting them into the target.
+   * - `true` (default): Values are cloned to prevent aliasing between the ops and target.
+   * - `false`: Values are used directly for better performance. Only use this if you
+   *   guarantee the op values won't be mutated after application.
+   */
+  cloneValues?: boolean
+}
+
+/**
+ * Applies a list of operations to a mutable target object.
+ * Use this to synchronize an external mutable state (e.g., MobX store)
+ * with the operations received via subscribe().
+ *
+ * @param ops - The list of operations to apply.
+ * @param target - The mutable object to modify.
+ * @param options - Optional settings for controlling cloning behavior.
+ */
+export function applyOps(ops: readonly Op[], target: JSONObject, options?: ApplyOpsOptions): void {
+  const cloneValues = options?.cloneValues ?? true
+  for (const op of ops) {
+    applyOp(target, op, cloneValues)
+  }
+}

package/src/reconcile.ts

@@ -0,0 +1,124 @@
+import { failure } from "./error"
+import { JSONRecord, JSONValue, Path } from "./json"
+import { Op } from "./operations"
+
+/**
+ * Reconciles the current state with the target state by computing and emitting
+ * the minimal set of operations needed to transform currentState into targetState.
+ */
+export function computeReconcileOps(currentState: JSONValue, targetState: JSONValue): Op[] {
+  const ops: Op[] = []
+  diffValue(currentState, targetState, [], ops)
+  return ops
+}
+
+function diffValue(current: JSONValue, target: JSONValue, path: Path, ops: Op[]): void {
+  // 1. Reference equality (structural sharing)
+  if (current === target) return
+
+  // 2. Handle primitives and null quickly
+  const currentType = typeof current
+  const targetType = typeof target
+
+  if (current === null || target === null || currentType !== "object" || targetType !== "object") {
+    // At least one is primitive/null, or types don't match
+    emitReplace(path, target, ops)
+    return
+  }
+
+  // Both are objects (object or array)
+  const currentIsArray = Array.isArray(current)
+  const targetIsArray = Array.isArray(target)
+
+  if (currentIsArray !== targetIsArray) {
+    // Type mismatch (one array, one object)
+    emitReplace(path, target, ops)
+    return
+  }
+
+  if (currentIsArray) {
+    diffArray(current, target as JSONValue[], path, ops)
+  } else {
+    diffObject(current as JSONRecord, target as JSONRecord, path, ops)
+  }
+}
+
+function diffObject(current: JSONRecord, target: JSONRecord, path: Path, ops: Op[]): void {
+  // 1. Delete keys in current but not in target
+  for (const key in current) {
+    if (Object.hasOwn(current, key) && !Object.hasOwn(target, key)) {
+      ops.push({ kind: "delete", path, key })
+    }
+  }
+
+  // 2. Add/Update keys in target
+  for (const key in target) {
+    if (Object.hasOwn(target, key)) {
+      const targetVal = target[key]
+      if (!Object.hasOwn(current, key)) {
+        ops.push({ kind: "set", path, key, value: targetVal })
+      } else if (current[key] !== targetVal) {
+        // Only recurse if values differ (reference check first)
+        diffValue(current[key], targetVal, [...path, key], ops)
+      }
+    }
+  }
+}
+
+function diffArray(current: JSONValue[], target: JSONValue[], path: Path, ops: Op[]): void {
+  const currentLen = current.length
+  const targetLen = target.length
+  const minLen = currentLen < targetLen ? currentLen : targetLen
+
+  // Diff common elements
+  for (let i = 0; i < minLen; i++) {
+    if (current[i] !== target[i]) {
+      diffValue(current[i], target[i], [...path, i], ops)
+    }
+  }
+
+  // Handle length difference
+  if (targetLen > currentLen) {
+    ops.push({
+      kind: "splice",
+      path,
+      index: currentLen,
+      deleteCount: 0,
+      inserts: target.slice(currentLen),
+    })
+  } else if (currentLen > targetLen) {
+    ops.push({
+      kind: "splice",
+      path,
+      index: targetLen,
+      deleteCount: currentLen - targetLen,
+      inserts: [],
+    })
+  }
+}
+
+function emitReplace(path: Path, value: JSONValue, ops: Op[]): void {
+  if (path.length === 0) {
+    // Cannot replace root directly via Ops (unless we define a 'root' op, which we don't)
+    // We expect root to be handled by diffObject usually.
+    // If we land here, it means root types mismatched (e.g. Obj -> Array).
+    failure("StateSyncLog: Cannot replace root state directly via Ops.")
+  }
+
+  const parentPath = path.slice(0, -1)
+  const keyToCheck = path[path.length - 1]
+
+  if (typeof keyToCheck === "string") {
+    // Parent is Object
+    ops.push({ kind: "set", path: parentPath, key: keyToCheck, value })
+  } else {
+    // Parent is Array
+    ops.push({
+      kind: "splice",
+      path: parentPath,
+      index: keyToCheck,
+      deleteCount: 1,
+      inserts: [value],
+    })
+  }
+}