@loro-extended/change 1.1.0 → 3.0.0

package/src/path-selector.test.ts

@@ -0,0 +1,322 @@
+import { describe, expect, it } from "vitest"
+import { createPathBuilder } from "./path-builder.js"
+import { compileToJsonPath, hasWildcard } from "./path-compiler.js"
+import { evaluatePathOnValue } from "./path-evaluator.js"
+import { Shape } from "./shape.js"
+
+describe("Path Selector DSL", () => {
+  const docShape = Shape.doc({
+    books: Shape.list(
+      Shape.struct({
+        title: Shape.text(),
+        price: Shape.plain.number(),
+        author: Shape.struct({
+          name: Shape.plain.string(),
+        }),
+      }),
+    ),
+    config: Shape.struct({
+      theme: Shape.plain.string(),
+    }),
+    users: Shape.record(
+      Shape.struct({
+        name: Shape.plain.string(),
+        score: Shape.counter(),
+      }),
+    ),
+  })
+
+  describe("createPathBuilder", () => {
+    it("should create a path builder for a doc shape", () => {
+      const builder = createPathBuilder(docShape)
+      expect(builder).toBeDefined()
+      expect(builder.books).toBeDefined()
+      expect(builder.config).toBeDefined()
+      expect(builder.users).toBeDefined()
+    })
+
+    it("should create path segments for simple property access", () => {
+      const builder = createPathBuilder(docShape)
+      const selector = builder.config.theme
+      expect(selector.__segments).toEqual([
+        { type: "property", key: "config" },
+        { type: "property", key: "theme" },
+      ])
+    })
+
+    it("should create path segments for $each on lists", () => {
+      const builder = createPathBuilder(docShape)
+      const selector = builder.books.$each.title
+      expect(selector.__segments).toEqual([
+        { type: "property", key: "books" },
+        { type: "each" },
+        { type: "property", key: "title" },
+      ])
+    })
+
+    it("should create path segments for $at on lists", () => {
+      const builder = createPathBuilder(docShape)
+      const selector = builder.books.$at(0).title
+      expect(selector.__segments).toEqual([
+        { type: "property", key: "books" },
+        { type: "index", index: 0 },
+        { type: "property", key: "title" },
+      ])
+    })
+
+    it("should create path segments for $first and $last", () => {
+      const builder = createPathBuilder(docShape)
+
+      const firstSelector = builder.books.$first.title
+      expect(firstSelector.__segments).toEqual([
+        { type: "property", key: "books" },
+        { type: "index", index: 0 },
+        { type: "property", key: "title" },
+      ])
+
+      const lastSelector = builder.books.$last.title
+      expect(lastSelector.__segments).toEqual([
+        { type: "property", key: "books" },
+        { type: "index", index: -1 },
+        { type: "property", key: "title" },
+      ])
+    })
+
+    it("should create path segments for $each on records", () => {
+      const builder = createPathBuilder(docShape)
+      const selector = builder.users.$each.name
+      expect(selector.__segments).toEqual([
+        { type: "property", key: "users" },
+        { type: "each" },
+        { type: "property", key: "name" },
+      ])
+    })
+
+    it("should create path segments for $key on records", () => {
+      const builder = createPathBuilder(docShape)
+      const selector = builder.users.$key("alice").name
+      expect(selector.__segments).toEqual([
+        { type: "property", key: "users" },
+        { type: "key", key: "alice" },
+        { type: "property", key: "name" },
+      ])
+    })
+
+    it("should support nested struct access", () => {
+      const builder = createPathBuilder(docShape)
+      const selector = builder.books.$each.author.name
+      expect(selector.__segments).toEqual([
+        { type: "property", key: "books" },
+        { type: "each" },
+        { type: "property", key: "author" },
+        { type: "property", key: "name" },
+      ])
+    })
+  })
+
+  describe("compileToJsonPath", () => {
+    it("should compile simple property path", () => {
+      const segments = [
+        { type: "property" as const, key: "config" },
+        { type: "property" as const, key: "theme" },
+      ]
+      expect(compileToJsonPath(segments)).toBe("$.config.theme")
+    })
+
+    it("should compile path with wildcard", () => {
+      const segments = [
+        { type: "property" as const, key: "books" },
+        { type: "each" as const },
+        { type: "property" as const, key: "title" },
+      ]
+      expect(compileToJsonPath(segments)).toBe("$.books[*].title")
+    })
+
+    it("should compile path with index", () => {
+      const segments = [
+        { type: "property" as const, key: "books" },
+        { type: "index" as const, index: 0 },
+        { type: "property" as const, key: "title" },
+      ]
+      expect(compileToJsonPath(segments)).toBe("$.books[0].title")
+    })
+
+    it("should compile path with negative index", () => {
+      const segments = [
+        { type: "property" as const, key: "books" },
+        { type: "index" as const, index: -1 },
+        { type: "property" as const, key: "title" },
+      ]
+      expect(compileToJsonPath(segments)).toBe("$.books[-1].title")
+    })
+
+    it("should compile path with key", () => {
+      const segments = [
+        { type: "property" as const, key: "users" },
+        { type: "key" as const, key: "alice" },
+        { type: "property" as const, key: "name" },
+      ]
+      expect(compileToJsonPath(segments)).toBe('$.users["alice"].name')
+    })
+
+    it("should use bracket notation for special characters", () => {
+      const segments = [{ type: "property" as const, key: "my-key" }]
+      expect(compileToJsonPath(segments)).toBe('$["my-key"]')
+    })
+  })
+
+  describe("hasWildcard", () => {
+    it("should return true for paths with $each", () => {
+      const segments = [
+        { type: "property" as const, key: "books" },
+        { type: "each" as const },
+        { type: "property" as const, key: "title" },
+      ]
+      expect(hasWildcard(segments)).toBe(true)
+    })
+
+    it("should return false for paths without $each", () => {
+      const segments = [
+        { type: "property" as const, key: "config" },
+        { type: "property" as const, key: "theme" },
+      ]
+      expect(hasWildcard(segments)).toBe(false)
+    })
+
+    it("should return false for paths with index", () => {
+      const segments = [
+        { type: "property" as const, key: "books" },
+        { type: "index" as const, index: 0 },
+        { type: "property" as const, key: "title" },
+      ]
+      expect(hasWildcard(segments)).toBe(false)
+    })
+  })
+
+  describe("evaluatePathOnValue", () => {
+    const testData = {
+      books: [
+        { title: "Book 1", price: 10, author: { name: "Author 1" } },
+        { title: "Book 2", price: 20, author: { name: "Author 2" } },
+        { title: "Book 3", price: 30, author: { name: "Author 3" } },
+      ],
+      config: { theme: "dark" },
+      users: {
+        alice: { name: "Alice", score: 100 },
+        bob: { name: "Bob", score: 200 },
+      },
+    }
+
+    it("should evaluate simple property path", () => {
+      const segments = [
+        { type: "property" as const, key: "config" },
+        { type: "property" as const, key: "theme" },
+      ]
+      expect(evaluatePathOnValue(testData, segments)).toBe("dark")
+    })
+
+    it("should evaluate path with wildcard on array", () => {
+      const segments = [
+        { type: "property" as const, key: "books" },
+        { type: "each" as const },
+        { type: "property" as const, key: "title" },
+      ]
+      expect(evaluatePathOnValue(testData, segments)).toEqual([
+        "Book 1",
+        "Book 2",
+        "Book 3",
+      ])
+    })
+
+    it("should evaluate path with positive index", () => {
+      const segments = [
+        { type: "property" as const, key: "books" },
+        { type: "index" as const, index: 1 },
+        { type: "property" as const, key: "title" },
+      ]
+      expect(evaluatePathOnValue(testData, segments)).toBe("Book 2")
+    })
+
+    it("should evaluate path with negative index", () => {
+      const segments = [
+        { type: "property" as const, key: "books" },
+        { type: "index" as const, index: -1 },
+        { type: "property" as const, key: "title" },
+      ]
+      expect(evaluatePathOnValue(testData, segments)).toBe("Book 3")
+
+      const segments2 = [
+        { type: "property" as const, key: "books" },
+        { type: "index" as const, index: -2 },
+        { type: "property" as const, key: "title" },
+      ]
+      expect(evaluatePathOnValue(testData, segments2)).toBe("Book 2")
+    })
+
+    it("should evaluate path with key on record", () => {
+      const segments = [
+        { type: "property" as const, key: "users" },
+        { type: "key" as const, key: "alice" },
+        { type: "property" as const, key: "name" },
+      ]
+      expect(evaluatePathOnValue(testData, segments)).toBe("Alice")
+    })
+
+    it("should evaluate path with wildcard on record", () => {
+      const segments = [
+        { type: "property" as const, key: "users" },
+        { type: "each" as const },
+        { type: "property" as const, key: "name" },
+      ]
+      const result = evaluatePathOnValue(testData, segments) as string[]
+      expect(result).toContain("Alice")
+      expect(result).toContain("Bob")
+    })
+
+    it("should evaluate nested path through wildcard", () => {
+      const segments = [
+        { type: "property" as const, key: "books" },
+        { type: "each" as const },
+        { type: "property" as const, key: "author" },
+        { type: "property" as const, key: "name" },
+      ]
+      expect(evaluatePathOnValue(testData, segments)).toEqual([
+        "Author 1",
+        "Author 2",
+        "Author 3",
+      ])
+    })
+
+    it("should return undefined for missing property", () => {
+      const segments = [{ type: "property" as const, key: "nonexistent" }]
+      expect(evaluatePathOnValue(testData, segments)).toBeUndefined()
+    })
+
+    it("should return undefined for out-of-bounds index", () => {
+      const segments = [
+        { type: "property" as const, key: "books" },
+        { type: "index" as const, index: 10 },
+        { type: "property" as const, key: "title" },
+      ]
+      expect(evaluatePathOnValue(testData, segments)).toBeUndefined()
+    })
+
+    it("should return undefined for out-of-bounds negative index", () => {
+      const segments = [
+        { type: "property" as const, key: "books" },
+        { type: "index" as const, index: -10 },
+        { type: "property" as const, key: "title" },
+      ]
+      expect(evaluatePathOnValue(testData, segments)).toBeUndefined()
+    })
+
+    it("should return empty array for wildcard on empty array", () => {
+      const segments = [
+        { type: "property" as const, key: "books" },
+        { type: "each" as const },
+        { type: "property" as const, key: "title" },
+      ]
+      expect(evaluatePathOnValue({ books: [] }, segments)).toEqual([])
+    })
+  })
+})

