@loro-extended/change 4.0.0 → 5.0.0

package/src/functional-helpers.ts

@@ -1,6 +1,29 @@
-import type { LoroDoc } from "loro-crdt"
-import type { DocShape } from "./shape.js"
+import type {
+  LoroCounter,
+  LoroDoc,
+  LoroList,
+  LoroMap,
+  LoroMovableList,
+  LoroText,
+  LoroTree,
+} from "loro-crdt"
+import { loro } from "./loro.js"
+import type {
+  ContainerOrValueShape,
+  ContainerShape,
+  CounterContainerShape,
+  DocShape,
+  ListContainerShape,
+  MovableListContainerShape,
+  RecordContainerShape,
+  ShapeToContainer,
+  StructContainerShape,
+  TextContainerShape,
+} from "./shape.js"
 import type { TypedDoc } from "./typed-doc.js"
+import type { TypedRef } from "./typed-refs/base.js"
+import type { StructRef } from "./typed-refs/struct-ref.js"
+import type { TreeRef } from "./typed-refs/tree-ref.js"
 import type { Mutable } from "./types.js"
 
 /**
@@ -36,26 +59,93 @@ export function change<Shape extends DocShape>(
   doc: TypedDoc<Shape>,
   fn: (draft: Mutable<Shape>) => void,
 ): TypedDoc<Shape> {
-  return doc.$.change(fn)
+  return doc.change(fn)
 }
 
 /**
  * Access the underlying LoroDoc for advanced operations.
+ * Works on both TypedDoc and any typed ref (TextRef, CounterRef, ListRef, etc.).
  *
- * @param doc - The TypedDoc to unwrap
- * @returns The underlying LoroDoc instance
+ * @param docOrRef - The TypedDoc or typed ref to unwrap
+ * @returns The underlying LoroDoc instance (or undefined for refs created outside a doc context)
  *
  * @example
  * ```typescript
  * import { getLoroDoc } from "@loro-extended/change"
  *
+ * // From TypedDoc
  * const loroDoc = getLoroDoc(doc)
  * const version = loroDoc.version()
  * loroDoc.subscribe(() => console.log("changed"))
+ *
+ * // From any ref (TextRef, CounterRef, ListRef, etc.)
+ * const titleRef = doc.title
+ * const loroDoc = getLoroDoc(titleRef)
+ * loroDoc?.subscribe(() => console.log("changed"))
  * ```
  */
 export function getLoroDoc<Shape extends DocShape>(
   doc: TypedDoc<Shape>,
+): LoroDoc
+export function getLoroDoc<Shape extends ContainerShape>(
+  ref: TypedRef<Shape>,
+): LoroDoc
+export function getLoroDoc<DataShape extends StructContainerShape>(
+  ref: TreeRef<DataShape>,
+): LoroDoc
+export function getLoroDoc(
+  docOrRef: TypedDoc<any> | TypedRef<any> | TreeRef<any>,
 ): LoroDoc {
-  return doc.$.loroDoc
+  // Use loro() to access the underlying LoroDoc
+  return loro(docOrRef as any).doc
+}
+
+/**
+ * Access the underlying Loro container from a typed ref.
+ * Returns the correctly-typed container based on the ref type.
+ *
+ * @param ref - The typed ref to unwrap
+ * @returns The underlying Loro container (LoroText, LoroCounter, LoroList, etc.)
+ *
+ * @example
+ * ```typescript
+ * import { getLoroContainer } from "@loro-extended/change"
+ *
+ * const titleRef = doc.title
+ * const loroText = getLoroContainer(titleRef)  // LoroText
+ *
+ * const countRef = doc.count
+ * const loroCounter = getLoroContainer(countRef)  // LoroCounter
+ *
+ * const itemsRef = doc.items
+ * const loroList = getLoroContainer(itemsRef)  // LoroList
+ *
+ * // Subscribe to container-level changes
+ * loroText.subscribe((event) => console.log("Text changed:", event))
+ * ```
+ */
+export function getLoroContainer(ref: TypedRef<TextContainerShape>): LoroText
+export function getLoroContainer(
+  ref: TypedRef<CounterContainerShape>,
+): LoroCounter
+export function getLoroContainer(ref: TypedRef<ListContainerShape>): LoroList
+export function getLoroContainer(
+  ref: TypedRef<MovableListContainerShape>,
+): LoroMovableList
+export function getLoroContainer(ref: TypedRef<RecordContainerShape>): LoroMap
+export function getLoroContainer(ref: TypedRef<StructContainerShape>): LoroMap
+export function getLoroContainer<
+  NestedShapes extends Record<string, ContainerOrValueShape>,
+>(ref: StructRef<NestedShapes>): LoroMap
+export function getLoroContainer<DataShape extends StructContainerShape>(
+  ref: TreeRef<DataShape>,
+): LoroTree
+export function getLoroContainer<Shape extends ContainerShape>(
+  ref: TypedRef<Shape>,
+): ShapeToContainer<Shape>
+export function getLoroContainer(
+  ref: TypedRef<any> | TreeRef<any> | StructRef<any>,
+): unknown {
+  // Use loro() to access the underlying container
+  return loro(ref as any).container
 }

