@loro-extended/change 1.1.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loro-extended/change",
-  "version": "1.1.0",
+  "version": "2.0.0",
   "description": "A schema-driven, type-safe wrapper for Loro CRDT that provides natural JavaScript syntax for collaborative data mutations",
   "author": "Duane Johnson",
   "license": "MIT",
@@ -21,7 +21,7 @@
     "./src/*": "./src/*"
   },
   "dependencies": {
-    "loro-crdt": "^1.10.2"
+    "loro-crdt": "^1.10.3"
   },
   "devDependencies": {
     "tsup": "^8.5.0",
@@ -31,8 +31,7 @@
   },
   "scripts": {
     "build": "tsup",
-    "format": "biome format --write .",
-    "lint": "biome check --write .",
+    "check": "biome check --write .",
     "test": "vitest",
     "typecheck": "tsc --noEmit --skipLibCheck"
   }

package/src/any-shape.test.ts

@@ -0,0 +1,164 @@
+import { describe, expect, it } from "vitest"
+import { deriveShapePlaceholder } from "./derive-placeholder.js"
+import { mergeValue } from "./overlay.js"
+import { Shape } from "./shape.js"
+import type { Infer } from "./types.js"
+
+describe("Shape.any()", () => {
+  it("creates an AnyContainerShape", () => {
+    const shape = Shape.any()
+    expect(shape._type).toBe("any")
+    expect(shape._placeholder).toBeUndefined()
+  })
+
+  it("can be used in a doc shape", () => {
+    const docShape = Shape.doc({
+      content: Shape.any(),
+    })
+    expect(docShape.shapes.content._type).toBe("any")
+  })
+
+  it("derives undefined placeholder for any container", () => {
+    const shape = Shape.any()
+    const placeholder = deriveShapePlaceholder(shape)
+    expect(placeholder).toBeUndefined()
+  })
+
+  it("mergeValue returns CRDT value as-is for any container", () => {
+    const shape = Shape.any()
+    const crdtValue = { nested: { data: "test" } }
+    const result = mergeValue(shape, crdtValue, undefined)
+    expect(result).toBe(crdtValue)
+  })
+
+  it("type inference produces unknown for any container", () => {
+    const docShape = Shape.doc({
+      content: Shape.any(),
+    })
+    // Type test: Infer<typeof docShape> should have content: unknown
+    type DocType = Infer<typeof docShape>
+    const _typeCheck: DocType = { content: "anything" }
+    const _typeCheck2: DocType = { content: { nested: true } }
+    const _typeCheck3: DocType = { content: 123 }
+    expect(true).toBe(true) // Type-level test
+  })
+})
+
+describe("Shape.plain.any()", () => {
+  it("creates an AnyValueShape", () => {
+    const shape = Shape.plain.any()
+    expect(shape._type).toBe("value")
+    expect(shape.valueType).toBe("any")
+    expect(shape._placeholder).toBeUndefined()
+  })
+
+  it("can be used in a struct value shape", () => {
+    const presenceShape = Shape.plain.struct({
+      metadata: Shape.plain.any(),
+    })
+    expect(presenceShape.shape.metadata.valueType).toBe("any")
+  })
+
+  it("derives undefined placeholder for any value", () => {
+    const shape = Shape.plain.any()
+    const placeholder = deriveShapePlaceholder(shape)
+    expect(placeholder).toBeUndefined()
+  })
+
+  it("mergeValue returns CRDT value as-is for any value", () => {
+    const shape = Shape.plain.any()
+    const crdtValue = { anything: "goes" }
+    const result = mergeValue(shape, crdtValue, undefined)
+    expect(result).toBe(crdtValue)
+  })
+})
+
+describe("Shape.plain.bytes()", () => {
+  it("creates a Uint8ArrayValueShape", () => {
+    const shape = Shape.plain.bytes()
+    expect(shape._type).toBe("value")
+    expect(shape.valueType).toBe("uint8array")
+  })
+
+  it("is equivalent to Shape.plain.uint8Array()", () => {
+    const bytesShape = Shape.plain.bytes()
+    const uint8ArrayShape = Shape.plain.uint8Array()
+    expect(bytesShape._type).toBe(uint8ArrayShape._type)
+    expect(bytesShape.valueType).toBe(uint8ArrayShape.valueType)
+  })
+
+  it("supports .nullable()", () => {
+    const shape = Shape.plain.bytes().nullable()
+    expect(shape.valueType).toBe("union")
+    expect(shape.shapes[0].valueType).toBe("null")
+    expect(shape.shapes[1].valueType).toBe("uint8array")
+  })
+
+  it("can be used for cursor presence data", () => {
+    const CursorPresenceShape = Shape.plain.struct({
+      anchor: Shape.plain.bytes().nullable(),
+      focus: Shape.plain.bytes().nullable(),
+      user: Shape.plain
+        .struct({
+          name: Shape.plain.string(),
+          color: Shape.plain.string(),
+        })
+        .nullable(),
+    })
+
+    // Type test: should compile
+    type CursorPresence = Infer<typeof CursorPresenceShape>
+    const _typeCheck: CursorPresence = {
+      anchor: new Uint8Array([1, 2, 3]),
+      focus: null,
+      user: { name: "Alice", color: "#ff0000" },
+    }
+    expect(CursorPresenceShape.shape.anchor.valueType).toBe("union")
+  })
+})
+
+describe("Shape.plain.uint8Array().nullable()", () => {
+  it("supports .nullable()", () => {
+    const shape = Shape.plain.uint8Array().nullable()
+    expect(shape.valueType).toBe("union")
+    expect(shape.shapes[0].valueType).toBe("null")
+    expect(shape.shapes[1].valueType).toBe("uint8array")
+  })
+})
+
+describe("Integration: loro-prosemirror style usage", () => {
+  it("allows typed presence with untyped document", () => {
+    // This is the target API for loro-prosemirror integration
+    const ProseMirrorDocShape = Shape.doc({
+      doc: Shape.any(), // loro-prosemirror manages this
+    })
+
+    const CursorPresenceShape = Shape.plain.struct({
+      anchor: Shape.plain.bytes().nullable(),
+      focus: Shape.plain.bytes().nullable(),
+      user: Shape.plain
+        .struct({
+          name: Shape.plain.string(),
+          color: Shape.plain.string(),
+        })
+        .nullable(),
+    })
+
+    // Type tests
+    type DocType = Infer<typeof ProseMirrorDocShape>
+    type PresenceType = Infer<typeof CursorPresenceShape>
+
+    // Document content is unknown (we opted out)
+    const _docTypeCheck: DocType = { doc: "anything" }
+
+    // Presence is fully typed
+    const _presenceTypeCheck: PresenceType = {
+      anchor: new Uint8Array([1, 2, 3]),
+      focus: null,
+      user: { name: "Alice", color: "#ff0000" },
+    }
+
+    expect(ProseMirrorDocShape.shapes.doc._type).toBe("any")
+    expect(CursorPresenceShape.shape.anchor.valueType).toBe("union")
+  })
+})

