@loro-extended/change 0.2.0

package/src/json-patch.ts

@@ -0,0 +1,391 @@
+/** biome-ignore-all lint/suspicious/noExplicitAny: JSON Patch values can be any type */
+
+import type { DocShape } from "./shape.js"
+import type { Draft } from "./types.js"
+
+// =============================================================================
+// JSON PATCH TYPES - Discriminated Union for Type Safety
+// =============================================================================
+
+export type JsonPatchAddOperation = {
+  op: "add"
+  path: string | (string | number)[]
+  value: any
+}
+
+export type JsonPatchRemoveOperation = {
+  op: "remove"
+  path: string | (string | number)[]
+}
+
+export type JsonPatchReplaceOperation = {
+  op: "replace"
+  path: string | (string | number)[]
+  value: any
+}
+
+export type JsonPatchMoveOperation = {
+  op: "move"
+  path: string | (string | number)[]
+  from: string | (string | number)[]
+}
+
+export type JsonPatchCopyOperation = {
+  op: "copy"
+  path: string | (string | number)[]
+  from: string | (string | number)[]
+}
+
+export type JsonPatchTestOperation = {
+  op: "test"
+  path: string | (string | number)[]
+  value: any
+}
+
+export type JsonPatchOperation =
+  | JsonPatchAddOperation
+  | JsonPatchRemoveOperation
+  | JsonPatchReplaceOperation
+  | JsonPatchMoveOperation
+  | JsonPatchCopyOperation
+  | JsonPatchTestOperation
+
+export type JsonPatch = JsonPatchOperation[]
+
+// =============================================================================
+// PATH NAVIGATION UTILITIES
+// =============================================================================
+
+/**
+ * Normalize JSON Pointer string to path array
+ * Handles RFC 6901 escaping: ~1 -> /, ~0 -> ~
+ */
+export function normalizePath(
+  path: string | (string | number)[],
+): (string | number)[] {
+  if (Array.isArray(path)) {
+    return path
+  }
+
+  // Handle JSON Pointer format (RFC 6901)
+  if (path.startsWith("/")) {
+    return path
+      .slice(1) // Remove leading slash
+      .split("/")
+      .map(segment => {
+        // Handle JSON Pointer escaping
+        const unescaped = segment.replace(/~1/g, "/").replace(/~0/g, "~")
+        // Try to parse as number for array indices
+        const asNumber = Number(unescaped)
+        return Number.isInteger(asNumber) && asNumber >= 0
+          ? asNumber
+          : unescaped
+      })
+  }
+
+  // Handle simple dot notation or single segment
+  return path.split(".").map(segment => {
+    const asNumber = Number(segment)
+    return Number.isInteger(asNumber) && asNumber >= 0 ? asNumber : segment
+  })
+}
+
+/**
+ * Navigate to a target path using natural DraftNode property access
+ * This follows the existing patterns from the test suite
+ */
+function navigateToPath<T extends DocShape>(
+  draft: Draft<T>,
+  path: (string | number)[],
+): { parent: any; key: string | number } {
+  if (path.length === 0) {
+    throw new Error("Cannot navigate to empty path")
+  }
+
+  let current = draft as any
+
+  // Navigate to parent of target
+  for (let i = 0; i < path.length - 1; i++) {
+    const segment = path[i]
+
+    if (typeof segment === "string") {
+      // Use natural property access - this leverages existing DraftNode lazy creation
+      current = current[segment]
+      if (current === undefined) {
+        throw new Error(`Cannot navigate to path segment: ${segment}`)
+      }
+    } else if (typeof segment === "number") {
+      // List/array access using get() method (following existing patterns)
+      if (current.get && typeof current.get === "function") {
+        current = current.get(segment)
+        if (current === undefined) {
+          throw new Error(`List index ${segment} does not exist`)
+        }
+      } else {
+        throw new Error(`Cannot use numeric index ${segment} on non-list`)
+      }
+    } else {
+      throw new Error(`Invalid path segment type: ${typeof segment}`)
+    }
+  }
+
+  const targetKey = path[path.length - 1]
+  return { parent: current, key: targetKey }
+}
+
+/**
+ * Get value at path using natural DraftNode access patterns
+ */
+function getValueAtPath<T extends DocShape>(
+  draft: Draft<T>,
+  path: (string | number)[],
+): any {
+  if (path.length === 0) {
+    return draft
+  }
+
+  const { parent, key } = navigateToPath(draft, path)
+
+  if (typeof key === "string") {
+    // Use natural property access or get() method
+    if (parent.get && typeof parent.get === "function") {
+      return parent.get(key)
+    }
+    return parent[key]
+  } else if (typeof key === "number") {
+    // List access using get() method
+    if (parent.get && typeof parent.get === "function") {
+      return parent.get(key)
+    }
+    throw new Error(`Cannot use numeric index ${key} on non-list`)
+  }
+
+  throw new Error(`Invalid key type: ${typeof key}`)
+}
+
+// =============================================================================
+// OPERATION HANDLERS - Following existing DraftNode patterns
+// =============================================================================
+
+/**
+ * Handle 'add' operation using existing DraftNode methods
+ */
+function handleAdd<T extends DocShape>(
+  draft: Draft<T>,
+  operation: JsonPatchAddOperation,
+): void {
+  const path = normalizePath(operation.path)
+  const { parent, key } = navigateToPath(draft, path)
+
+  if (typeof key === "string") {
+    // Map-like operations - use natural assignment or set() method
+    if (parent.set && typeof parent.set === "function") {
+      parent.set(key, operation.value)
+    } else {
+      // Natural property assignment (follows existing test patterns)
+      parent[key] = operation.value
+    }
+  } else if (typeof key === "number") {
+    // List operations - use insert() method (follows existing patterns)
+    if (parent.insert && typeof parent.insert === "function") {
+      parent.insert(key, operation.value)
+    } else {
+      throw new Error(`Cannot insert at numeric index ${key} on non-list`)
+    }
+  } else {
+    throw new Error(`Invalid key type: ${typeof key}`)
+  }
+}
+
+/**
+ * Handle 'remove' operation using existing DraftNode methods
+ */
+function handleRemove<T extends DocShape>(
+  draft: Draft<T>,
+  operation: JsonPatchRemoveOperation,
+): void {
+  const path = normalizePath(operation.path)
+  const { parent, key } = navigateToPath(draft, path)
+
+  if (typeof key === "string") {
+    // Map-like operations - use delete() method (follows existing patterns)
+    if (parent.delete && typeof parent.delete === "function") {
+      parent.delete(key)
+    } else {
+      delete parent[key]
+    }
+  } else if (typeof key === "number") {
+    // List operations - use delete() method with count (follows existing patterns)
+    if (parent.delete && typeof parent.delete === "function") {
+      parent.delete(key, 1)
+    } else {
+      throw new Error(`Cannot remove at numeric index ${key} on non-list`)
+    }
+  } else {
+    throw new Error(`Invalid key type: ${typeof key}`)
+  }
+}
+
+/**
+ * Handle 'replace' operation using existing DraftNode methods
+ */
+function handleReplace<T extends DocShape>(
+  draft: Draft<T>,
+  operation: JsonPatchReplaceOperation,
+): void {
+  const path = normalizePath(operation.path)
+  const { parent, key } = navigateToPath(draft, path)
+
+  if (typeof key === "string") {
+    // Map-like operations - use set() method or natural assignment
+    if (parent.set && typeof parent.set === "function") {
+      parent.set(key, operation.value)
+    } else {
+      parent[key] = operation.value
+    }
+  } else if (typeof key === "number") {
+    // List operations - delete then insert (follows existing patterns)
+    if (
+      parent.delete &&
+      parent.insert &&
+      typeof parent.delete === "function" &&
+      typeof parent.insert === "function"
+    ) {
+      parent.delete(key, 1)
+      parent.insert(key, operation.value)
+    } else {
+      throw new Error(`Cannot replace at numeric index ${key} on non-list`)
+    }
+  } else {
+    throw new Error(`Invalid key type: ${typeof key}`)
+  }
+}
+
+/**
+ * Handle 'move' operation using existing DraftNode methods
+ */
+function handleMove<T extends DocShape>(
+  draft: Draft<T>,
+  operation: JsonPatchMoveOperation,
+): void {
+  const fromPath = normalizePath(operation.from)
+  const toPath = normalizePath(operation.path)
+
+  // For list moves within the same parent, we need special handling
+  if (
+    fromPath.length === toPath.length &&
+    fromPath.slice(0, -1).every((segment, i) => segment === toPath[i])
+  ) {
+    // Same parent container - use list move operation if available
+    const fromIndex = fromPath[fromPath.length - 1]
+    const toIndex = toPath[toPath.length - 1]
+
+    if (typeof fromIndex === "number" && typeof toIndex === "number") {
+      const { parent } = navigateToPath(draft, fromPath.slice(0, -1))
+
+      // Check if the parent has a move method (like LoroMovableList)
+      if (parent.move && typeof parent.move === "function") {
+        parent.move(fromIndex, toIndex)
+        return
+      }
+
+      // Otherwise, get value, remove, then add at target index
+      const value = getValueAtPath(draft, fromPath)
+      handleRemove(draft, { op: "remove", path: operation.from })
+
+      // For JSON Patch move semantics, the target index refers to the position
+      // in the final array, not the intermediate array after removal.
+      // No index adjustment needed - use the original target index.
+      handleAdd(draft, { op: "add", path: operation.path, value })
+      return
+    }
+  }
+
+  // Different parents or non-numeric indices - standard move
+  const value = getValueAtPath(draft, fromPath)
+  handleRemove(draft, { op: "remove", path: operation.from })
+  handleAdd(draft, { op: "add", path: operation.path, value })
+}
+
+/**
+ * Handle 'copy' operation using existing DraftNode methods
+ */
+function handleCopy<T extends DocShape>(
+  draft: Draft<T>,
+  operation: JsonPatchCopyOperation,
+): void {
+  const fromPath = normalizePath(operation.from)
+
+  // Get the value to copy
+  const value = getValueAtPath(draft, fromPath)
+
+  // Add to destination (no removal)
+  handleAdd(draft, { op: "add", path: operation.path, value })
+}
+
+/**
+ * Handle 'test' operation using existing DraftNode value access
+ */
+function handleTest<T extends DocShape>(
+  draft: Draft<T>,
+  operation: JsonPatchTestOperation,
+): boolean {
+  const path = normalizePath(operation.path)
+  const actualValue = getValueAtPath(draft, path)
+
+  // Deep equality check for test operation
+  return JSON.stringify(actualValue) === JSON.stringify(operation.value)
+}
+
+// =============================================================================
+// MAIN APPLICATOR - Simple orchestration following existing patterns
+// =============================================================================
+
+/**
+ * Main JSON Patch applicator - follows existing change() patterns
+ */
+export class JsonPatchApplicator<T extends DocShape> {
+  constructor(private rootDraft: Draft<T>) {}
+
+  /**
+   * Apply a single JSON Patch operation
+   */
+  applyOperation(operation: JsonPatchOperation): void {
+    switch (operation.op) {
+      case "add":
+        handleAdd(this.rootDraft, operation)
+        break
+      case "remove":
+        handleRemove(this.rootDraft, operation)
+        break
+      case "replace":
+        handleReplace(this.rootDraft, operation)
+        break
+      case "move":
+        handleMove(this.rootDraft, operation)
+        break
+      case "copy":
+        handleCopy(this.rootDraft, operation)
+        break
+      case "test":
+        if (!handleTest(this.rootDraft, operation)) {
+          throw new Error(`JSON Patch test failed at path: ${operation.path}`)
+        }
+        break
+      default:
+        // TypeScript will catch this at compile time with proper discriminated union
+        throw new Error(
+          `Unsupported JSON Patch operation: ${(operation as any).op}`,
+        )
+    }
+  }
+
+  /**
+   * Apply multiple JSON Patch operations in sequence
+   */
+  applyPatch(patch: JsonPatch): void {
+    for (const operation of patch) {
+      this.applyOperation(operation)
+    }
+  }
+}