package/src/path-selector.ts

@@ -0,0 +1,131 @@
+// ============================================================================
+// Type-Safe Path Selector DSL
+// ============================================================================
+//
+// This module provides type definitions for a type-safe path selector DSL
+// that compiles to JSONPath strings for WASM-side filtering.
+//
+// See plans/typed-path-selector-dsl.md for full design documentation.
+
+import type {
+  ContainerOrValueShape,
+  CounterContainerShape,
+  DocShape,
+  ListContainerShape,
+  MovableListContainerShape,
+  RecordContainerShape,
+  StructContainerShape,
+  TextContainerShape,
+  ValueShape,
+} from "./shape.js"
+import type { Infer } from "./types.js"
+
+// ============================================================================
+// Path Segment Types
+// ============================================================================
+
+export type PathSegment =
+  | { type: "property"; key: string }
+  | { type: "each" } // Wildcard for arrays/records
+  | { type: "index"; index: number } // Specific array index (supports negative)
+  | { type: "key"; key: string } // Specific record key
+
+// ============================================================================
+// Path Selector (carries type and segments)
+// ============================================================================
+
+export interface PathSelector<T> {
+  readonly __resultType: T // Phantom type for inference
+  readonly __segments: PathSegment[] // Runtime path data
+}
+
+// ============================================================================
+// Path Node Types (for each container type)
+// ============================================================================
+
+// List path node - InArray tracks if we're inside a wildcard
+interface ListPathNode<
+  Item extends ContainerOrValueShape,
+  InArray extends boolean,
+> extends PathSelector<WrapType<Infer<Item>[], InArray>> {
+  /** Select all items (wildcard) - sets InArray to true for children */
+  readonly $each: PathNode<Item, true>
+  /** Select item at specific index (supports negative indices: -1 = last, -2 = second-to-last, etc.) */
+  $at(index: number): PathNode<Item, InArray>
+  /** Select first item (alias for $at(0)) */
+  readonly $first: PathNode<Item, InArray>
+  /** Select last item (alias for $at(-1)) */
+  readonly $last: PathNode<Item, InArray>
+}
+
+// Struct path node (fixed keys) - propagates InArray to children
+type StructPathNode<
+  Shapes extends Record<string, ContainerOrValueShape>,
+  InArray extends boolean,
+> = PathSelector<
+  WrapType<{ [K in keyof Shapes]: Infer<Shapes[K]> }, InArray>
+> & {
+  readonly [K in keyof Shapes]: PathNode<Shapes[K], InArray>
+}
+
+// Record path node (dynamic keys) - propagates InArray to children
+interface RecordPathNode<
+  Item extends ContainerOrValueShape,
+  InArray extends boolean,
+> extends PathSelector<WrapType<Record<string, Infer<Item>>, InArray>> {
+  /** Select all values (wildcard) - sets InArray to true for children */
+  readonly $each: PathNode<Item, true>
+  /** Select value at specific key */
+  $key(key: string): PathNode<Item, InArray>
+}
+
+// Text path node (terminal)
+type TextPathNode<InArray extends boolean> = PathSelector<
+  WrapType<string, InArray>
+>
+
+// Counter path node (terminal)
+type CounterPathNode<InArray extends boolean> = PathSelector<
+  WrapType<number, InArray>
+>
+
+// Terminal node for primitive values
+type TerminalPathNode<T, InArray extends boolean> = PathSelector<
+  WrapType<T, InArray>
+>
+
+// ============================================================================
+// PathNode Type Mapping
+// ============================================================================
+
+// Helper: wrap type in array if InArray is true
+type WrapType<T, InArray extends boolean> = InArray extends true ? T[] : T
+
+// InArray tracks whether we've passed through a wildcard ($each)
+// This affects the result type: T vs T[]
+export type PathNode<
+  S extends ContainerOrValueShape,
+  InArray extends boolean,
+> = S extends ListContainerShape<infer Item>
+  ? ListPathNode<Item, InArray>
+  : S extends MovableListContainerShape<infer Item>
+    ? ListPathNode<Item, InArray>
+    : S extends StructContainerShape<infer Shapes>
+      ? StructPathNode<Shapes, InArray>
+      : S extends RecordContainerShape<infer Item>
+        ? RecordPathNode<Item, InArray>
+        : S extends TextContainerShape
+          ? TextPathNode<InArray>
+          : S extends CounterContainerShape
+            ? CounterPathNode<InArray>
+            : S extends ValueShape
+              ? TerminalPathNode<Infer<S>, InArray>
+              : never
+
+// ============================================================================
+// Path Builder (entry point)
+// ============================================================================
+
+export type PathBuilder<D extends DocShape> = {
+  readonly [K in keyof D["shapes"]]: PathNode<D["shapes"][K], false>
+}

