state-sync-log 0.9.0 → 0.10.0

package/src/createOps/interface.ts

@@ -0,0 +1,95 @@
+/**
+ * createOps interface types.
+ * Simplified from mutative - removed patches, autoFreeze, strict mode, mark, Map/Set support.
+ */
+
+import type { JSONPrimitive, JSONValue, Path } from "../json"
+import type { Op } from "../operations"
+
+export type { Op, Path, JSONValue }
+
+export enum DraftType {
+  Object = 0,
+  Array = 1,
+}
+
+/**
+ * Finalities - shared state for the draft tree
+ */
+export interface Finalities {
+  /** Finalization callbacks (for unwrapping child drafts) */
+  draft: (() => void)[]
+  /** Revoke functions for all proxies */
+  revoke: (() => void)[]
+  /** Set of handled objects (for cycle detection) */
+  handledSet: WeakSet<object>
+  /** Cache of created drafts */
+  draftsCache: WeakSet<object>
+  /** List of operations performed in this draft session (eager logging) */
+  ops: Op[]
+  /** Root draft of the tree (set when creating the root draft) */
+  rootDraft: ProxyDraft | null
+}
+
+/**
+ * Internal proxy draft state
+ */
+export interface ProxyDraft<T = any> {
+  /** Type of the draft (Object or Array) */
+  type: DraftType
+  /** Whether this draft has been mutated */
+  operated?: boolean
+  /** Whether finalization has been completed */
+  finalized: boolean
+  /** The original (unmodified) value */
+  original: T
+  /** The shallow copy (created on first mutation) */
+  copy: T | null
+  /** The proxy instance */
+  proxy: T | null
+  /** Finalities container (shared across draft tree) */
+  finalities: Finalities
+  /** Parent draft (for path tracking) */
+  parent?: ProxyDraft | null
+  /** Key in parent */
+  key?: string | number
+  /** Track which keys have been assigned (key -> true=assigned, false=deleted) */
+  assignedMap?: Map<PropertyKey, boolean>
+  /** Count of positions this draft exists at (for aliasing optimization) */
+  aliasCount: number
+}
+
+/**
+ * Result of createOps
+ */
+export interface CreateOpsResult<T> {
+  /** The new immutable state */
+  nextState: T
+  /** The operations that were performed */
+  ops: Op[]
+}
+
+// ============================================================================
+// Type Utilities
+// ============================================================================
+
+/** Primitive types that don't need drafting */
+type Primitive = JSONPrimitive
+
+/**
+ * Draft type - makes all properties mutable for editing
+ */
+export type Draft<T> = T extends Primitive
+  ? T
+  : T extends object
+    ? { -readonly [K in keyof T]: Draft<T[K]> }
+    : T
+
+/**
+ * Immutable type - makes all properties readonly
+ */
+export type Immutable<T> = T extends Primitive
+  ? T
+  : T extends object
+    ? { readonly [K in keyof T]: Immutable<T[K]> }
+    : T

package/src/createOps/original.ts

@@ -0,0 +1,24 @@
+/**
+ * Get the original value from a draft.
+ */
+
+import { getProxyDraft } from "./utils"
+
+/**
+ * `original(draft)` to get original state in the draft mutation function.
+ *
+ * @example
+ * ```ts
+ * const { nextState, ops } = createOps(baseState, (draft) => {
+ *   draft.foo.bar = 'new value';
+ *   console.log(original(draft.foo)); // { bar: 'old value' }
+ * });
+ * ```
+ */
+export function original<T>(target: T): T {
+  const proxyDraft = getProxyDraft(target)
+  if (!proxyDraft) {
+    throw new Error(`original() is only used for a draft, parameter: ${target}`)
+  }
+  return proxyDraft.original as T
+}

package/src/createOps/pushOp.ts

@@ -0,0 +1,42 @@
+/**
+ * Eager op generation - ops are pushed immediately when mutations happen.
+ *
+ * This module provides the pushOp function that records operations at mutation time,
+ * rather than diffing at finalization time.
+ *
+ * When a draft exists at multiple positions (aliasing), ops are emitted for ALL positions
+ * to ensure consistency when applied.
+ */
+
+import { failure } from "../error"
+import type { Op, ProxyDraft } from "./interface"
+import { getAllPathsForDraft } from "./utils"
+
+/**
+ * Push an operation to the ops log.
+ * Values should already be cloned by the caller to avoid aliasing issues.
+ *
+ * When the target draft exists at multiple positions (due to aliasing),
+ * this function emits ops for all positions to maintain consistency.
+ */
+export function pushOp(proxyDraft: ProxyDraft, op: Op): void {
+  const rootDraft = proxyDraft.finalities.rootDraft
+  if (!rootDraft) {
+    throw failure("rootDraft is not set - cannot emit op")
+  }
+
+  // Fast path: no aliasing, just emit the single op
+  if (proxyDraft.aliasCount <= 1) {
+    proxyDraft.finalities.ops.push(op)
+    return
+  }
+
+  // Slow path: draft exists at multiple positions, find all paths
+  const allPaths = getAllPathsForDraft(rootDraft, proxyDraft)
+
+  // Emit the op for each path where this draft exists
+  for (const path of allPaths) {
+    const adjustedOp = { ...op, path }
+    proxyDraft.finalities.ops.push(adjustedOp)
+  }
+}