package/src/overlay.ts

@@ -0,0 +1,90 @@
+import type { Value } from "loro-crdt"
+import type { ContainerShape, DocShape, ValueShape } from "./shape.js"
+import { isObjectValue } from "./utils/type-guards.js"
+
+/**
+ * Overlays CRDT state with empty state defaults
+ */
+export function overlayEmptyState<Shape extends DocShape>(
+  shape: Shape,
+  crdtValue: { [key: string]: Value },
+  emptyValue: { [key: string]: Value },
+): { [key: string]: Value } {
+  if (typeof crdtValue !== "object") {
+    throw new Error("crdt object is required")
+  }
+
+  if (typeof emptyValue !== "object") {
+    throw new Error("empty object is required")
+  }
+
+  const result = { ...emptyValue }
+
+  for (const [key, propShape] of Object.entries(shape.shapes)) {
+    const propCrdtValue = crdtValue[key]
+
+    const propEmptyValue = emptyValue[key as keyof typeof emptyValue]
+
+    result[key as keyof typeof result] = mergeValue(
+      propShape,
+      propCrdtValue,
+      propEmptyValue,
+    )
+  }
+
+  return result
+}
+
+/**
+ * Merges individual CRDT values with empty state defaults
+ */
+export function mergeValue<Shape extends ContainerShape | ValueShape>(
+  shape: Shape,
+  crdtValue: Value,
+  emptyValue: Value,
+): Value {
+  if (crdtValue === undefined && emptyValue === undefined) {
+    throw new Error("either crdt or empty value must be defined")
+  }
+
+  switch (shape._type) {
+    case "text":
+      return crdtValue ?? emptyValue ?? ""
+    case "counter":
+      return crdtValue ?? emptyValue ?? 0
+    case "list":
+    case "movableList":
+      return crdtValue ?? emptyValue ?? []
+    case "map": {
+      if (!isObjectValue(crdtValue) && crdtValue !== undefined) {
+        throw new Error("map crdt must be object")
+      }
+
+      const crdtMapValue = crdtValue ?? {}
+
+      if (!isObjectValue(emptyValue) && emptyValue !== undefined) {
+        throw new Error("map empty state must be object")
+      }
+
+      const emptyMapValue = emptyValue ?? {}
+
+      const result = { ...emptyMapValue }
+      for (const [key, nestedShape] of Object.entries(shape.shapes)) {
+        const nestedCrdtValue = crdtMapValue[key]
+        const nestedEmptyValue = emptyMapValue[key]
+
+        result[key as keyof typeof result] = mergeValue(
+          nestedShape,
+          nestedCrdtValue,
+          nestedEmptyValue,
+        )
+      }
+
+      return result
+    }
+    case "tree":
+      return crdtValue ?? emptyValue ?? []
+    default:
+      return crdtValue ?? emptyValue
+  }
+}

