@loro-extended/change 0.8.1 → 0.9.1

package/src/presence-interface.ts

@@ -0,0 +1,52 @@
+import type { Value } from "loro-crdt"
+
+/**
+ * A record of string keys to Loro values, used for presence data.
+ */
+export type ObjectValue = Record<string, Value>
+
+/**
+ * Interface for presence management that can be implemented by different backends.
+ * This abstraction allows TypedPresence to work with any presence provider.
+ */
+export interface PresenceInterface {
+  /**
+   * Set multiple presence values at once.
+   */
+  set: (values: ObjectValue) => void
+
+  /**
+   * Get a single presence value by key.
+   */
+  get: (key: string) => Value
+
+  /**
+   * The current peer's presence state.
+   */
+  readonly self: ObjectValue
+
+  /**
+   * Other peers' presence states, keyed by peer ID.
+   * Does NOT include self. Use this for iterating over remote peers.
+   */
+  readonly peers: Map<string, ObjectValue>
+
+  /**
+   * All peers' presence states, keyed by peer ID (includes self).
+   * @deprecated Use `peers` and `self` separately. This property is synthesized
+   * from `peers` and `self` for backward compatibility.
+   */
+  readonly all: Record<string, ObjectValue>
+
+  /**
+   * Set a single raw value by key (escape hatch for arbitrary keys).
+   */
+  setRaw: (key: string, value: Value) => void
+
+  /**
+   * Subscribe to presence changes.
+   * @param cb Callback that receives the aggregated presence values
+   * @returns Unsubscribe function
+   */
+  subscribe: (cb: (values: ObjectValue) => void) => () => void
+}

package/src/shape.ts

@@ -9,17 +9,17 @@ import type {
   LoroTree,
 } from "loro-crdt"
 