package/src/grand-unified-api.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it } from "vitest"
+import { loro } from "./loro.js"
 import { Shape } from "./shape.js"
 import { createTypedDoc } from "./typed-doc.js"
 
@@ -7,7 +8,7 @@ import { createTypedDoc } from "./typed-doc.js"
  *
  * This API provides direct schema access on the doc object:
  * - doc.count.increment(5) instead of doc.count.increment(5)
- * - doc.$.change() for batched mutations
+ * - doc.change() for batched mutations
  * - doc.toJSON() for serialization
  */
 describe("Grand Unified API v3", () => {
@@ -113,7 +114,7 @@ describe("Grand Unified API v3", () => {
 
     it("should support 'in' operator after change()", () => {
       const doc = createTypedDoc(schema)
-      doc.$.change(draft => {
+      doc.change(draft => {
         draft.users.set("alice", { name: "Alice" })
         draft.users.set("bob", { name: "Bob" })
       })
@@ -128,15 +129,15 @@ describe("Grand Unified API v3", () => {
       const doc = createTypedDoc(schema)
 
       // Track commits by checking version changes
-      const versionBefore = doc.$.loroDoc.version()
+      const versionBefore = loro(doc).doc.version()
 
-      doc.$.change(draft => {
+      doc.change(draft => {
         draft.count.increment(1)
         draft.count.increment(2)
         draft.count.increment(3)
       })
 
-      const versionAfter = doc.$.loroDoc.version()
+      const versionAfter = loro(doc).doc.version()
 
       // Version should have changed
       expect(versionAfter).not.toEqual(versionBefore)
@@ -146,7 +147,7 @@ describe("Grand Unified API v3", () => {
     it("should batch multiple different operations", () => {
       const doc = createTypedDoc(schema)
 
-      doc.$.change(draft => {
+      doc.change(draft => {
         draft.title.insert(0, "Hello World")
         draft.count.increment(42)
         draft.users.set("alice", { name: "Alice" })
@@ -163,7 +164,7 @@ describe("Grand Unified API v3", () => {
     it("should return doc for chaining from change()", () => {
       const doc = createTypedDoc(schema)
 
-      const result = doc.$.change(draft => {
+      const result = doc.change(draft => {
         draft.title.insert(0, "Test")
         draft.count.increment(5)
       })
@@ -178,9 +179,11 @@ describe("Grand Unified API v3", () => {
       const doc = createTypedDoc(schema)
 
       // Chain mutations after change
-      doc.$.change(draft => {
-        draft.count.increment(5)
-      }).count.increment(3)
+      doc
+        .change(draft => {
+          draft.count.increment(5)
+        })
+        .count.increment(3)
 
       expect(doc.toJSON().count).toBe(8)
     })
@@ -192,19 +195,19 @@ describe("Grand Unified API v3", () => {
 
       // Both should have .has()
       expect(typeof doc.users.has).toBe("function")
-      doc.$.change(draft => {
+      doc.change(draft => {
         expect(typeof draft.users.has).toBe("function")
       })
 
       // Both should have .keys()
       expect(typeof doc.users.keys).toBe("function")
-      doc.$.change(draft => {
+      doc.change(draft => {
         expect(typeof draft.users.keys).toBe("function")
       })
 
       // Both should have .set()
       expect(typeof doc.users.set).toBe("function")
-      doc.$.change(draft => {
+      doc.change(draft => {
         expect(typeof draft.users.set).toBe("function")
       })
     })
@@ -213,7 +216,7 @@ describe("Grand Unified API v3", () => {
       const doc = createTypedDoc(schema)
 
       // Set up some data
-      doc.$.change(draft => {
+      doc.change(draft => {
         draft.title.insert(0, "Test Title")
         draft.count.increment(42)
         draft.users.set("alice", { name: "Alice" })
@@ -245,7 +248,7 @@ describe("Grand Unified API v3", () => {
       // Direct mutations on nested containers
       doc.article.title.insert(0, "My Article")
       doc.article.metadata.views.increment(100)
-      doc.article.metadata.set("author", "John Doe")
+      doc.article.metadata.author = "John Doe"
 
       const result = doc.toJSON()
       expect(result.article.title).toBe("My Article")
@@ -266,7 +269,7 @@ describe("Grand Unified API v3", () => {
       const doc = createTypedDoc(listMapSchema)
 
       // Push via batch first to create the structure
-      doc.$.change(draft => {
+      doc.change(draft => {
         draft.articles.push({ title: "Article 1", views: 0 })
         draft.articles.push({ title: "Article 2", views: 0 })
       })
@@ -386,25 +389,28 @@ describe("Grand Unified API v3", () => {
     })
   })
 
-  describe("$ namespace", () => {
-    it("should provide access to meta-operations via $", () => {
+  describe("loro() namespace", () => {
+    it("should provide access to CRDT internals via loro()", () => {
       const doc = createTypedDoc(schema)
 
-      // $ should exist
-      expect(doc.$).toBeDefined()
+      // loro(doc) should provide access to CRDT internals
+      expect(loro(doc).doc).toBeDefined()
+      expect(loro(doc).subscribe).toBeDefined()
+      expect(loro(doc).applyPatch).toBeDefined()
+      expect(loro(doc).rawValue).toBeDefined()
+      expect(loro(doc).docShape).toBeDefined()
 
-      // $ should have batch, toJSON, loroDoc, etc.
-      expect(typeof doc.$.change).toBe("function")
+      // doc should have change() and toJSON() directly
+      expect(typeof doc.change).toBe("function")
       expect(typeof doc.toJSON).toBe("function")
-      expect(doc.$.loroDoc).toBeDefined()
     })
 
-    it("should not enumerate $ in Object.keys()", () => {
+    it("should not enumerate internal properties in Object.keys()", () => {
       const doc = createTypedDoc(schema)
 
-      // $ should not appear in Object.keys()
+      // Internal properties should not appear in Object.keys()
       const keys = Object.keys(doc)
-      expect(keys).not.toContain("$")
+      expect(keys).not.toContain("change")
 
       // But schema keys should appear
       expect(keys).toContain("title")
@@ -413,11 +419,11 @@ describe("Grand Unified API v3", () => {
       expect(keys).toContain("items")
     })
 
-    it("should support 'in' operator for $", () => {
+    it("should support 'in' operator for change", () => {
       const doc = createTypedDoc(schema)
 
-      // $ should be accessible via 'in'
-      expect("$" in doc).toBe(true)
+      // change should be accessible via 'in'
+      expect("change" in doc).toBe(true)
     })
   })
 })

package/src/index.ts

@@ -5,7 +5,19 @@ export {
   deriveShapePlaceholder,
 } from "./derive-placeholder.js"
 // Functional helpers (recommended API)
-export { change, getLoroDoc } from "./functional-helpers.js"
+export { change, getLoroContainer, getLoroDoc } from "./functional-helpers.js"
+// The loro() escape hatch for CRDT internals
+export {
+  LORO_SYMBOL,
+  type LoroCounterRef,
+  type LoroListRef,
+  type LoroMapRef,
+  type LoroRefBase,
+  type LoroTextRef,
+  type LoroTreeRef,
+  type LoroTypedDocRef,
+  loro,
+} from "./loro.js"
 export { mergeValue, overlayPlaceholder } from "./overlay.js"
 // Path selector DSL exports
 export { createPathBuilder } from "./path-builder.js"
@@ -44,6 +56,9 @@ export type {
   StructValueShape,
   TextContainerShape,
   TreeContainerShape,
+  // Tree-related types
+  TreeNodeJSON,
+  TreeRefInterface,
   UnionValueShape,
   // Value shapes
   ValueShape,
@@ -56,6 +71,15 @@ export type {
 export { Shape } from "./shape.js"
 export type { TypedDoc } from "./typed-doc.js"
 export { createTypedDoc } from "./typed-doc.js"
+// Typed ref types - for specifying types with the loro() function
+export type { CounterRef } from "./typed-refs/counter-ref.js"
+export type { ListRef } from "./typed-refs/list-ref.js"
+export type { MovableListRef } from "./typed-refs/movable-list-ref.js"
+export type { RecordRef } from "./typed-refs/record-ref.js"
+export type { StructRef } from "./typed-refs/struct-ref.js"
+export type { TextRef } from "./typed-refs/text-ref.js"
+export type { TreeNodeRef } from "./typed-refs/tree-node-ref.js"
+export type { TreeRef } from "./typed-refs/tree-ref.js"
 export type {
   // Type inference - Infer<T> is the recommended unified helper
   Infer,

package/src/json-patch.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from "vitest"
 import { change } from "./functional-helpers.js"
 import type { JsonPatch } from "./json-patch.js"
+import { loro } from "./loro.js"
 import { Shape } from "./shape.js"
 import { createTypedDoc } from "./typed-doc.js"
 
@@ -21,7 +22,8 @@ describe("JSON Patch Integration", () => {
         { op: "add", path: "/metadata/count", value: 42 },
       ]
 
-      const result = typedDoc.$.applyPatch(patch).toJSON()
+      loro(typedDoc).applyPatch(patch)
+      const result = typedDoc.toJSON()
 
       expect(result.metadata.title).toBe("Hello World")
       expect(result.metadata.count).toBe(42)
@@ -39,13 +41,14 @@ describe("JSON Patch Integration", () => {
 
       // First set some values
       change(typedDoc, draft => {
-        draft.config.set("theme", "dark")
-        draft.config.set("debug", false)
+        draft.config.theme = "dark"
+        draft.config.debug = false
       })
 
       const patch: JsonPatch = [{ op: "remove", path: "/config/debug" }]
 
-      const result = typedDoc.$.applyPatch(patch).toJSON()
+      loro(typedDoc).applyPatch(patch)
+      const result = typedDoc.toJSON()
 
       expect(result.config.theme).toBe("dark")
       expect(result.config.debug).toBe(true) // Should fall back to empty state
@@ -63,8 +66,8 @@ describe("JSON Patch Integration", () => {
 
       // Set initial values
       change(typedDoc, draft => {
-        draft.settings.set("language", "fr")
-        draft.settings.set("volume", 75)
+        draft.settings.language = "fr"
+        draft.settings.volume = 75
       })
 
       const patch: JsonPatch = [
@@ -72,7 +75,8 @@ describe("JSON Patch Integration", () => {
         { op: "replace", path: "/settings/volume", value: 100 },
       ]
 
-      const result = typedDoc.$.applyPatch(patch).toJSON()
+      loro(typedDoc).applyPatch(patch)
+      const result = typedDoc.toJSON()
 
       expect(result.settings.language).toBe("es")
       expect(result.settings.volume).toBe(100)
@@ -93,7 +97,8 @@ describe("JSON Patch Integration", () => {
         { op: "add", path: "/items/1", value: "middle" }, // Insert in middle
       ]
 
-      const result = typedDoc.$.applyPatch(patch).toJSON()
+      loro(typedDoc).applyPatch(patch)
+      const result = typedDoc.toJSON()
 
       expect(result.items).toEqual(["first", "middle", "second"])
     })
@@ -116,7 +121,8 @@ describe("JSON Patch Integration", () => {
         { op: "remove", path: "/tasks/1" }, // Remove "task2"
       ]
 
-      const result = typedDoc.$.applyPatch(patch).toJSON()
+      loro(typedDoc).applyPatch(patch)
+      const result = typedDoc.toJSON()
 
       expect(result.tasks).toEqual(["task1", "task3"])
     })
@@ -139,7 +145,8 @@ describe("JSON Patch Integration", () => {
         { op: "replace", path: "/numbers/1", value: 20 },
       ]
 
-      const result = typedDoc.$.applyPatch(patch).toJSON()
+      loro(typedDoc).applyPatch(patch)
+      const result = typedDoc.toJSON()
 
       expect(result.numbers).toEqual([1, 20, 3])
     })
@@ -215,7 +222,8 @@ describe("JSON Patch Integration", () => {
         },
       ]
 
-      const result = typedDoc.$.applyPatch(patch).toJSON()
+      loro(typedDoc).applyPatch(patch)
+      const result = typedDoc.toJSON()
 
       expect(result.user.profile.name).toBe("Alice")
       expect(result.user.profile.settings.theme).toBe("dark")
@@ -253,7 +261,8 @@ describe("JSON Patch Integration", () => {
         },
       ]
 
-      const result = typedDoc.$.applyPatch(patch).toJSON()
+      loro(typedDoc).applyPatch(patch)
+      const result = typedDoc.toJSON()
 
       expect(result.todos).toHaveLength(2)
       expect(result.todos[0]).toEqual({
@@ -288,7 +297,8 @@ describe("JSON Patch Integration", () => {
         { op: "move", from: "/items/0", path: "/items/2" }, // Move "first" to end
       ]
 
-      const result = typedDoc.$.applyPatch(patch).toJSON()
+      loro(typedDoc).applyPatch(patch)
+      const result = typedDoc.toJSON()
 
       expect(result.items).toEqual(["second", "third", "first"])
     })
@@ -312,7 +322,8 @@ describe("JSON Patch Integration", () => {
         { op: "move", from: "/items/0", path: "/items/3" },
       ]
 
-      const result1 = typedDoc.$.applyPatch(patch1).toJSON()
+      loro(typedDoc).applyPatch(patch1)
+      const result1 = typedDoc.toJSON()
       expect(result1.items).toEqual(["B", "C", "D", "A"])
 
       // Reset for next test
@@ -329,7 +340,8 @@ describe("JSON Patch Integration", () => {
         { op: "move", from: "/items/1", path: "/items/3" },
       ]
 
-      const result2 = typedDoc.$.applyPatch(patch2).toJSON()
+      loro(typedDoc).applyPatch(patch2)
+      const result2 = typedDoc.toJSON()
       expect(result2.items).toEqual(["A", "C", "D", "B"])
     })
 
@@ -352,7 +364,8 @@ describe("JSON Patch Integration", () => {
         { op: "copy", from: "/source/1", path: "/target/1" },
       ]
 
-      const result = typedDoc.$.applyPatch(patch).toJSON()
+      loro(typedDoc).applyPatch(patch)
+      const result = typedDoc.toJSON()
 
       expect(result.source).toEqual(["item1", "item2"])
       expect(result.target).toEqual(["item1", "item2"])
@@ -370,7 +383,7 @@ describe("JSON Patch Integration", () => {
       const typedDoc = createTypedDoc(schema)
 
       change(typedDoc, draft => {
-        draft.config.set("version", "2.0.0")
+        draft.config.version = "2.0.0"
       })
 
       const patch: JsonPatch = [
@@ -378,7 +391,8 @@ describe("JSON Patch Integration", () => {
         { op: "replace", path: "/config/version", value: "2.1.0" },
       ]
 
-      const result = typedDoc.$.applyPatch(patch).toJSON()
+      loro(typedDoc).applyPatch(patch)
+      const result = typedDoc.toJSON()
 
       expect(result.config.version).toBe("2.1.0")
     })
@@ -397,7 +411,7 @@ describe("JSON Patch Integration", () => {
       ]
 
       expect(() => {
-        typedDoc.$.applyPatch(patch)
+        loro(typedDoc).applyPatch(patch)
       }).toThrow("JSON Patch test failed at path: /config/version")
     })
   })
@@ -425,7 +439,8 @@ describe("JSON Patch Integration", () => {
         { op: "add", path: "/email", value: "alice@example.com" },
       ]
 
-      const result = typedDoc.$.applyPatch(patch, ["users", "alice"]).toJSON()
+      loro(typedDoc).applyPatch(patch, ["users", "alice"])
+      const result = typedDoc.toJSON()
 
       expect(result.users.alice.name).toBe("Alice Smith")
       expect(result.users.alice.email).toBe("alice@example.com")
@@ -448,7 +463,8 @@ describe("JSON Patch Integration", () => {
         { op: "add", path: "/data/items/1", value: "second" },
       ]
 
-      const result = typedDoc.$.applyPatch(patch).toJSON()
+      loro(typedDoc).applyPatch(patch)
+      const result = typedDoc.toJSON()
 
       expect(result.data.items).toEqual(["first", "second"])
     })
@@ -467,7 +483,8 @@ describe("JSON Patch Integration", () => {
         { op: "add", path: ["data", "items", 1], value: "second" },
       ]
 
-      const result = typedDoc.$.applyPatch(patch).toJSON()
+      loro(typedDoc).applyPatch(patch)
+      const result = typedDoc.toJSON()
 
       expect(result.data.items).toEqual(["first", "second"])
     })
@@ -488,7 +505,7 @@ describe("JSON Patch Integration", () => {
       ]
 
       expect(() => {
-        typedDoc.$.applyPatch(patch)
+        loro(typedDoc).applyPatch(patch)
       }).toThrow("Cannot navigate to path segment: nonexistent")
     })
 
@@ -504,7 +521,7 @@ describe("JSON Patch Integration", () => {
       ]
 
       expect(() => {
-        typedDoc.$.applyPatch(patch)
+        loro(typedDoc).applyPatch(patch)
       }).toThrow("Index out of bound")
     })
   })
@@ -533,7 +550,8 @@ describe("JSON Patch Integration", () => {
         { op: "add", path: "/data/items/1", value: "item2" },
       ]
 
-      const result = typedDoc.$.applyPatch(patch).toJSON()
+      loro(typedDoc).applyPatch(patch)
+      const result = typedDoc.toJSON()
 
       expect(result.counter).toBe(5)
       expect(result.text).toBe("Hello")
@@ -555,14 +573,15 @@ describe("JSON Patch Integration", () => {
         { op: "replace", path: "/settings/theme", value: "dark" },
       ]
 
-      typedDoc.$.applyPatch(patch1)
+      loro(typedDoc).applyPatch(patch1)
 
       // Second patch
       const patch2: JsonPatch = [
         { op: "replace", path: "/settings/language", value: "fr" },
       ]
 
-      const result = typedDoc.$.applyPatch(patch2).toJSON()
+      loro(typedDoc).applyPatch(patch2)
+      const result = typedDoc.toJSON()
 
       expect(result.settings.theme).toBe("dark") // Should persist from first patch
       expect(result.settings.language).toBe("fr")