package/src/record.test.ts

@@ -0,0 +1,188 @@
+import { describe, expect, it } from "vitest"
+import { Shape, TypedDoc } from "./index.js"
+
+describe("Record Types", () => {
+  describe("Shape.record (Container)", () => {
+    it("should handle record of counters", () => {
+      const schema = Shape.doc({
+        scores: Shape.record(Shape.counter()),
+      })
+
+      const doc = new TypedDoc(schema, { scores: {} })
+
+      doc.change(draft => {
+        draft.scores.getOrCreateNode("alice").increment(10)
+        draft.scores.getOrCreateNode("bob").increment(5)
+      })
+
+      expect(doc.value.scores).toEqual({
+        alice: 10,
+        bob: 5,
+      })
+
+      doc.change(draft => {
+        draft.scores.getOrCreateNode("alice").increment(5)
+        draft.scores.delete("bob")
+      })
+
+      expect(doc.value.scores).toEqual({
+        alice: 15,
+      })
+    })
+
+    it("should handle record of text", () => {
+      const schema = Shape.doc({
+        notes: Shape.record(Shape.text()),
+      })
+
+      const doc = new TypedDoc(schema, { notes: {} })
+
+      doc.change(draft => {
+        draft.notes.getOrCreateNode("todo").insert(0, "Buy milk")
+        draft.notes.getOrCreateNode("reminders").insert(0, "Call mom")
+      })
+
+      expect(doc.value.notes).toEqual({
+        todo: "Buy milk",
+        reminders: "Call mom",
+      })
+    })
+
+    it("should handle record of lists", () => {
+      const schema = Shape.doc({
+        groups: Shape.record(Shape.list(Shape.plain.string())),
+      })
+
+      const doc = new TypedDoc(schema, { groups: {} })
+
+      doc.change(draft => {
+        const groupA = draft.groups.getOrCreateNode("groupA")
+        groupA.push("alice")
+        groupA.push("bob")
+
+        const groupB = draft.groups.getOrCreateNode("groupB")
+        groupB.push("charlie")
+      })
+
+      expect(doc.value.groups).toEqual({
+        groupA: ["alice", "bob"],
+        groupB: ["charlie"],
+      })
+    })
+  })
+
+  describe("Shape.plain.record (Value)", () => {
+    it("should handle record of plain strings", () => {
+      const schema = Shape.doc({
+        wrapper: Shape.map({
+          config: Shape.plain.record(Shape.plain.string()),
+        }),
+      })
+
+      const doc = new TypedDoc(schema, { wrapper: { config: {} } })
+
+      doc.change(draft => {
+        draft.wrapper.config.theme = "dark"
+        draft.wrapper.config.lang = "en"
+      })
+
+      expect(doc.value.wrapper.config).toEqual({
+        theme: "dark",
+        lang: "en",
+      })
+
+      doc.change(draft => {
+        delete draft.wrapper.config.theme
+        draft.wrapper.config.lang = "fr"
+      })
+
+      expect(doc.value.wrapper.config).toEqual({
+        lang: "fr",
+      })
+    })
+
+    it("should handle record of plain numbers", () => {
+      const schema = Shape.doc({
+        wrapper: Shape.map({
+          stats: Shape.plain.record(Shape.plain.number()),
+        }),
+      })
+
+      const doc = new TypedDoc(schema, { wrapper: { stats: { visits: 0 } } })
+
+      doc.change(draft => {
+        draft.wrapper.stats.visits = 100
+        draft.wrapper.stats.clicks = 50
+      })
+
+      expect(doc.value.wrapper.stats).toEqual({
+        visits: 100,
+        clicks: 50,
+      })
+    })
+
+    it("should handle nested records", () => {
+      const schema = Shape.doc({
+        wrapper: Shape.map({
+          settings: Shape.plain.record(
+            Shape.plain.record(Shape.plain.boolean()),
+          ),
+        }),
+      })
+
+      const doc = new TypedDoc(schema, { wrapper: { settings: {} } })
+
+      doc.change(draft => {
+        draft.wrapper.settings.ui = {
+          darkMode: true,
+          sidebar: false,
+        }
+        draft.wrapper.settings.notifications = {
+          email: true,
+          push: true,
+        }
+      })
+
+      expect(doc.value.wrapper.settings).toEqual({
+        ui: {
+          darkMode: true,
+          sidebar: false,
+        },
+        notifications: {
+          email: true,
+          push: true,
+        },
+      })
+    })
+  })
+
+  describe("Mixed Usage", () => {
+    it("should handle record of maps", () => {
+      const schema = Shape.doc({
+        users: Shape.record(
+          Shape.map({
+            name: Shape.plain.string(),
+            age: Shape.plain.number(),
+          }),
+        ),
+      })
+
+      const doc = new TypedDoc(schema, { users: {} })
+
+      doc.change(draft => {
+        const alice = draft.users.getOrCreateNode("u1")
+        alice.name = "Alice"
+        alice.age = 30
+
+        const bob = draft.users.getOrCreateNode("u2")
+        bob.name = "Bob"
+        bob.age = 25
+      })
+
+      expect(doc.value.users).toEqual({
+        u1: { name: "Alice", age: 30 },
+        u2: { name: "Bob", age: 25 },
+      })
+    })
+  })
+})