package/src/readonly.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it } from "vitest"
+import { change } from "./functional-helpers.js"
 import { Shape } from "./shape.js"
 import { createTypedDoc } from "./typed-doc.js"
 
@@ -14,7 +15,7 @@ describe("TypedDoc Mutable Mode", () => {
   it("should read values correctly", () => {
     const doc = createTypedDoc(schema)
 
-    doc.$.change(d => {
+    change(doc, d => {
       d.meta.count = 1
       d.meta.title = "updated"
       d.list.push("item1")
@@ -33,7 +34,7 @@ describe("TypedDoc Mutable Mode", () => {
 
     expect(liveMeta.count).toBe(0)
 
-    doc.$.change(d => {
+    change(doc, d => {
       d.meta.count = 5
     })
 
@@ -58,7 +59,7 @@ describe("TypedDoc Mutable Mode", () => {
   it("should support change() for grouped mutations", () => {
     const doc = createTypedDoc(schema)
 
-    doc.$.change(d => {
+    change(doc, d => {
       d.meta.count = 1
       d.meta.title = "batched"
       d.list.push("a")
@@ -74,7 +75,7 @@ describe("TypedDoc Mutable Mode", () => {
   it("should support toJSON for full serialization", () => {
     const doc = createTypedDoc(schema)
 
-    doc.$.change(d => {
+    change(doc, d => {
       d.meta.count = 1
       d.meta.title = "json"
       d.list.push("a")

package/src/shape.ts

@@ -7,6 +7,7 @@ import type {
   LoroMovableList,
   LoroText,
   LoroTree,
+  Value,
 } from "loro-crdt"
 
 import type { CounterRef } from "./typed-refs/counter.js"
@@ -128,7 +129,24 @@ export interface RecordContainerShape<
   readonly shape: NestedShape
 }
 
+/**
+ * Container escape hatch - represents "any LoroContainer".
+ * Use this when integrating with external libraries that manage their own document structure.
+ *
+ * @example
+ * ```typescript
+ * // loro-prosemirror manages its own structure
+ * const ProseMirrorDocShape = Shape.doc({
+ *   doc: Shape.any(), // opt out of typing for this container
+ * })
+ * ```
+ */
+export interface AnyContainerShape extends Shape<unknown, unknown, undefined> {
+  readonly _type: "any"
+}
+
 export type ContainerShape =
+  | AnyContainerShape
   | CounterContainerShape
   | ListContainerShape
   | MovableListContainerShape
@@ -250,8 +268,25 @@ export interface DiscriminatedUnionValueShape<
   readonly variants: T
 }
 
+/**
+ * Value escape hatch - represents "any Loro Value".
+ * Use this when you need to accept any valid Loro value type.
+ *
+ * @example
+ * ```typescript
+ * const FlexiblePresenceShape = Shape.plain.struct({
+ *   cursor: Shape.plain.any(), // accept any value type
+ * })
+ * ```
+ */
+export interface AnyValueShape extends Shape<Value, Value, undefined> {
+  readonly _type: "value"
+  readonly valueType: "any"
+}
+
 // Union of all ValueShapes - these can only contain other ValueShapes, not ContainerShapes
 export type ValueShape =
+  | AnyValueShape
   | StringValueShape
   | NumberValueShape
   | BooleanValueShape
@@ -317,6 +352,28 @@ export const Shape = {
     _placeholder: {} as any,
   }),
 
+  /**
+   * Creates an "any" container shape - an escape hatch for untyped containers.
+   * Use this when integrating with external libraries that manage their own document structure.
+   *
+   * @example
+   * ```typescript
+   * // loro-prosemirror manages its own structure
+   * const ProseMirrorDocShape = Shape.doc({
+   *   doc: Shape.any(), // opt out of typing for this container
+   * })
+   *
+   * const handle = repo.get(docId, ProseMirrorDocShape, CursorPresenceShape)
+   * // handle.doc.doc is typed as `unknown` - you're on your own
+   * ```
+   */
+  any: (): AnyContainerShape => ({
+    _type: "any" as const,
+    _plain: undefined as unknown,
+    _mutable: undefined as unknown,
+    _placeholder: undefined,
+  }),
+
   // CRDTs are represented by Loro Containers--they converge on state using Loro's
   // various CRDT algorithms
   counter: (): WithPlaceholder<CounterContainerShape> => {
@@ -509,12 +566,70 @@ export const Shape = {
       _placeholder: undefined,
     }),
 
-    uint8Array: (): Uint8ArrayValueShape => ({
+    uint8Array: (): Uint8ArrayValueShape &
+      WithNullable<Uint8ArrayValueShape> => {
+      const base: Uint8ArrayValueShape = {
+        _type: "value" as const,
+        valueType: "uint8array" as const,
+        _plain: new Uint8Array(),
+        _mutable: new Uint8Array(),
+        _placeholder: new Uint8Array(),
+      }
+      return Object.assign(base, {
+        nullable(): WithPlaceholder<
+          UnionValueShape<[NullValueShape, Uint8ArrayValueShape]>
+        > {
+          return makeNullable(base)
+        },
+      })
+    },
+
+    /**
+     * Alias for `uint8Array()` - creates a shape for binary data.
+     * Use this for better discoverability when working with binary data like cursor positions.
+     *
+     * @example
+     * ```typescript
+     * const CursorPresenceShape = Shape.plain.struct({
+     *   anchor: Shape.plain.bytes().nullable(),
+     *   focus: Shape.plain.bytes().nullable(),
+     * })
+     * ```
+     */
+    bytes: (): Uint8ArrayValueShape & WithNullable<Uint8ArrayValueShape> => {
+      const base: Uint8ArrayValueShape = {
+        _type: "value" as const,
+        valueType: "uint8array" as const,
+        _plain: new Uint8Array(),
+        _mutable: new Uint8Array(),
+        _placeholder: new Uint8Array(),
+      }
+      return Object.assign(base, {
+        nullable(): WithPlaceholder<
+          UnionValueShape<[NullValueShape, Uint8ArrayValueShape]>
+        > {
+          return makeNullable(base)
+        },
+      })
+    },
+
+    /**
+     * Creates an "any" value shape - an escape hatch for untyped values.
+     * Use this when you need to accept any valid Loro value type.
+     *
+     * @example
+     * ```typescript
+     * const FlexiblePresenceShape = Shape.plain.struct({
+     *   metadata: Shape.plain.any(), // accept any value type
+     * })
+     * ```
+     */
+    any: (): AnyValueShape => ({
       _type: "value" as const,
-      valueType: "uint8array" as const,
-      _plain: new Uint8Array(),
-      _mutable: new Uint8Array(),
-      _placeholder: new Uint8Array(),
+      valueType: "any" as const,
+      _plain: undefined as unknown as Value,
+      _mutable: undefined as unknown as Value,
+      _placeholder: undefined,
     }),
 
     /**

package/src/typed-refs/base.ts

@@ -19,6 +19,12 @@ export abstract class TypedRef<Shape extends DocShape | ContainerShape> {
 
   abstract absorbPlainValues(): void
 
+  /**
+   * Serializes the ref to a plain JSON-compatible value.
+   * Returns the plain type inferred from the shape.
+   */
+  abstract toJSON(): Infer<Shape>
+
   protected get shape(): Shape {
     return this._params.shape
   }

package/src/typed-refs/counter.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it } from "vitest"
+import { change } from "../functional-helpers.js"
 import { Shape } from "../shape.js"
 import { createTypedDoc } from "../typed-doc.js"
 
@@ -57,7 +58,7 @@ describe("Counter Ref", () => {
     })
     const doc = createTypedDoc(schema)
 
-    doc.$.change(draft => {
+    change(doc, draft => {
       draft.counter.increment(5)
     })