package/src/createOps/setHelpers.ts

@@ -0,0 +1,93 @@
+/**
+ * Helper functions for set-like array operations.
+ * Uses eager op logging - ops are pushed immediately when mutations happen.
+ */
+
+import type { JSONValue } from "../json"
+import { deepClone, deepEqual } from "../utils"
+import { pushOp } from "./pushOp"
+import { ensureShallowCopy, getPathOrThrow, getProxyDraft, markChanged } from "./utils"
+
+/**
+ * Add a value to an array if it doesn't already exist (set semantics).
+ * Generates an `addToSet` operation.
+ *
+ * @example
+ * ```ts
+ * createOps(state, (draft) => {
+ *   addToSet(draft.tags, 'newTag'); // Only adds if not present
+ * });
+ * ```
+ */
+export function addToSet<T extends JSONValue>(draft: T[], value: T): void {
+  const proxyDraft = getProxyDraft(draft)
+  if (!proxyDraft) {
+    throw new Error(`addToSet() can only be used on draft arrays`)
+  }
+
+  // Mark as changed
+  ensureShallowCopy(proxyDraft)
+  markChanged(proxyDraft)
+
+  // Check if value already exists
+  const arr = proxyDraft.copy as T[]
+  if (arr.some((item) => item === value || deepEqual(item, value))) {
+    // Value already exists - no op needed
+    return
+  }
+
+  // Add the value
+  arr.push(value)
+
+  // Eager op logging
+  pushOp(proxyDraft, {
+    kind: "addToSet",
+    path: getPathOrThrow(proxyDraft),
+    value: deepClone(value) as JSONValue,
+  })
+}
+
+/**
+ * Remove a value from an array (set semantics).
+ * Generates a `deleteFromSet` operation.
+ *
+ * @example
+ * ```ts
+ * createOps(state, (draft) => {
+ *   deleteFromSet(draft.tags, 'oldTag'); // Removes all matching items
+ * });
+ * ```
+ */
+export function deleteFromSet<T extends JSONValue>(draft: T[], value: T): void {
+  const proxyDraft = getProxyDraft(draft)
+  if (!proxyDraft) {
+    throw new Error(`deleteFromSet() can only be used on draft arrays`)
+  }
+
+  // Mark as changed
+  ensureShallowCopy(proxyDraft)
+  markChanged(proxyDraft)
+
+  // Check if value exists
+  const arr = proxyDraft.copy as T[]
+  const hasValue = arr.some((item) => item === value || deepEqual(item, value))
+
+  if (!hasValue) {
+    // Value doesn't exist - no op needed
+    return
+  }
+
+  // Remove all matching items (by value equality)
+  for (let i = arr.length - 1; i >= 0; i--) {
+    if (arr[i] === value || deepEqual(arr[i], value)) {
+      arr.splice(i, 1)
+    }
+  }
+
+  // Eager op logging
+  pushOp(proxyDraft, {
+    kind: "deleteFromSet",
+    path: getPathOrThrow(proxyDraft),
+    value: deepClone(value) as JSONValue,
+  })
+}

package/src/createOps/utils.ts

