@loro-extended/change 0.9.1 → 1.0.1

package/README.md

@@ -11,11 +11,11 @@ A schema-driven, type-safe wrapper for [Loro CRDT](https://github.com/loro-dev/l
 Working with Loro directly involves somewhat verbose container operations and complex type management. The `change` package provides:
 
 - **Schema-First Design**: Define your document structure with type-safe schemas
-- **Natural Syntax**: Write `draft.title.insert(0, "Hello")` instead of verbose CRDT operations
+- **Natural Syntax**: Write `doc.title.insert(0, "Hello")` instead of verbose CRDT operations
 - **Empty State Overlay**: Seamlessly blend default values with CRDT state
 - **Full Type Safety**: Complete TypeScript support with compile-time validation
-- **Transactional Changes**: All mutations within a `change()` block are atomic
-- **Loro Compatible**: Works seamlessly with existing Loro code (`typedDoc.loroDoc` is a familiar `LoroDoc`)
+- **Transactional Changes**: All mutations within a `$.batch()` block are atomic
+- **Loro Compatible**: Works seamlessly with existing Loro code (`doc.$.loroDoc` is a familiar `LoroDoc`)
 
 ## Installation
 
@@ -28,35 +28,45 @@ pnpm add @loro-extended/change loro-crdt
 ## Quick Start
 
 ```typescript
-import { TypedDoc, Shape } from "@loro-extended/change";
+import { createTypedDoc, Shape, change } from "@loro-extended/change";
 
 // Define your document schema
 const schema = Shape.doc({
   title: Shape.text().placeholder("My Todo List"),
-  todos: Shape.list(
-    Shape.plain.object({
-      id: Shape.plain.string(),
-      text: Shape.plain.string(),
-      completed: Shape.plain.boolean(),
-    })
-  ),
+  count: Shape.counter(),
+  users: Shape.record(Shape.plain.struct({
+    name: Shape.plain.string(),
+  })),
 });
 
 // Create a typed document
-const doc = new TypedDoc(schema);
+const doc = createTypedDoc(schema);
 
-// Make changes with natural syntax
-const result = doc.change((draft) => {
-  draft.title.insert(0, "📝 Todo");
-  draft.todos.push({
-    id: "1",
-    text: "Learn Loro",
-    completed: false,
-  });
+// Direct mutations - commit immediately (auto-commit mode)
+doc.title.insert(0, "📝 Todo");
+doc.count.increment(5);
+doc.users.set("alice", { name: "Alice" });
+
+// Check existence
+if (doc.users.has("alice")) {
+  console.log("Alice exists!");
+}
+if ("alice" in doc.users) {
+  console.log("Also works with 'in' operator!");
+}
+
+// Batched mutations - commit together (optional, for performance)
+// Using functional helper (recommended)
+change(doc, draft => {
+  draft.title.insert(0, "Change: ");
+  draft.count.increment(10);
+  draft.users.set("bob", { name: "Bob" });
 });
+// All changes commit as one transaction
 
-console.log(result);
-// { title: "📝 Todo", todos: [{ id: "1", text: "Learn Loro", completed: false }] }
+// Get JSON snapshot using functional helper
+console.log(doc.toJSON());
+// { title: "Change: 📝 Todo", count: 15, users: { alice: { name: "Alice" }, bob: { name: "Bob" } } }
 ```
 
 Note that this is even more useful in combination with `@loro-extended/react` (if your app uses React) and `@loro-extended/repo` for syncing between client/server or among peers.
@@ -78,8 +88,8 @@ const blogSchema = Shape.doc({
   // Lists for ordered data
   tags: Shape.list(Shape.plain.string()), // List of strings
 
-  // Maps for structured data
-  metadata: Shape.map({
+  // Structs for structured data with fixed keys
+  metadata: Shape.struct({
     author: Shape.plain.string(), // Plain values (POJOs)
     publishedAt: Shape.plain.string(), // ISO date string
     featured: Shape.plain.boolean(),
@@ -87,7 +97,7 @@ const blogSchema = Shape.doc({
 
   // Movable lists for reorderable content
   sections: Shape.movableList(
-    Shape.map({
+    Shape.struct({
       heading: Shape.text(), // Collaborative headings
       content: Shape.text(), // Collaborative content
       order: Shape.plain.number(), // Plain metadata
@@ -96,7 +106,7 @@ const blogSchema = Shape.doc({
 });
 ```
 
-**NOTE:** Use `Shape.*` for collaborative containers and `Shape.plain.*` for plain values. Only put plain values inside Loro containers - a Loro container inside a plain JS object or array won't work.
+**NOTE:** Use `Shape.*` for collaborative containers and `Shape.plain.*` for plain values. Only put plain values inside Loro containers - a Loro container inside a plain JS struct or array won't work.
 
 ### Empty State Overlay
 
@@ -108,13 +118,13 @@ const blogSchemaWithDefaults = Shape.doc({
   title: Shape.text().placeholder("Untitled Document"),
   viewCount: Shape.counter(), // defaults to 0
   tags: Shape.list(Shape.plain.string()), // defaults to []
-  metadata: Shape.map({
+  metadata: Shape.struct({
     author: Shape.plain.string().placeholder("Anonymous"),
     publishedAt: Shape.plain.string(), // defaults to ""
     featured: Shape.plain.boolean(), // defaults to false
   }),
   sections: Shape.movableList(
-    Shape.map({
+    Shape.struct({
       heading: Shape.text(),
       content: Shape.text(),
       order: Shape.plain.number(),
@@ -122,29 +132,40 @@ const blogSchemaWithDefaults = Shape.doc({
   ),
 });
 
-const doc = new TypedDoc(blogSchemaWithDefaults);
+const doc = createTypedDoc(blogSchemaWithDefaults);
 
 // Initially returns empty state
-console.log(doc.value);
+console.log(doc.toJSON());
 // { title: "Untitled Document", viewCount: 0, ... }
 
 // After changes, CRDT values take priority over empty state
-doc.change((draft) => {
+change(doc, (draft) => {
   draft.title.insert(0, "My Blog Post");
   draft.viewCount.increment(10);
 });
 
-console.log(doc.value);
+console.log(doc.toJSON());
 // { title: "My Blog Post",  viewCount: 10,  tags: [], ... }
 //   ↑ CRDT value            ↑ CRDT value    ↑ empty state preserved
 ```
 
-### The `change()` Function
+### Direct Mutations vs Batched Mutations
 
-All mutations happen within transactional `change()` blocks:
+With the Grand Unified API, schema properties are accessed directly on the doc. Mutations commit immediately by default:
 
 ```typescript
-const result = doc.change((draft) => {
+// Direct mutations - each commits immediately
+doc.title.insert(0, "📝");
+doc.viewCount.increment(1);
+doc.tags.push("typescript");
+```
+
+For batched operations (better performance, atomic undo), use `change()`:
+
+```typescript
+import { change } from "@loro-extended/change";
+
+change(doc, (draft) => {
   // Text operations
   draft.title.insert(0, "📝");
   draft.title.delete(5, 3);
@@ -158,7 +179,7 @@ const result = doc.change((draft) => {
   draft.tags.insert(0, "loro");
   draft.tags.delete(1, 1);
 
-  // Map operations (POJO values)
+  // Struct operations (POJO values)
   draft.metadata.set("author", "John Doe");
   draft.metadata.delete("featured");
 
@@ -171,10 +192,23 @@ const result = doc.change((draft) => {
   draft.sections.move(0, 1); // Reorder sections
 });
 
-// All changes are committed atomically
-console.log(result); // Updated document state
+// All changes are committed atomically as one transaction
+// change() returns the doc for chaining
+console.log(doc.toJSON()); // Updated document state
 ```
 
+### When to Use `change()` vs Direct Mutations
+
+| Use Case | Approach |
+|----------|----------|
+| Single mutation | Direct: `doc.count.increment(1)` |
+| Multiple related mutations | Batched: `change(doc, d => { ... })` |
+| Atomic undo/redo | Batched: `change(doc, d => { ... })` |
+| Performance-critical bulk updates | Batched: `change(doc, d => { ... })` |
+| Simple reads + writes | Direct: `doc.users.set(...)` |
+
+> **Note:** The `$.change()` method is available as an escape hatch, but the functional `change()` helper is recommended for cleaner code.
+
 ## Advanced Usage
 
 ### Discriminated Unions
@@ -185,19 +219,19 @@ For type-safe tagged unions (like different message types or presence states), u
 import { Shape, mergeValue } from "@loro-extended/change";
 
 // Define variant shapes - each must have the discriminant key
-const ClientPresenceShape = Shape.plain.object({
+const ClientPresenceShape = Shape.plain.struct({
   type: Shape.plain.string("client"), // Literal type for discrimination
   name: Shape.plain.string(),
-  input: Shape.plain.object({
+  input: Shape.plain.struct({
     force: Shape.plain.number(),
     angle: Shape.plain.number(),
   }),
 });
 
-const ServerPresenceShape = Shape.plain.object({
+const ServerPresenceShape = Shape.plain.struct({
   type: Shape.plain.string("server"), // Literal type for discrimination
   cars: Shape.plain.record(
-    Shape.plain.object({
+    Shape.plain.struct({
       x: Shape.plain.number(),
       y: Shape.plain.number(),
     })
@@ -253,11 +287,11 @@ Handle complex nested documents with ease:
 
 ```typescript
 const complexSchema = Shape.doc({
-  article: Shape.map({
+  article: Shape.struct({
     title: Shape.text(),
-    metadata: Shape.map({
+    metadata: Shape.struct({
       views: Shape.counter(),
-      author: Shape.map({
+      author: Shape.struct({
         name: Shape.plain.string(),
         email: Shape.plain.string(),
       }),
@@ -278,9 +312,9 @@ const emptyState = {
   },
 };
 
-const doc = new TypedDoc(complexSchema, emptyState);
+const doc = createTypedDoc(complexSchema);
 
-doc.change((draft) => {
+change(doc, (draft) => {
   draft.article.title.insert(0, "Deep Nesting Example");
   draft.article.metadata.views.increment(5);
   draft.article.metadata.author.name = "Alice"; // plain string update is captured and applied after closure
@@ -288,20 +322,20 @@ doc.change((draft) => {
 });
 ```
 
-### Map Operations
+### Struct Operations
 
-For map containers, use the standard map methods:
+For struct containers (fixed-key objects), use direct property access:
 
 ```typescript
 const schema = Shape.doc({
-  settings: Shape.map({
+  settings: Shape.struct({
     theme: Shape.plain.string(),
     collapsed: Shape.plain.boolean(),
     width: Shape.plain.number(),
   }),
 });
 
-doc.change((draft) => {
+change(doc, (draft) => {
   // Set individual values
   draft.settings.theme = "dark";
   draft.settings.collapsed = true;
@@ -316,11 +350,11 @@ Create lists containing CRDT containers for collaborative nested structures:
 ```typescript
 const collaborativeSchema = Shape.doc({
   articles: Shape.list(
-    Shape.map({
+    Shape.struct({
       title: Shape.text(), // Collaborative title
       content: Shape.text(), // Collaborative content
       tags: Shape.list(Shape.plain.string()), // Collaborative tag list
-      metadata: Shape.plain.object({
+      metadata: Shape.plain.struct({
         // Static metadata
         authorId: Shape.plain.string(),
         publishedAt: Shape.plain.string(),
@@ -329,7 +363,7 @@ const collaborativeSchema = Shape.doc({
   ),
 });
 
-doc.change((draft) => {
+change(doc, (draft) => {
   // Push creates and configures nested containers automatically
   draft.articles.push({
     title: "Collaborative Article",
@@ -352,22 +386,77 @@ doc.change((draft) => {
 
 ### Core Functions
 
-#### `new TypedDoc<T>(schema, existingDoc?)`
+#### `createTypedDoc<T>(schema, existingDoc?)`
+
+Creates a new typed Loro document. This is the recommended way to create documents.
+
+```typescript
+import { createTypedDoc, Shape } from "@loro-extended/change";
+
+const doc = createTypedDoc(schema);
+const docFromExisting = createTypedDoc(schema, existingLoroDoc);
+```
+
+#### `new TypedDoc<T>(schema, existingDoc?)` *(deprecated)*
 
-Creates a new typed Loro document.
+Constructor-style API. Use `createTypedDoc()` instead for cleaner code.
 
 ```typescript
+// Deprecated - use createTypedDoc() instead
 const doc = new TypedDoc(schema);
-const docFromExisting = new TypedDoc(schema, existingLoroDoc);
 ```
 
-#### `doc.change(mutator)`
+### Functional Helpers (Recommended)
 
-Applies transactional changes to a document.
+These functional helpers provide a cleaner API and are the recommended way to work with TypedDoc:
+
+#### `change(doc, mutator)`
+
+Batches multiple mutations into a single transaction. Returns the doc for chaining.
 
 ```typescript
-const result = doc.change((draft) => {
-  // Make changes to draft
+import { change } from "@loro-extended/change";
+
+change(doc, (draft) => {
+  draft.title.insert(0, "Hello");
+  draft.count.increment(5);
+});
+
+// Chainable - change returns the doc
+change(doc, d => d.count.increment(1)).count.increment(2);
+```
+
+#### `doc.toJSON()`
+
+Returns the full plain JavaScript object representation of the document.
+
+```typescript
+const snapshot = doc.toJSON();
+// { title: "Hello", count: 5, ... }
+```
+
+#### `getLoroDoc(doc)`
+
+Access the underlying LoroDoc for advanced operations.
+
+```typescript
+import { getLoroDoc } from "@loro-extended/change";
+
+const loroDoc = getLoroDoc(doc);
+loroDoc.subscribe((event) => console.log("Changed:", event));
+```
+
+### $ Namespace (Escape Hatch)
+
+The `$` namespace provides access to meta-operations. While functional helpers are recommended, the `$` namespace is available for advanced use cases:
+
+#### `doc.$.change(mutator)`
+
+Same as `change(doc, mutator)`.
+
+```typescript
+doc.$.change((draft) => {
+  // Make changes to draft - all commit together
 });
 ```
 
@@ -390,7 +479,7 @@ const schema = Shape.doc({
 - `Shape.counter()` - Collaborative increment/decrement counters
 - `Shape.list(itemSchema)` - Collaborative ordered lists
 - `Shape.movableList(itemSchema)` - Collaborative reorderable lists
-- `Shape.map(shape)` - Collaborative key-value maps with fixed keys
+- `Shape.struct(shape)` - Collaborative structs with fixed keys (uses LoroMap internally)
 - `Shape.record(valueSchema)` - Collaborative key-value maps with dynamic string keys
 - `Shape.tree(shape)` - Collaborative hierarchical tree structures (Note: incomplete implementation)
 
@@ -402,45 +491,60 @@ const schema = Shape.doc({
 - `Shape.plain.null()` - Null values
 - `Shape.plain.undefined()` - Undefined values
 - `Shape.plain.uint8Array()` - Binary data values
-- `Shape.plain.object(shape)` - Object values with fixed keys
+- `Shape.plain.struct(shape)` - Struct values with fixed keys
 - `Shape.plain.record(valueShape)` - Object values with dynamic string keys
 - `Shape.plain.array(itemShape)` - Array values
 - `Shape.plain.union(shapes)` - Union of value types (e.g., `string | null`)
 - `Shape.plain.discriminatedUnion(key, variants)` - Tagged union types with a discriminant key
 
-### TypedDoc Methods
+### TypedDoc API
+
+With the proxy-based API, schema properties are accessed directly on the doc object, and meta-operations are accessed via the `$` namespace.
 
-#### `.value`
+#### Direct Schema Access
 
-Returns the current document state with empty state overlay.
+Access schema properties directly on the doc. Mutations commit immediately (auto-commit mode).
 
 ```typescript
-const currentState = doc.value;
+// Read values
+const title = doc.title.toString();
+const count = doc.count.value;
+
+// Mutate directly - commits immediately
+doc.title.insert(0, "Hello");
+doc.count.increment(5);
+doc.users.set("alice", { name: "Alice" });
+
+// Check existence
+doc.users.has("alice"); // true
+"alice" in doc.users;   // true
 ```
 
-This overlays "empty state" defaults with CRDT values, returning a JSON object with full type information (from your schema).
+For batched mutations, use `$.change()` instead.
 
-#### `.rawValue`
+#### `doc.$.toJSON()`
 
-Returns raw CRDT state without empty state overlay.
+Same as `doc.toJSON`. Returns the full plain JavaScript object representation.
 
 ```typescript
-const crdtState = doc.rawValue;
+const snapshot = doc.$.toJSON();
 ```
 
-#### `.loroDoc`
+#### `doc.$.rawValue`
 
-Access the underlying LoroDoc for advanced operations.
+Returns raw CRDT state without empty state overlay.
 
 ```typescript
-const loroDoc = doc.loroDoc;
-
-const foods = loroDoc.getMap("foods");
-const drinks = loroDoc.getOrCreateContainer("drinks", new LoroMap());
-// etc.
+const crdtState = doc.$.rawValue;
 ```
 
-You may need this when interfacing with other libraries, such as `loro-dev/loro-prosemirror`.
+#### `doc.$.loroDoc`
+
+Same as `getLoroDoc(doc)`. Access the underlying LoroDoc.
+
+```typescript
+const loroDoc = doc.$.loroDoc;
+```
 
 ## CRDT Container Operations
 
@@ -505,7 +609,7 @@ draft.todos.forEach((todo, index) => {
 **Important**: Methods like `find()` and `filter()` return **mutable draft objects** that you can modify directly:
 
 ```typescript
-doc.change((draft) => {
+change(doc, (draft) => {
   // Find and mutate pattern - very common!
   const todo = draft.todos.find((t) => t.id === "123");
   if (todo) {
@@ -553,16 +657,16 @@ You can easily get a plain JavaScript object snapshot of any part of the documen
 
 ```typescript
 // Get full document snapshot
-const snapshot = doc.toJSON();
+const snapshot = doc.$.toJSON();
 
 // Get snapshot of a specific list
-const todos = doc.value.todos.toJSON(); // returns plain array of todos
+const todos = doc.todos.toJSON(); // returns plain array of todos
 
 // Works with nested structures
-const metadata = doc.value.metadata.toJSON(); // returns plain object
+const metadata = doc.metadata.toJSON(); // returns plain object
 
 // Serialize as JSON
-const serializedMetadata = JSON.stringify(doc.value.metadata); // returns string
+const serializedMetadata = JSON.stringify(doc.metadata); // returns string
 ```
 
 **Note:** `JSON.stringify()` is recommended for serialization as it handles all data types correctly. `.toJSON()` is available on all `TypedRef` objects and proxied placeholders for convenience when you need a direct object snapshot.
@@ -584,7 +688,7 @@ interface TodoDoc {
 const todoSchema = Shape.doc({
   title: Shape.text(),
   todos: Shape.list(
-    Shape.plain.object({
+    Shape.plain.struct({
       id: Shape.plain.string(),
       text: Shape.plain.string(),
       done: Shape.plain.boolean(),
@@ -593,10 +697,10 @@ const todoSchema = Shape.doc({
 });
 
 // TypeScript will ensure the schema produces the correct type
-const doc = new TypedDoc(todoSchema);
+const doc = createTypedDoc(todoSchema);
 
-// The result will be properly typed as TodoDoc
-const result: TodoDoc = doc.change((draft) => {
+// Mutations are type-safe
+change(doc, (draft) => {
   draft.title.insert(0, "Hello"); // ✅ Valid - TypeScript knows this is LoroText
   draft.todos.push({
     // ✅ Valid - TypeScript knows the expected shape
@@ -609,6 +713,9 @@ const result: TodoDoc = doc.change((draft) => {
   // draft.todos.push({ invalid: true }); // ❌ TypeScript error
 });
 
+// The result is properly typed as TodoDoc
+const result: TodoDoc = doc.toJSON();
+
 // You can also use type assertion to ensure schema compatibility
 type SchemaType = InferPlainType<typeof todoSchema>;
 const _typeCheck: TodoDoc = {} as SchemaType; // ✅ Will error if types don't match
@@ -622,13 +729,14 @@ const _typeCheck: TodoDoc = {} as SchemaType; // ✅ Will error if types don't m
 
 ```typescript
 import { LoroDoc } from "loro-crdt";
+import { createTypedDoc, getLoroDoc } from "@loro-extended/change";
 
 // Wrap existing LoroDoc
 const existingDoc = new LoroDoc();
-const typedDoc = new TypedDoc(schema, existingDoc);
+const typedDoc = createTypedDoc(schema, existingDoc);
 
 // Access underlying LoroDoc
-const loroDoc = typedDoc.loroDoc;
+const loroDoc = getLoroDoc(typedDoc);
 
 // Use with existing Loro APIs
 loroDoc.subscribe((event) => {
@@ -644,8 +752,8 @@ The `TypedPresence` class provides type-safe access to ephemeral presence data w
 import { TypedPresence, Shape } from "@loro-extended/change";
 
 // Define a presence schema with placeholders
-const PresenceSchema = Shape.plain.object({
-  cursor: Shape.plain.object({
+const PresenceSchema = Shape.plain.struct({
+  cursor: Shape.plain.struct({
     x: Shape.plain.number(),
     y: Shape.plain.number(),
   }),
@@ -696,7 +804,7 @@ This is typically provided by `UntypedDocHandle.presence` in `@loro-extended/rep
 
 ## Performance Considerations
 
-- All changes within a `change()` block are batched into a single transaction
+- All changes within a `change()` call are batched into a single transaction
 - Empty state overlay is computed on-demand, not stored
 - Container creation is lazy - containers are only created when accessed
 - Type validation occurs at development time, not runtime