-import type { CounterDraftNode } from "./draft-nodes/counter.js"
-import type { ListDraftNode } from "./draft-nodes/list.js"
-import type { MapDraftNode } from "./draft-nodes/map.js"
-import type { MovableListDraftNode } from "./draft-nodes/movable-list.js"
-import type { RecordDraftNode } from "./draft-nodes/record.js"
-import type { TextDraftNode } from "./draft-nodes/text.js"
-
-export interface Shape<Plain, Draft, Placeholder = Plain> {
+import type { CounterRef } from "./typed-refs/counter.js"
+import type { ListRef } from "./typed-refs/list.js"
+import type { MapRef } from "./typed-refs/map.js"
+import type { MovableListRef } from "./typed-refs/movable-list.js"
+import type { RecordRef } from "./typed-refs/record.js"
+import type { TextRef } from "./typed-refs/text.js"
+
+export interface Shape<Plain, Mutable, Placeholder = Plain> {
   readonly _type: string
   readonly _plain: Plain
-  readonly _draft: Draft
+  readonly _mutable: Mutable
   readonly _placeholder: Placeholder
 }
 
@@ -35,7 +35,7 @@ export interface DocShape<
   >,
 > extends Shape<
     { [K in keyof NestedShapes]: NestedShapes[K]["_plain"] },
-    { [K in keyof NestedShapes]: NestedShapes[K]["_draft"] },
+    { [K in keyof NestedShapes]: NestedShapes[K]["_mutable"] },
     { [K in keyof NestedShapes]: NestedShapes[K]["_placeholder"] }
   > {
   readonly _type: "doc"
@@ -43,12 +43,11 @@ export interface DocShape<
   readonly shapes: NestedShapes
 }
 
-export interface TextContainerShape
-  extends Shape<string, TextDraftNode, string> {
+export interface TextContainerShape extends Shape<string, TextRef, string> {
   readonly _type: "text"
 }
 export interface CounterContainerShape
-  extends Shape<number, CounterDraftNode, number> {
+  extends Shape<number, CounterRef, number> {
   readonly _type: "counter"
 }
 export interface TreeContainerShape<NestedShape = ContainerOrValueShape>
@@ -64,7 +63,7 @@ export interface TreeContainerShape<NestedShape = ContainerOrValueShape>
 // This prevents users from expecting per-entry merging behavior.
 export interface ListContainerShape<
   NestedShape extends ContainerOrValueShape = ContainerOrValueShape,
-> extends Shape<NestedShape["_plain"][], ListDraftNode<NestedShape>, never[]> {
+> extends Shape<NestedShape["_plain"][], ListRef<NestedShape>, never[]> {
   readonly _type: "list"
   // A list contains many elements, all of the same 'shape'
   readonly shape: NestedShape
@@ -72,11 +71,7 @@ export interface ListContainerShape<
 
 export interface MovableListContainerShape<
   NestedShape extends ContainerOrValueShape = ContainerOrValueShape,
-> extends Shape<
-    NestedShape["_plain"][],
-    MovableListDraftNode<NestedShape>,
-    never[]
-  > {
+> extends Shape<NestedShape["_plain"][], MovableListRef<NestedShape>, never[]> {
   readonly _type: "movableList"
   // A list contains many elements, all of the same 'shape'
   readonly shape: NestedShape
@@ -89,8 +84,8 @@ export interface MapContainerShape<
   >,
 > extends Shape<
     { [K in keyof NestedShapes]: NestedShapes[K]["_plain"] },
-    MapDraftNode<NestedShapes> & {
-      [K in keyof NestedShapes]: NestedShapes[K]["_draft"]
+    MapRef<NestedShapes> & {
+      [K in keyof NestedShapes]: NestedShapes[K]["_mutable"]
     },
     { [K in keyof NestedShapes]: NestedShapes[K]["_placeholder"] }
   > {
@@ -103,7 +98,7 @@ export interface RecordContainerShape<
   NestedShape extends ContainerOrValueShape = ContainerOrValueShape,
 > extends Shape<
     Record<string, NestedShape["_plain"]>,
-    RecordDraftNode<NestedShape>,
+    RecordRef<NestedShape>,
     Record<string, never>
   > {
   readonly _type: "record"
@@ -155,7 +150,7 @@ export interface ObjectValueShape<
   T extends Record<string, ValueShape> = Record<string, ValueShape>,
 > extends Shape<
     { [K in keyof T]: T[K]["_plain"] },
-    { [K in keyof T]: T[K]["_draft"] },
+    { [K in keyof T]: T[K]["_mutable"] },
     { [K in keyof T]: T[K]["_placeholder"] }
   > {
   readonly _type: "value"
@@ -168,7 +163,7 @@ export interface ObjectValueShape<
 export interface RecordValueShape<T extends ValueShape = ValueShape>
   extends Shape<
     Record<string, T["_plain"]>,
-    Record<string, T["_draft"]>,
+    Record<string, T["_mutable"]>,
     Record<string, never>
   > {
   readonly _type: "value"
@@ -177,7 +172,7 @@ export interface RecordValueShape<T extends ValueShape = ValueShape>
 }
 
 export interface ArrayValueShape<T extends ValueShape = ValueShape>
-  extends Shape<T["_plain"][], T["_draft"][], never[]> {
+  extends Shape<T["_plain"][], T["_mutable"][], never[]> {
   readonly _type: "value"
   readonly valueType: "array"
   readonly shape: T
@@ -186,7 +181,7 @@ export interface ArrayValueShape<T extends ValueShape = ValueShape>
 export interface UnionValueShape<T extends ValueShape[] = ValueShape[]>
   extends Shape<
     T[number]["_plain"],
-    T[number]["_draft"],
+    T[number]["_mutable"],
     T[number]["_placeholder"]
   > {
   readonly _type: "value"
@@ -210,11 +205,10 @@ export interface UnionValueShape<T extends ValueShape[] = ValueShape[]>
 export interface DiscriminatedUnionValueShape<
   K extends string = string,
   T extends Record<string, ObjectValueShape> = Record<string, ObjectValueShape>,
-> extends Shape<
-    T[keyof T]["_plain"],
-    T[keyof T]["_draft"],
-    T[keyof T]["_placeholder"]
-  > {
+  Plain = T[keyof T]["_plain"],
+  Mutable = T[keyof T]["_mutable"],
+  Placeholder = T[keyof T]["_placeholder"],
+> extends Shape<Plain, Mutable, Placeholder> {
   readonly _type: "value"
   readonly valueType: "discriminatedUnion"
   readonly discriminantKey: K
@@ -249,7 +243,7 @@ export const Shape = {
     _type: "doc" as const,
     shapes: shape,
     _plain: {} as any,
-    _draft: {} as any,
+    _mutable: {} as any,
     _placeholder: {} as any,
   }),
 
@@ -259,7 +253,7 @@ export const Shape = {
     const base: CounterContainerShape = {
       _type: "counter" as const,
       _plain: 0,
-      _draft: {} as CounterDraftNode,
+      _mutable: {} as CounterRef,
       _placeholder: 0,
     }
     return Object.assign(base, {
@@ -273,7 +267,7 @@ export const Shape = {
     _type: "list" as const,
     shape,
     _plain: [] as any,
-    _draft: {} as any,
+    _mutable: {} as any,
     _placeholder: [] as never[],
   }),
 
@@ -283,7 +277,7 @@ export const Shape = {
     _type: "map" as const,
     shapes: shape,
     _plain: {} as any,
-    _draft: {} as any,
+    _mutable: {} as any,
     _placeholder: {} as any,
   }),
 
@@ -293,7 +287,7 @@ export const Shape = {
     _type: "record" as const,
     shape,
     _plain: {} as any,
-    _draft: {} as any,
+    _mutable: {} as any,
     _placeholder: {} as Record<string, never>,
   }),
 
@@ -303,7 +297,7 @@ export const Shape = {
     _type: "movableList" as const,
     shape,
     _plain: [] as any,
-    _draft: {} as any,
+    _mutable: {} as any,
     _placeholder: [] as never[],
   }),
 
@@ -311,7 +305,7 @@ export const Shape = {
     const base: TextContainerShape = {
       _type: "text" as const,
       _plain: "",
-      _draft: {} as TextDraftNode,
+      _mutable: {} as TextRef,
       _placeholder: "",
     }
     return Object.assign(base, {
@@ -325,7 +319,7 @@ export const Shape = {
     _type: "tree" as const,
     shape,
     _plain: {} as any,
-    _draft: {} as any,
+    _mutable: {} as any,
     _placeholder: [] as never[],
   }),
 
@@ -341,7 +335,7 @@ export const Shape = {
         _type: "value" as const,
         valueType: "string" as const,
         _plain: (options[0] ?? "") as T,
-        _draft: (options[0] ?? "") as T,
+        _mutable: (options[0] ?? "") as T,
         _placeholder: (options[0] ?? "") as T,
         options: options.length > 0 ? options : undefined,
       }
@@ -357,7 +351,7 @@ export const Shape = {
         _type: "value" as const,
         valueType: "number" as const,
         _plain: 0,
-        _draft: 0,
+        _mutable: 0,
         _placeholder: 0,
       }
       return Object.assign(base, {
@@ -372,7 +366,7 @@ export const Shape = {
         _type: "value" as const,
         valueType: "boolean" as const,
         _plain: false,
-        _draft: false,
+        _mutable: false,
         _placeholder: false,
       }
       return Object.assign(base, {
@@ -386,7 +380,7 @@ export const Shape = {
       _type: "value" as const,
       valueType: "null" as const,
       _plain: null,
-      _draft: null,
+      _mutable: null,
       _placeholder: null,
     }),
 
@@ -394,7 +388,7 @@ export const Shape = {
       _type: "value" as const,
       valueType: "undefined" as const,
       _plain: undefined,
-      _draft: undefined,
+      _mutable: undefined,
       _placeholder: undefined,
     }),
 
@@ -402,7 +396,7 @@ export const Shape = {
       _type: "value" as const,
       valueType: "uint8array" as const,
       _plain: new Uint8Array(),
-      _draft: new Uint8Array(),
+      _mutable: new Uint8Array(),
       _placeholder: new Uint8Array(),
     }),
 
@@ -413,7 +407,7 @@ export const Shape = {
       valueType: "object" as const,
       shape,
       _plain: {} as any,
-      _draft: {} as any,
+      _mutable: {} as any,
       _placeholder: {} as any,
     }),
 
@@ -422,7 +416,7 @@ export const Shape = {
       valueType: "record" as const,
       shape,
       _plain: {} as any,
-      _draft: {} as any,
+      _mutable: {} as any,
       _placeholder: {} as Record<string, never>,
     }),
 
@@ -431,7 +425,7 @@ export const Shape = {
       valueType: "array" as const,
       shape,
       _plain: [] as any,
-      _draft: [] as any,
+      _mutable: [] as any,
       _placeholder: [] as never[],
     }),
 
@@ -445,7 +439,7 @@ export const Shape = {
         valueType: "union" as const,
         shapes,
         _plain: {} as any,
-        _draft: {} as any,
+        _mutable: {} as any,
         _placeholder: {} as any,
       }
       return Object.assign(base, {
@@ -494,7 +488,7 @@ export const Shape = {
         discriminantKey,
         variants,
         _plain: {} as any,
-        _draft: {} as any,
+        _mutable: {} as any,
         _placeholder: {} as any,
       }
       return Object.assign(base, {

package/src/typed-doc.ts

@@ -2,7 +2,6 @@
 
 import { LoroDoc } from "loro-crdt"
 import { derivePlaceholder } from "./derive-placeholder.js"
-import { DraftDoc } from "./draft-nodes/doc.js"
 import {
   type JsonPatch,
   JsonPatchApplicator,
@@ -11,6 +10,7 @@ import {
 } from "./json-patch.js"
 import { overlayPlaceholder } from "./overlay.js"
 import type { DocShape } from "./shape.js"
+import { DocRef } from "./typed-refs/doc.js"
 import type {
   DeepReadonly,
   Draft,
@@ -46,7 +46,7 @@ export class TypedDoc<Shape extends DocShape> {
    * This is efficient (O(1) per access) and always up-to-date.
    */
   get value(): DeepReadonly<Infer<Shape>> {
-    return new DraftDoc({
+    return new DocRef({
       shape: this.shape,
       placeholder: this.placeholder as any,
       doc: this.doc,
@@ -68,8 +68,8 @@ export class TypedDoc<Shape extends DocShape> {
   }
 
   change(fn: (draft: Draft<Shape>) => void): Infer<Shape> {
-    // Reuse existing DocumentDraft system with placeholder integration
-    const draft = new DraftDoc({
+    // Reuse existing DocRef system with placeholder integration
+    const draft = new DocRef({
       shape: this.shape,
       placeholder: this.placeholder as any,
       doc: this.doc,

package/src/typed-presence.ts

@@ -0,0 +1,96 @@
+import { deriveShapePlaceholder } from "./derive-placeholder.js"
+import { mergeValue } from "./overlay.js"
+import type { ObjectValue, PresenceInterface } from "./presence-interface.js"
+import type { ContainerShape, ValueShape } from "./shape.js"
+import type { Infer } from "./types.js"
+
+/**
+ * A strongly-typed wrapper around a PresenceInterface.
+ * Provides type-safe access to presence data with automatic placeholder merging.
+ *
+ * @typeParam S - The shape of the presence data
+ */
+export class TypedPresence<S extends ContainerShape | ValueShape> {
+  private placeholder: Infer<S>
+
+  constructor(
+    public shape: S,
+    private presence: PresenceInterface,
+  ) {
+    this.placeholder = deriveShapePlaceholder(shape) as Infer<S>
+  }
+
+  /**
+   * Get the current peer's presence state with placeholder values merged in.
+   */
+  get self(): Infer<S> {
+    return mergeValue(
+      this.shape,
+      this.presence.self,
+      this.placeholder,
+    ) as Infer<S>
+  }
+
+  /**
+   * Get other peers' presence states with placeholder values merged in.
+   * Does NOT include self. Use this for iterating over remote peers.
+   */
+  get peers(): Map<string, Infer<S>> {
+    const result = new Map<string, Infer<S>>()
+    for (const [peerId, value] of this.presence.peers) {
+      result.set(
+        peerId,
+        mergeValue(this.shape, value, this.placeholder) as Infer<S>,
+      )
+    }
+    return result
+  }
+
+  /**
+   * Get all peers' presence states with placeholder values merged in.
+   * @deprecated Use `peers` and `self` separately. This property is synthesized
+   * from `peers` and `self` for backward compatibility.
+   */
+  get all(): Record<string, Infer<S>> {
+    const result: Record<string, Infer<S>> = {}
+    const all = this.presence.all
+    for (const peerId of Object.keys(all)) {
+      result[peerId] = mergeValue(
+        this.shape,
+        all[peerId],
+        this.placeholder,
+      ) as Infer<S>
+    }
+    return result
+  }
+
+  /**
+   * Set presence values for the current peer.
+   */
+  set(value: Partial<Infer<S>>) {
+    this.presence.set(value as ObjectValue)
+  }
+
+  /**
+   * Subscribe to presence changes.
+   * The callback is called immediately with the current state, then on each change.
+   *
+   * @param cb Callback that receives the typed presence state
+   * @returns Unsubscribe function
+   */
+  subscribe(
+    cb: (state: {
+      self: Infer<S>
+      peers: Map<string, Infer<S>>
+      /** @deprecated Use `peers` and `self` separately */
+      all: Record<string, Infer<S>>
+    }) => void,
+  ): () => void {
+    // Initial call
+    cb({ self: this.self, peers: this.peers, all: this.all })
+
+    return this.presence.subscribe(() => {
+      cb({ self: this.self, peers: this.peers, all: this.all })
+    })
+  }
+}

package/src/{draft-nodes → typed-refs}/base.ts

@@ -1,18 +1,18 @@
 import type { ContainerShape, DocShape, ShapeToContainer } from "../shape.js"
 import type { Infer } from "../types.js"
 
-export type DraftNodeParams<Shape extends DocShape | ContainerShape> = {
+export type TypedRefParams<Shape extends DocShape | ContainerShape> = {
   shape: Shape
   placeholder?: Infer<Shape>
   getContainer: () => ShapeToContainer<Shape>
   readonly?: boolean
 }
 
-// Base class for all draft nodes
-export abstract class DraftNode<Shape extends DocShape | ContainerShape> {
+// Base class for all typed refs
+export abstract class TypedRef<Shape extends DocShape | ContainerShape> {
   protected _cachedContainer?: ShapeToContainer<Shape>
 
-  constructor(protected _params: DraftNodeParams<Shape>) {}
+  constructor(protected _params: TypedRefParams<Shape>) {}
 
   abstract absorbPlainValues(): void
 
@@ -28,6 +28,16 @@ export abstract class DraftNode<Shape extends DocShape | ContainerShape> {
     return !!this._params.readonly
   }
 
+  /**
+   * Throws an error if this ref is in readonly mode.
+   * Call this at the start of any mutating method.
+   */
+  protected assertMutable(): void {
+    if (this.readonly) {
+      throw new Error("Cannot modify readonly ref")
+    }
+  }
+
   protected get container(): ShapeToContainer<Shape> {
     if (!this._cachedContainer) {
       const container = this._params.getContainer()

package/src/{draft-nodes → typed-refs}/counter.test.ts

@@ -2,7 +2,7 @@ import { describe, expect, it } from "vitest"
 import { Shape } from "../shape.js"
 import { createTypedDoc } from "../typed-doc.js"
 
-describe("Counter Draft Node", () => {
+describe("Counter Ref", () => {
   it("should return placeholder value without materializing the container", () => {
     const schema = Shape.doc({
       counter: Shape.counter().placeholder(10),

package/src/{draft-nodes → typed-refs}/counter.ts

@@ -1,21 +1,27 @@
 import type { CounterContainerShape } from "../shape.js"
-import { DraftNode } from "./base.js"
+import { TypedRef } from "./base.js"
 
-// Counter draft node
-export class CounterDraftNode extends DraftNode<CounterContainerShape> {
+// Counter typed ref
+export class CounterRef extends TypedRef<CounterContainerShape> {
   absorbPlainValues() {
     // no plain values contained within
   }
 
   increment(value: number): void {
+    this.assertMutable()
     this.container.increment(value)
   }
 
   decrement(value: number): void {
+    this.assertMutable()
     this.container.decrement(value)
   }
 
   get value(): number {
     return this.container.value
   }
+
+  toJSON(): number {
+    return this.value
+  }
 }