@@ -0,0 +1,325 @@
+/**
+ * Utility functions for proxy drafts.
+ * Adapted from mutative - removed Map/Set support, mark, deepFreeze.
+ */
+
+import { failure } from "../error"
+import { PROXY_DRAFT } from "./constant"
+import { DraftType, type ProxyDraft } from "./interface"
+
+// ============================================================================
+// Core Draft Utilities
+// ============================================================================
+
+/**
+ * Get the latest value (copy if exists, otherwise original)
+ */
+export function latest<T>(proxyDraft: ProxyDraft<T>): T {
+  return (proxyDraft.copy ?? proxyDraft.original) as T
+}
+
+/**
+ * Check if the value is a draft
+ */
+export function isDraft(target: unknown): boolean {
+  return !!getProxyDraft(target)
+}
+
+/**
+ * Get the ProxyDraft from a draft value
+ */
+export function getProxyDraft<T>(value: unknown): ProxyDraft<T> | null {
+  if (typeof value !== "object" || value === null) return null
+  return (value as { [PROXY_DRAFT]?: ProxyDraft<T> })[PROXY_DRAFT] ?? null
+}
+
+/**
+ * Get the actual value from a draft (copy or original)
+ */
+export function getValue<T extends object>(value: T): T {
+  const proxyDraft = getProxyDraft(value)
+  return proxyDraft ? ((proxyDraft.copy ?? proxyDraft.original) as T) : value
+}
+
+/**
+ * Check if a value is draftable (plain object or array)
+ * We only support plain objects and arrays - no Map, Set, Date, etc.
+ */
+export function isDraftable(value: unknown): value is object {
+  if (value === null || typeof value !== "object") return false
+  return Array.isArray(value) || Object.getPrototypeOf(value) === Object.prototype
+}
+
+/**
+ * Get the draft type
+ */
+export function getType(target: unknown): DraftType {
+  return Array.isArray(target) ? DraftType.Array : DraftType.Object
+}
+
+/**
+ * Get a value by key
+ */
+export function get(target: object, key: PropertyKey): unknown {
+  return (target as Record<PropertyKey, unknown>)[key]
+}
+
+/**
+ * Set a value by key
+ */
+export function set(target: object, key: PropertyKey, value: unknown): void {
+  ;(target as Record<PropertyKey, unknown>)[key] = value
+}
+
+/**
+ * Check if a key exists (own property)
+ */
+export function has(target: object, key: PropertyKey): boolean {
+  return Object.hasOwn(target, key as string)
+}
+
+/**
+ * Peek at a value (through drafts)
+ */
+export function peek(target: object, key: PropertyKey): unknown {
+  const state = getProxyDraft(target)
+  const source = state ? latest(state) : target
+  return (source as Record<PropertyKey, unknown>)[key]
+}
+
+/**
+ * SameValue comparison (handles -0 and NaN)
+ */
+export function isEqual(x: unknown, y: unknown): boolean {
+  if (x === y) {
+    return x !== 0 || 1 / (x as number) === 1 / (y as number)
+  }
+  // biome-ignore lint/suspicious/noSelfCompare: NaN check pattern (NaN !== NaN)
+  return x !== x && y !== y
+}
+
+/**
+ * Revoke all proxies in a draft tree
+ */
+export function revokeProxy(proxyDraft: ProxyDraft | null): void {
+  if (!proxyDraft) return
+  while (proxyDraft.finalities.revoke.length > 0) {
+    const revoke = proxyDraft.finalities.revoke.pop()!
+    revoke()
+  }
+}
+
+/**
+ * Get the path from root to this draft
+ */
+export function getPath(
+  target: ProxyDraft,
+  path: (string | number)[] = []
+): (string | number)[] | null {
+  if (Object.hasOwn(target, "key") && target.key !== undefined) {
+    // Check if the parent still has this draft at this key
+    const parentCopy = target.parent?.copy
+    if (parentCopy) {
+      const proxyDraft = getProxyDraft(get(parentCopy as object, target.key))
+      if (proxyDraft !== null && proxyDraft.original !== target.original) {
+        return null
+      }
+    }
+    path.push(target.key)
+  }
+  if (target.parent) {
+    return getPath(target.parent, path)
+  }
+  // target is root draft
+  path.reverse()
+  return path
+}
+
+/**
+ * Get the path from root to this draft, or throw if not available
+ */
+export function getPathOrThrow(target: ProxyDraft): (string | number)[] {
+  const path = getPath(target)
+  if (!path) {
+    throw failure("Cannot determine path for operation")
+  }
+  return path
+}
+
+/**
+ * Find all paths to a given draft by searching the tree.
+ * This handles aliasing where the same draft exists at multiple positions.
+ */
+export function getAllPathsForDraft(
+  rootDraft: ProxyDraft,
+  targetDraft: ProxyDraft
+): (string | number)[][] {
+  const result: (string | number)[][] = []
+
+  function search(current: ProxyDraft, currentPath: (string | number)[]): void {
+    if (current === targetDraft) {
+      result.push([...currentPath])
+      // Don't return - the same draft could be nested inside itself (unlikely but possible)
+    }
+
+    const source = latest(current) as Record<string | number, unknown>
+    if (!source || typeof source !== "object") return
+
+    const keys: (string | number)[] = Array.isArray(source)
+      ? Array.from({ length: source.length }, (_, i) => i)
+      : Object.keys(source)
+
+    for (const key of keys) {
+      const value = source[key]
+      const childDraft = getProxyDraft(value)
+      if (childDraft) {
+        search(childDraft, [...currentPath, key])
+      }
+    }
+  }
+
+  search(rootDraft, [])
+  return result
+}
+
+/**
+ * Get a property descriptor from the prototype chain
+ */
+export function getDescriptor(target: object, key: PropertyKey): PropertyDescriptor | undefined {
+  if (key in target) {
+    let prototype = Reflect.getPrototypeOf(target)
+    while (prototype) {
+      const descriptor = Reflect.getOwnPropertyDescriptor(prototype, key)
+      if (descriptor) return descriptor
+      prototype = Reflect.getPrototypeOf(prototype)
+    }
+  }
+  return undefined
+}
+
+// ============================================================================
+// Copy Utilities
+// ============================================================================
+
+const propIsEnum = Object.prototype.propertyIsEnumerable
+
+/**
+ * Create a shallow copy of an object or array
+ */
+export function shallowCopy<T>(original: T): T {
+  if (Array.isArray(original)) {
+    return Array.prototype.concat.call(original) as T
+  }
+  // Plain object - use optimized copy
+  const copy: Record<string | symbol, unknown> = {}
+  for (const key of Object.keys(original as object)) {
+    copy[key] = (original as Record<string, unknown>)[key]
+  }
+  for (const key of Object.getOwnPropertySymbols(original as object)) {
+    if (propIsEnum.call(original, key)) {
+      copy[key] = (original as Record<symbol, unknown>)[key]
+    }
+  }
+  return copy as T
+}
+
+/**
+ * Ensure a draft has a shallow copy
+ */
+export function ensureShallowCopy(target: ProxyDraft): void {
+  if (target.copy) return
+  target.copy = shallowCopy(target.original)
+  target.assignedMap = target.assignedMap ?? new Map()
+}
+
+/**
+ * Deep clone a value, unwrapping any drafts
+ */
+export function deepClone<T>(target: T): T {
+  if (!isDraftable(target)) {
+    return isDraft(target) ? (getValue(target as object) as T) : target
+  }
+  if (Array.isArray(target)) {
+    return target.map(deepClone) as T
+  }
+  const copy: Record<string, unknown> = {}
+  for (const key in target) {
+    if (has(target, key)) {
+      copy[key] = deepClone((target as Record<string, unknown>)[key])
+    }
+  }
+  return copy as T
+}
+
+/**
+ * Clone if the value is a draft, otherwise return as-is
+ */
+export function cloneIfNeeded<T>(target: T): T {
+  return isDraft(target) ? deepClone(target) : target
+}
+
+// ============================================================================
+// Draft State Utilities
+// ============================================================================
+
+/**
+ * Mark a draft as changed (operated)
+ */
+export function markChanged(target: ProxyDraft): void {
+  if (!target.operated) {
+    target.operated = true
+    if (target.parent) {
+      markChanged(target.parent)
+    }
+  }
+}
+
+/**
+ * Iterate over object/array entries
+ */
+export function forEach<T extends object>(
+  target: T,
+  callback: (key: PropertyKey, value: unknown, target: T) => void
+): void {
+  if (Array.isArray(target)) {
+    for (let i = 0; i < target.length; i++) {
+      callback(i, target[i], target)
+    }
+  } else {
+    for (const key of Reflect.ownKeys(target)) {
+      callback(key, (target as Record<PropertyKey, unknown>)[key], target)
+    }
+  }
+}
+
+// ============================================================================
+// Finalization Utilities
+// ============================================================================
+
+/**
+ * Handle nested values during finalization
+ */
+export function handleValue(target: unknown, handledSet: WeakSet<object>): void {
+  if (
+    !isDraftable(target) ||
+    isDraft(target) ||
+    handledSet.has(target as object) ||
+    Object.isFrozen(target)
+  ) {
+    return
+  }
+
+  handledSet.add(target as object)
+
+  forEach(target as object, (key, value) => {
+    if (isDraft(value)) {
+      const proxyDraft = getProxyDraft(value)!
+      ensureShallowCopy(proxyDraft)
+      const updatedValue =
+        proxyDraft.assignedMap?.size || proxyDraft.operated ? proxyDraft.copy : proxyDraft.original
+      set(target as object, key, updatedValue)
+    } else {
+      handleValue(value, handledSet)
+    }
+  })
+}