@loro-extended/change 1.0.1 → 2.0.0

package/README.md

@@ -34,9 +34,11 @@ import { createTypedDoc, Shape, change } from "@loro-extended/change";
 const schema = Shape.doc({
   title: Shape.text().placeholder("My Todo List"),
   count: Shape.counter(),
-  users: Shape.record(Shape.plain.struct({
-    name: Shape.plain.string(),
-  })),
+  users: Shape.record(
+    Shape.plain.struct({
+      name: Shape.plain.string(),
+    })
+  ),
 });
 
 // Create a typed document
@@ -57,7 +59,7 @@ if ("alice" in doc.users) {
 
 // Batched mutations - commit together (optional, for performance)
 // Using functional helper (recommended)
-change(doc, draft => {
+change(doc, (draft) => {
   draft.title.insert(0, "Change: ");
   draft.count.increment(10);
   draft.users.set("bob", { name: "Bob" });
@@ -199,13 +201,13 @@ 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 => { ... })` |
+| 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(...)` |
+| 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.
 
@@ -276,11 +278,73 @@ function handlePresence(presence: typeof result) {
 ```
 
 **Key features:**
+
 - The discriminant key (e.g., `"type"`) determines which variant shape to use
 - Missing fields are filled from the empty state of the matching variant
-- Works seamlessly with `@loro-extended/react`'s `usePresence` hook
+- Works seamlessly with `@loro-extended/react`'s `useEphemeral` hook
 - Full TypeScript support for discriminated union types
 
+### Untyped Integration with External Libraries
+
+When integrating with external libraries that manage their own document structure (like `loro-prosemirror`), you may want typed presence but untyped document content. Use `Shape.any()` as an escape hatch:
+
+```typescript
+import { Shape } from "@loro-extended/change";
+
+// Fully typed presence with binary cursor data
+const CursorPresenceSchema = Shape.plain.struct({
+  anchor: Shape.plain.bytes().nullable(), // Uint8Array | null
+  focus: Shape.plain.bytes().nullable(),
+  user: Shape.plain
+    .struct({
+      name: Shape.plain.string(),
+      color: Shape.plain.string(),
+    })
+    .nullable(),
+});
+
+// With @loro-extended/repo:
+
+// Option 1: Shape.any() directly - entire document is untyped
+const handle = repo.get(docId, Shape.any(), { presence: CursorPresenceSchema });
+handle.loroDoc; // Raw LoroDoc - use Loro API directly
+handle.loroDoc.getMap("anything").set("key", "value");
+handle.presence.setSelf({
+  // Typed presence
+  anchor: cursor.encode(), // Uint8Array directly
+  focus: null,
+  user: { name: "Alice", color: "#ff0000" },
+});
+
+// Option 2: Shape.any() in a container - one container is untyped
+const ProseMirrorDocShape = Shape.doc({
+  doc: Shape.any(), // loro-prosemirror manages this
+  metadata: Shape.struct({
+    // But we can still have typed containers
+    title: Shape.text(),
+  }),
+});
+const handle2 = repo.get(docId, ProseMirrorDocShape, { presence: CursorPresenceSchema });
+handle2.doc.toJSON(); // { doc: unknown, metadata: { title: string } }
+```
+
+**Key features:**
+
+- `Shape.any()` creates an `AnyContainerShape` - type inference produces `unknown`
+- `Shape.plain.any()` creates an `AnyValueShape` - type inference produces Loro's `Value` type
+- `Shape.plain.bytes()` is an alias for `Shape.plain.uint8Array()` for better discoverability
+- All support `.nullable()` for optional values
+
+**When to use:**
+
+| Scenario                                    | Shape to Use                                                       |
+| ------------------------------------------- | ------------------------------------------------------------------ |
+| External library manages entire document    | `repo.get(docId, Shape.any(), { presence: presenceSchema })`       |
+| External library manages one container      | `Shape.doc({ doc: Shape.any(), ... })`                             |
+| Flexible metadata in presence               | `Shape.plain.any()` for dynamic values                             |
+| Binary cursor/selection data                | `Shape.plain.bytes().nullable()` for `Uint8Array` \| `null`        |
+| Full type safety                            | Use specific shapes like `Shape.struct()`, `Shape.text()`          |
+
 ### Nested Structures
 
 Handle complex nested documents with ease:
@@ -382,6 +446,31 @@ change(doc, (draft) => {
 });
 ```
 
+## Path Selector DSL
+
+The `@loro-extended/change` package exports a type-safe path selector DSL for building (a subset of) JSONPath expressions with full TypeScript type inference. This is primarily used by `Handle.subscribe()` in `@loro-extended/repo` for efficient, type-safe subscriptions:
+
+```typescript
+// In @loro-extended/repo, use with Handle.subscribe():
+handle.subscribe(
+  (p) => p.books.$each.title, // Type-safe path selector
+  (titles, prev) => {
+    // titles: string[], prev: string[] | undefined
+    console.log("Titles changed:", titles);
+  }
+);
+
+// DSL constructs:
+// p.config.theme        - Property access
+// p.books.$each         - All items in list/record
+// p.books.$at(0)        - Item at index (supports negative: -1 = last)
+// p.books.$first        - First item (alias for $at(0))
+// p.books.$last         - Last item (alias for $at(-1))
+// p.users.$key("alice") - Record value by key
+```
+
+See `@loro-extended/repo` documentation for full details on `Handle.subscribe()`.
+
 ## API Reference
 
 ### Core Functions
@@ -397,7 +486,7 @@ const doc = createTypedDoc(schema);
 const docFromExisting = createTypedDoc(schema, existingLoroDoc);
 ```
 
-#### `new TypedDoc<T>(schema, existingDoc?)` *(deprecated)*
+#### `new TypedDoc<T>(schema, existingDoc?)` _(deprecated)_
 
 Constructor-style API. Use `createTypedDoc()` instead for cleaner code.
 
@@ -423,7 +512,7 @@ change(doc, (draft) => {
 });
 
 // Chainable - change returns the doc
-change(doc, d => d.count.increment(1)).count.increment(2);
+change(doc, (d) => d.count.increment(1)).count.increment(2);
 ```
 
 #### `doc.toJSON()`
@@ -482,6 +571,7 @@ const schema = Shape.doc({
 - `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)
+- `Shape.any()` - Escape hatch for untyped containers (see [Untyped Integration](#untyped-integration-with-external-libraries))
 
 #### Value Types
 
@@ -491,11 +581,58 @@ const schema = Shape.doc({
 - `Shape.plain.null()` - Null values
 - `Shape.plain.undefined()` - Undefined values
 - `Shape.plain.uint8Array()` - Binary data values
+- `Shape.plain.bytes()` - Alias for `uint8Array()` for better discoverability
 - `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
+- `Shape.plain.any()` - Escape hatch for untyped values (see [Untyped Integration](#untyped-integration-with-external-libraries))
+
+#### Nullable Values
+
+Use `.nullable()` on value types to create nullable fields with `null` as the default placeholder:
+
+```typescript
+const schema = Shape.doc({
+  profile: Shape.struct({
+    name: Shape.plain.string().placeholder("Anonymous"),
+    email: Shape.plain.string().nullable(), // string | null, defaults to null
+    age: Shape.plain.number().nullable(), // number | null, defaults to null
+    verified: Shape.plain.boolean().nullable(), // boolean | null, defaults to null
+    tags: Shape.plain.array(Shape.plain.string()).nullable(), // string[] | null
+    metadata: Shape.plain.record(Shape.plain.string()).nullable(), // Record<string, string> | null
+    location: Shape.plain
+      .struct({
+        // { lat: number, lng: number } | null
+        lat: Shape.plain.number(),
+        lng: Shape.plain.number(),
+      })
+      .nullable(),
+  }),
+});
+```
+
+You can chain `.placeholder()` after `.nullable()` to customize the default value:
+
+```typescript
+const schema = Shape.doc({
+  settings: Shape.struct({
+    // Nullable string with custom default
+    nickname: Shape.plain.string().nullable().placeholder("Guest"),
+  }),
+});
+```
+
+This is syntactic sugar for the more verbose union pattern:
+
+```typescript
+// These are equivalent:
+email: Shape.plain.string().nullable();
+email: Shape.plain
+  .union([Shape.plain.null(), Shape.plain.string()])
+  .placeholder(null);
+```
 
 ### TypedDoc API
 
@@ -517,7 +654,7 @@ doc.users.set("alice", { name: "Alice" });
 
 // Check existence
 doc.users.has("alice"); // true
-"alice" in doc.users;   // true
+"alice" in doc.users; // true
 ```
 
 For batched mutations, use `$.change()` instead.
@@ -744,12 +881,12 @@ loroDoc.subscribe((event) => {
 });
 ```
 
-## TypedPresence
+## TypedEphemeral (Presence)
 
-The `TypedPresence` class provides type-safe access to ephemeral presence data with placeholder defaults:
+The `TypedEphemeral` interface in `@loro-extended/repo` provides type-safe access to ephemeral presence data with placeholder defaults. Define your presence schema and use it with `repo.get()`:
 
 ```typescript
-import { TypedPresence, Shape } from "@loro-extended/change";
+import { Shape } from "@loro-extended/change";
 
 // Define a presence schema with placeholders
 const PresenceSchema = Shape.plain.struct({
@@ -761,46 +898,28 @@ const PresenceSchema = Shape.plain.struct({
   status: Shape.plain.string().placeholder("online"),
 });
 
-// Create typed presence from a PresenceInterface
-// (Usually obtained from handle.presence in @loro-extended/repo)
-const typedPresence = new TypedPresence(PresenceSchema, presenceInterface);
+// Use with @loro-extended/repo
+const handle = repo.get("doc-id", DocSchema, { presence: PresenceSchema });
 
 // Read your presence (with placeholder defaults merged in)
-console.log(typedPresence.self);
+console.log(handle.presence.self);
 // { cursor: { x: 0, y: 0 }, name: "Anonymous", status: "online" }
 
 // Set presence values
-typedPresence.set({ cursor: { x: 100, y: 200 }, name: "Alice" });
+handle.presence.setSelf({ cursor: { x: 100, y: 200 }, name: "Alice" });
 
-// Read all peers' presence
-console.log(typedPresence.all);
-// { "peer-1": { cursor: { x: 100, y: 200 }, name: "Alice", status: "online" } }
+// Read other peers' presence
+for (const [peerId, presence] of handle.presence.peers) {
+  console.log(`${peerId}: ${presence.name}`);
+}
 
 // Subscribe to presence changes
-typedPresence.subscribe(({ self, all }) => {
-  console.log("My presence:", self);
-  console.log("All peers:", all);
+handle.presence.subscribe(({ key, value, source }) => {
+  console.log(`Peer ${key} updated:`, value);
 });
 ```
 
-### PresenceInterface
-
-`TypedPresence` works with any object implementing `PresenceInterface`:
-
-```typescript
-import type { PresenceInterface, ObjectValue } from "@loro-extended/change";
-
-interface PresenceInterface {
-  set: (values: ObjectValue) => void;
-  get: (key: string) => Value;
-  readonly self: ObjectValue;
-  readonly all: Record<string, ObjectValue>;
-  setRaw: (key: string, value: Value) => void;
-  subscribe: (cb: (values: ObjectValue) => void) => () => void;
-}
-```
-
-This is typically provided by `UntypedDocHandle.presence` in `@loro-extended/repo`.
+See `@loro-extended/repo` documentation for full details on the `TypedEphemeral` interface.
 
 ## Performance Considerations