package/src/change.test.ts

@@ -242,8 +242,10 @@ describe("CRDT Operations", () => {
       // Test move operation: move first item to the end
       const result = change(typedDoc, draft => {
         const valueToMove = draft.items.get(0)
-        draft.items.delete(0, 1)
-        draft.items.insert(2, valueToMove)
+        if (valueToMove !== undefined) {
+          draft.items.delete(0, 1)
+          draft.items.insert(2, valueToMove)
+        }
       }).toJSON()
 
       expect(result.items).toEqual(["second", "third", "first"])

package/src/derive-placeholder.ts

@@ -27,6 +27,10 @@ export function derivePlaceholder<T extends DocShape>(
  */
 export function deriveShapePlaceholder(shape: ContainerOrValueShape): unknown {
   switch (shape._type) {
+    // Any container - no placeholder (undefined)
+    case "any":
+      return undefined
+
     // Leaf containers - use _placeholder directly
     case "text":
       return shape._placeholder
@@ -60,6 +64,10 @@ export function deriveShapePlaceholder(shape: ContainerOrValueShape): unknown {
 
 function deriveValueShapePlaceholder(shape: ValueShape): unknown {
   switch (shape.valueType) {
+    // Any value - no placeholder (undefined)
+    case "any":
+      return undefined
+
     // Leaf values - use _placeholder directly
     case "string":
       return shape._placeholder

package/src/index.ts

@@ -7,9 +7,21 @@ export {
 // Functional helpers (recommended API)
 export { change, getLoroDoc } from "./functional-helpers.js"
 export { mergeValue, overlayPlaceholder } from "./overlay.js"
+// Path selector DSL exports
+export { createPathBuilder } from "./path-builder.js"
+export { compileToJsonPath, hasWildcard } from "./path-compiler.js"
+export { evaluatePath, evaluatePathOnValue } from "./path-evaluator.js"
+export type {
+  PathBuilder,
+  PathNode,
+  PathSegment,
+  PathSelector,
+} from "./path-selector.js"
 export { createPlaceholderProxy } from "./placeholder-proxy.js"
-export type { ObjectValue, PresenceInterface } from "./presence-interface.js"
 export type {
+  // Escape hatch shapes for untyped integration
+  AnyContainerShape,
+  AnyValueShape,
   ArrayValueShape,
   ContainerOrValueShape,
   ContainerShape,
@@ -44,7 +56,6 @@ export type {
 export { Shape } from "./shape.js"
 export type { TypedDoc } from "./typed-doc.js"
 export { createTypedDoc } from "./typed-doc.js"
-export { TypedPresence } from "./typed-presence.js"
 export type {
   // Type inference - Infer<T> is the recommended unified helper
   Infer,

package/src/overlay.ts

@@ -50,6 +50,16 @@ export function mergeValue<Shape extends ContainerShape | ValueShape>(
   crdtValue: Value,
   placeholderValue: Value,
 ): Value {
+  // For "any" shapes, just return the CRDT value as-is (no placeholder merging)
+  if (shape._type === "any") {
+    return crdtValue
+  }
+
+  // For "any" value shapes, just return the CRDT value as-is
+  if (shape._type === "value" && (shape as any).valueType === "any") {
+    return crdtValue
+  }
+
   if (crdtValue === undefined && placeholderValue === undefined) {
     throw new Error("either crdt or placeholder value must be defined")
   }

package/src/path-builder.ts

@@ -0,0 +1,131 @@
+// ============================================================================
+// Path Builder Factory
+// ============================================================================
+//
+// Runtime implementation of the path builder that creates PathSelector objects
+// with proper segments for JSONPath compilation.
+
+import type { PathBuilder, PathSegment, PathSelector } from "./path-selector.js"
+import type { ContainerOrValueShape, DocShape } from "./shape.js"
+
+function createPathSelector<T>(segments: PathSegment[]): PathSelector<T> {
+  return {
+    __resultType: undefined as unknown as T,
+    __segments: segments,
+  }
+}
+
+function createPathNode(
+  shape: ContainerOrValueShape,
+  segments: PathSegment[],
+): unknown {
+  const selector = createPathSelector(segments)
+
+  // Terminal shapes (text, counter, value)
+  if (shape._type === "text" || shape._type === "counter") {
+    return selector
+  }
+  if (shape._type === "value") {
+    return selector
+  }
+
+  // List/MovableList
+  if (shape._type === "list" || shape._type === "movableList") {
+    return Object.assign(selector, {
+      get $each() {
+        return createPathNode(shape.shape, [...segments, { type: "each" }])
+      },
+      $at(index: number) {
+        return createPathNode(shape.shape, [
+          ...segments,
+          { type: "index", index },
+        ])
+      },
+      get $first() {
+        return createPathNode(shape.shape, [
+          ...segments,
+          { type: "index", index: 0 },
+        ])
+      },
+      get $last() {
+        return createPathNode(shape.shape, [
+          ...segments,
+          { type: "index", index: -1 },
+        ])
+      },
+    })
+  }
+
+  // Struct (fixed keys)
+  if (shape._type === "struct") {
+    const props: Record<string, unknown> = {}
+    for (const key in shape.shapes) {
+      Object.defineProperty(props, key, {
+        get() {
+          return createPathNode(shape.shapes[key], [
+            ...segments,
+            { type: "property", key },
+          ])
+        },
+        enumerable: true,
+      })
+    }
+    return Object.assign(selector, props)
+  }
+
+  // Record (dynamic keys)
+  if (shape._type === "record") {
+    return Object.assign(selector, {
+      get $each() {
+        return createPathNode(shape.shape, [...segments, { type: "each" }])
+      },
+      $key(key: string) {
+        return createPathNode(shape.shape, [...segments, { type: "key", key }])
+      },
+    })
+  }
+
+  return selector
+}
+
+/**
+ * Creates a path builder for a given document shape.
+ *
+ * The path builder provides a type-safe DSL for selecting paths within
+ * a document. The resulting PathSelector can be compiled to a JSONPath
+ * string for use with subscribeJsonpath.
+ *
+ * @example
+ * ```typescript
+ * const docShape = Shape.doc({
+ *   books: Shape.list(Shape.struct({
+ *     title: Shape.text(),
+ *     price: Shape.plain.number(),
+ *   })),
+ * })
+ *
+ * const builder = createPathBuilder(docShape)
+ * const selector = builder.books.$each.title
+ * // selector.__segments = [
+ * //   { type: "property", key: "books" },
+ * //   { type: "each" },
+ * //   { type: "property", key: "title" }
+ * // ]
+ * ```
+ */
+export function createPathBuilder<D extends DocShape>(
+  docShape: D,
+): PathBuilder<D> {
+  const builder: Record<string, unknown> = {}
+
+  for (const key in docShape.shapes) {
+    Object.defineProperty(builder, key, {
+      get() {
+        return createPathNode(docShape.shapes[key], [{ type: "property", key }])
+      },
+      enumerable: true,
+    })
+  }
+
+  return builder as PathBuilder<D>
+}

package/src/path-compiler.ts

@@ -0,0 +1,64 @@
+// ============================================================================
+// JSONPath Compiler
+// ============================================================================
+//
+// Compiles PathSelector segments to JSONPath strings for use with
+// subscribeJsonpath.
+
+import type { PathSegment } from "./path-selector.js"
+
+/**
+ * Compiles path segments to a JSONPath string.
+ *
+ * @example
+ * ```typescript
+ * const segments = [
+ *   { type: "property", key: "books" },
+ *   { type: "each" },
+ *   { type: "property", key: "title" }
+ * ]
+ * compileToJsonPath(segments) // => '$.books[*].title'
+ * ```
+ */
+export function compileToJsonPath(segments: PathSegment[]): string {
+  let path = "$"
+
+  for (const segment of segments) {
+    switch (segment.type) {
+      case "property":
+        // Use dot notation for simple identifiers, bracket notation for safety
+        if (/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(segment.key)) {
+          path += `.${segment.key}`
+        } else {
+          path += `["${escapeJsonPathKey(segment.key)}"]`
+        }
+        break
+      case "each":
+        path += "[*]"
+        break
+      case "index":
+        path += `[${segment.index}]`
+        break
+      case "key":
+        path += `["${escapeJsonPathKey(segment.key)}"]`
+        break
+    }
+  }
+
+  return path
+}
+
+/**
+ * Escapes special characters in a JSONPath key.
+ */
+function escapeJsonPathKey(key: string): string {
+  return key.replace(/\\/g, "\\\\").replace(/"/g, '\\"')
+}
+
+/**
+ * Check if the path contains any wildcard segments.
+ * Paths with wildcards need deep equality checking for change detection.
+ */
+export function hasWildcard(segments: PathSegment[]): boolean {
+  return segments.some(s => s.type === "each")
+}

package/src/path-evaluator.ts

@@ -0,0 +1,76 @@
+// ============================================================================
+// Path Evaluator
+// ============================================================================
+//
+// Evaluates a path selector against a TypedDoc to get the current value.
+// This is used for:
+// 1. Establishing the initial previousValue baseline
+// 2. Getting the current value when subscribeJsonpath fires
+// 3. Deep equality comparison to filter false positives
+
+import type { PathSegment, PathSelector } from "./path-selector.js"
+import type { DocShape } from "./shape.js"
+import type { TypedDoc } from "./typed-doc.js"
+
+/**
+ * Evaluate a path selector against a TypedDoc to get the current value.
+ * Returns the value(s) at the path, properly typed.
+ *
+ * @example
+ * ```typescript
+ * const selector = builder.books.$each.title
+ * const titles = evaluatePath(doc, selector)
+ * // titles: string[]
+ * ```
+ */
+export function evaluatePath<D extends DocShape, T>(
+  doc: TypedDoc<D>,
+  selector: PathSelector<T>,
+): T {
+  const json = doc.$.toJSON()
+  return evaluatePathOnValue(json, selector.__segments) as T
+}
+
+/**
+ * Evaluate path segments against a plain JavaScript value.
+ * This is the core recursive evaluation logic.
+ */
+export function evaluatePathOnValue(
+  value: unknown,
+  segments: PathSegment[],
+): unknown {
+  if (segments.length === 0) {
+    return value
+  }
+
+  const [segment, ...rest] = segments
+
+  switch (segment.type) {
+    case "property":
+    case "key":
+      if (value == null) return undefined
+      if (typeof value !== "object") return undefined
+      return evaluatePathOnValue(
+        (value as Record<string, unknown>)[segment.key],
+        rest,
+      )
+
+    case "index": {
+      if (!Array.isArray(value)) return undefined
+      // Handle negative indices: -1 = last, -2 = second-to-last, etc.
+      const index =
+        segment.index < 0 ? value.length + segment.index : segment.index
+      if (index < 0 || index >= value.length) return undefined
+      return evaluatePathOnValue(value[index], rest)
+    }
+
+    case "each":
+      if (Array.isArray(value)) {
+        return value.map(item => evaluatePathOnValue(item, rest))
+      }
+      if (typeof value === "object" && value !== null) {
+        return Object.values(value).map(item => evaluatePathOnValue(item, rest))
+      }
+      return []
+  }
+}