@loro-extended/change 0.6.0 → 0.8.0

package/src/shape.ts

@@ -16,11 +16,16 @@ 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, EmptyState = Plain> {
+export interface Shape<Plain, Draft, Placeholder = Plain> {
   readonly _type: string
   readonly _plain: Plain
   readonly _draft: Draft
-  readonly _emptyState: EmptyState
+  readonly _placeholder: Placeholder
+}
+
+// Type for shapes that support placeholder customization
+export type WithPlaceholder<S extends Shape<any, any, any>> = S & {
+  placeholder(value: S["_placeholder"]): S
 }
 
 export interface DocShape<
@@ -31,7 +36,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]["_emptyState"] }
+    { [K in keyof NestedShapes]: NestedShapes[K]["_placeholder"] }
   > {
   readonly _type: "doc"
   // A doc's root containers each separately has its own shape, hence 'shapes'
@@ -54,8 +59,8 @@ export interface TreeContainerShape<NestedShape = ContainerOrValueShape>
 }
 
 // Container schemas using interfaces for recursive references
-// NOTE: List and Record use never[] and Record<string, never> for EmptyState
-// to enforce that only empty values ([] and {}) are valid in empty state.
+// NOTE: List and Record use never[] and Record<string, never> for Placeholder
+// to enforce that only empty values ([] and {}) are valid in placeholder state.
 // This prevents users from expecting per-entry merging behavior.
 export interface ListContainerShape<
   NestedShape extends ContainerOrValueShape = ContainerOrValueShape,
@@ -87,7 +92,7 @@ export interface MapContainerShape<
     MapDraftNode<NestedShapes> & {
       [K in keyof NestedShapes]: NestedShapes[K]["_draft"]
     },
-    { [K in keyof NestedShapes]: NestedShapes[K]["_emptyState"] }
+    { [K in keyof NestedShapes]: NestedShapes[K]["_placeholder"] }
   > {
   readonly _type: "map"
   // Each map property has its own shape, hence 'shapes'
@@ -151,7 +156,7 @@ export interface ObjectValueShape<
 > extends Shape<
     { [K in keyof T]: T[K]["_plain"] },
     { [K in keyof T]: T[K]["_draft"] },
-    { [K in keyof T]: T[K]["_emptyState"] }
+    { [K in keyof T]: T[K]["_placeholder"] }
   > {
   readonly _type: "value"
   readonly valueType: "object"
@@ -159,7 +164,7 @@ export interface ObjectValueShape<
 }
 
 // NOTE: RecordValueShape and ArrayValueShape use Record<string, never> and never[]
-// for EmptyState to enforce that only empty values ({} and []) are valid.
+// for Placeholder to enforce that only empty values ({} and []) are valid.
 export interface RecordValueShape<T extends ValueShape = ValueShape>
   extends Shape<
     Record<string, T["_plain"]>,
@@ -182,7 +187,7 @@ export interface UnionValueShape<T extends ValueShape[] = ValueShape[]>
   extends Shape<
     T[number]["_plain"],
     T[number]["_draft"],
-    T[number]["_emptyState"]
+    T[number]["_placeholder"]
   > {
   readonly _type: "value"
   readonly valueType: "union"
@@ -208,7 +213,7 @@ export interface DiscriminatedUnionValueShape<
 > extends Shape<
     T[keyof T]["_plain"],
     T[keyof T]["_draft"],
-    T[keyof T]["_emptyState"]
+    T[keyof T]["_placeholder"]
   > {
   readonly _type: "value"
   readonly valueType: "discriminatedUnion"
@@ -245,24 +250,31 @@ export const Shape = {
     shapes: shape,
     _plain: {} as any,
     _draft: {} as any,
-    _emptyState: {} as any,
+    _placeholder: {} as any,
   }),
 
   // CRDTs are represented by Loro Containers--they converge on state using Loro's
   // various CRDT algorithms
-  counter: (): CounterContainerShape => ({
-    _type: "counter" as const,
-    _plain: 0,
-    _draft: {} as CounterDraftNode,
-    _emptyState: 0,
-  }),
+  counter: (): WithPlaceholder<CounterContainerShape> => {
+    const base: CounterContainerShape = {
+      _type: "counter" as const,
+      _plain: 0,
+      _draft: {} as CounterDraftNode,
+      _placeholder: 0,
+    }
+    return Object.assign(base, {
+      placeholder(value: number): CounterContainerShape {
+        return { ...base, _placeholder: value }
+      },
+    })
+  },
 
   list: <T extends ContainerOrValueShape>(shape: T): ListContainerShape<T> => ({
     _type: "list" as const,
     shape,
     _plain: [] as any,
     _draft: {} as any,
-    _emptyState: [] as never[],
+    _placeholder: [] as never[],
   }),
 
   map: <T extends Record<string, ContainerOrValueShape>>(
@@ -272,7 +284,7 @@ export const Shape = {
     shapes: shape,
     _plain: {} as any,
     _draft: {} as any,
-    _emptyState: {} as any,
+    _placeholder: {} as any,
   }),
 
   record: <T extends ContainerOrValueShape>(
@@ -282,7 +294,7 @@ export const Shape = {
     shape,
     _plain: {} as any,
     _draft: {} as any,
-    _emptyState: {} as Record<string, never>,
+    _placeholder: {} as Record<string, never>,
   }),
 
   movableList: <T extends ContainerOrValueShape>(
@@ -292,22 +304,29 @@ export const Shape = {
     shape,
     _plain: [] as any,
     _draft: {} as any,
-    _emptyState: [] as never[],
+    _placeholder: [] as never[],
   }),
 
-  text: (): TextContainerShape => ({
-    _type: "text" as const,
-    _plain: "",
-    _draft: {} as TextDraftNode,
-    _emptyState: "",
-  }),
+  text: (): WithPlaceholder<TextContainerShape> => {
+    const base: TextContainerShape = {
+      _type: "text" as const,
+      _plain: "",
+      _draft: {} as TextDraftNode,
+      _placeholder: "",
+    }
+    return Object.assign(base, {
+      placeholder(value: string): TextContainerShape {
+        return { ...base, _placeholder: value }
+      },
+    })
+  },
 
   tree: <T extends MapContainerShape>(shape: T): TreeContainerShape => ({
     _type: "tree" as const,
     shape,
     _plain: {} as any,
     _draft: {} as any,
-    _emptyState: [] as never[],
+    _placeholder: [] as never[],
   }),
 
   // Values are represented as plain JS objects, with the limitation that they MUST be
@@ -317,37 +336,58 @@ export const Shape = {
   plain: {
     string: <T extends string = string>(
       ...options: T[]
-    ): StringValueShape<T> => ({
-      _type: "value" as const,
-      valueType: "string" as const,
-      _plain: (options[0] ?? "") as T,
-      _draft: (options[0] ?? "") as T,
-      _emptyState: (options[0] ?? "") as T,
-      options: options.length > 0 ? options : undefined,
-    }),
+    ): WithPlaceholder<StringValueShape<T>> => {
+      const base: StringValueShape<T> = {
+        _type: "value" as const,
+        valueType: "string" as const,
+        _plain: (options[0] ?? "") as T,
+        _draft: (options[0] ?? "") as T,
+        _placeholder: (options[0] ?? "") as T,
+        options: options.length > 0 ? options : undefined,
+      }
+      return Object.assign(base, {
+        placeholder(value: T): StringValueShape<T> {
+          return { ...base, _placeholder: value }
+        },
+      })
+    },
 
-    number: (): NumberValueShape => ({
-      _type: "value" as const,
-      valueType: "number" as const,
-      _plain: 0,
-      _draft: 0,
-      _emptyState: 0,
-    }),
+    number: (): WithPlaceholder<NumberValueShape> => {
+      const base: NumberValueShape = {
+        _type: "value" as const,
+        valueType: "number" as const,
+        _plain: 0,
+        _draft: 0,
+        _placeholder: 0,
+      }
+      return Object.assign(base, {
+        placeholder(value: number): NumberValueShape {
+          return { ...base, _placeholder: value }
+        },
+      })
+    },
 
-    boolean: (): BooleanValueShape => ({
-      _type: "value" as const,
-      valueType: "boolean" as const,
-      _plain: false,
-      _draft: false,
-      _emptyState: false,
-    }),
+    boolean: (): WithPlaceholder<BooleanValueShape> => {
+      const base: BooleanValueShape = {
+        _type: "value" as const,
+        valueType: "boolean" as const,
+        _plain: false,
+        _draft: false,
+        _placeholder: false,
+      }
+      return Object.assign(base, {
+        placeholder(value: boolean): BooleanValueShape {
+          return { ...base, _placeholder: value }
+        },
+      })
+    },
 
     null: (): NullValueShape => ({
       _type: "value" as const,
       valueType: "null" as const,
       _plain: null,
       _draft: null,
-      _emptyState: null,
+      _placeholder: null,
     }),
 
     undefined: (): UndefinedValueShape => ({
@@ -355,7 +395,7 @@ export const Shape = {
       valueType: "undefined" as const,
       _plain: undefined,
       _draft: undefined,
-      _emptyState: undefined,
+      _placeholder: undefined,
     }),
 
     uint8Array: (): Uint8ArrayValueShape => ({
@@ -363,7 +403,7 @@ export const Shape = {
       valueType: "uint8array" as const,
       _plain: new Uint8Array(),
       _draft: new Uint8Array(),
-      _emptyState: new Uint8Array(),
+      _placeholder: new Uint8Array(),
     }),
 
     object: <T extends Record<string, ValueShape>>(
@@ -374,7 +414,7 @@ export const Shape = {
       shape,
       _plain: {} as any,
       _draft: {} as any,
-      _emptyState: {} as any,
+      _placeholder: {} as any,
     }),
 
     record: <T extends ValueShape>(shape: T): RecordValueShape<T> => ({
@@ -383,7 +423,7 @@ export const Shape = {
       shape,
       _plain: {} as any,
       _draft: {} as any,
-      _emptyState: {} as Record<string, never>,
+      _placeholder: {} as Record<string, never>,
     }),
 
     array: <T extends ValueShape>(shape: T): ArrayValueShape<T> => ({
@@ -392,19 +432,28 @@ export const Shape = {
       shape,
       _plain: [] as any,
       _draft: [] as any,
-      _emptyState: [] as never[],
+      _placeholder: [] as never[],
     }),
 
     // Special value type that helps make things like `string | null` representable
     // TODO(duane): should this be a more general type for containers too?
-    union: <T extends ValueShape[]>(shapes: T): UnionValueShape<T> => ({
-      _type: "value" as const,
-      valueType: "union" as const,
-      shapes,
-      _plain: {} as any,
-      _draft: {} as any,
-      _emptyState: {} as any,
-    }),
+    union: <T extends ValueShape[]>(
+      shapes: T,
+    ): WithPlaceholder<UnionValueShape<T>> => {
+      const base: UnionValueShape<T> = {
+        _type: "value" as const,
+        valueType: "union" as const,
+        shapes,
+        _plain: {} as any,
+        _draft: {} as any,
+        _placeholder: {} as any,
+      }
+      return Object.assign(base, {
+        placeholder(value: T[number]["_placeholder"]): UnionValueShape<T> {
+          return { ...base, _placeholder: value }
+        },
+      })
+    },
 
     /**
      * Creates a discriminated union shape for type-safe tagged unions.
@@ -438,15 +487,24 @@ export const Shape = {
     >(
       discriminantKey: K,
       variants: T,
-    ): DiscriminatedUnionValueShape<K, T> => ({
-      _type: "value" as const,
-      valueType: "discriminatedUnion" as const,
-      discriminantKey,
-      variants,
-      _plain: {} as any,
-      _draft: {} as any,
-      _emptyState: {} as any,
-    }),
+    ): WithPlaceholder<DiscriminatedUnionValueShape<K, T>> => {
+      const base: DiscriminatedUnionValueShape<K, T> = {
+        _type: "value" as const,
+        valueType: "discriminatedUnion" as const,
+        discriminantKey,
+        variants,
+        _plain: {} as any,
+        _draft: {} as any,
+        _placeholder: {} as any,
+      }
+      return Object.assign(base, {
+        placeholder(
+          value: T[keyof T]["_placeholder"],
+        ): DiscriminatedUnionValueShape<K, T> {
+          return { ...base, _placeholder: value }
+        },
+      })
+    },
   },
 }
 

package/src/{change.ts → typed-doc.ts}

@@ -1,6 +1,7 @@
 /** biome-ignore-all lint/suspicious/noExplicitAny: fix later */
 
 import { LoroDoc } from "loro-crdt"
+import { derivePlaceholder } from "./derive-placeholder.js"
 import { DraftDoc } from "./draft-nodes/doc.js"
 import {
   type JsonPatch,
@@ -8,50 +9,75 @@ import {
   type JsonPatchOperation,
   normalizePath,
 } from "./json-patch.js"
-import { overlayEmptyState } from "./overlay.js"
+import { overlayPlaceholder } from "./overlay.js"
 import type { DocShape } from "./shape.js"
-import type { Draft, InferEmptyStateType, InferPlainType } from "./types.js"
-import { validateEmptyState } from "./validation.js"
+import type {
+  DeepReadonly,
+  Draft,
+  Infer,
+  InferPlaceholderType,
+} from "./types.js"
+import { validatePlaceholder } from "./validation.js"
 
 // Core TypedDoc abstraction around LoroDoc
 export class TypedDoc<Shape extends DocShape> {
+  private shape: Shape
+  private placeholder: InferPlaceholderType<Shape>
+  private doc: LoroDoc
+
   /**
-   * Creates a new TypedDoc with the given schema and empty state.
+   * Creates a new TypedDoc with the given schema.
+   * Placeholder state is automatically derived from the schema's placeholder values.
    *
-   * @param shape - The document schema
-   * @param emptyState - Default values for the document. For dynamic containers
-   *   (list, record, etc.), only empty values ([] or {}) are allowed. Use
-   *   `.change()` to add initial data after construction.
+   * @param shape - The document schema (with optional .placeholder() values)
    * @param doc - Optional existing LoroDoc to wrap
    */
-  constructor(
-    private shape: Shape,
-    private emptyState: InferEmptyStateType<Shape>,
-    private doc: LoroDoc = new LoroDoc(),
-  ) {
-    validateEmptyState(emptyState, shape)
+  constructor(shape: Shape, doc: LoroDoc = new LoroDoc()) {
+    this.shape = shape
+    this.placeholder = derivePlaceholder(shape)
+    this.doc = doc
+
+    validatePlaceholder(this.placeholder, this.shape)
+  }
+
+  /**
+   * Returns a read-only, live view of the document.
+   * Accessing properties on this object will read directly from the underlying CRDT.
+   * This is efficient (O(1) per access) and always up-to-date.
+   */
+  get value(): DeepReadonly<Infer<Shape>> {
+    return new DraftDoc({
+      shape: this.shape,
+      placeholder: this.placeholder as any,
+      doc: this.doc,
+      readonly: true,
+    }) as unknown as DeepReadonly<Infer<Shape>>
   }
 
-  get value(): InferPlainType<Shape> {
+  /**
+   * Returns the full plain JavaScript object representation of the document.
+   * This is an expensive O(N) operation that serializes the entire document.
+   */
+  toJSON(): Infer<Shape> {
     const crdtValue = this.doc.toJSON()
-    return overlayEmptyState(
+    return overlayPlaceholder(
       this.shape,
       crdtValue,
-      this.emptyState as any,
-    ) as InferPlainType<Shape>
+      this.placeholder as any,
+    ) as Infer<Shape>
   }
 
-  change(fn: (draft: Draft<Shape>) => void): InferPlainType<Shape> {
-    // Reuse existing DocumentDraft system with empty state integration
+  change(fn: (draft: Draft<Shape>) => void): Infer<Shape> {
+    // Reuse existing DocumentDraft system with placeholder integration
     const draft = new DraftDoc({
       shape: this.shape,
-      emptyState: this.emptyState as any,
+      placeholder: this.placeholder as any,
       doc: this.doc,
     })
     fn(draft as unknown as Draft<Shape>)
     draft.absorbPlainValues()
     this.doc.commit()
-    return this.value
+    return this.toJSON()
   }
 
   /**
@@ -69,10 +95,7 @@ export class TypedDoc<Shape extends DocShape> {
    * ])
    * ```
    */
-  applyPatch(
-    patch: JsonPatch,
-    pathPrefix?: (string | number)[],
-  ): InferPlainType<Shape> {
+  applyPatch(patch: JsonPatch, pathPrefix?: (string | number)[]): Infer<Shape> {
     return this.change(draft => {
       const applicator = new JsonPatchApplicator(draft)
 
@@ -107,8 +130,7 @@ export class TypedDoc<Shape extends DocShape> {
 // Factory function for TypedLoroDoc
 export function createTypedDoc<Shape extends DocShape>(
   shape: Shape,
-  emptyState: InferEmptyStateType<Shape>,
   existingDoc?: LoroDoc,
 ): TypedDoc<Shape> {
-  return new TypedDoc<Shape>(shape, emptyState, existingDoc || new LoroDoc())
+  return new TypedDoc<Shape>(shape, existingDoc || new LoroDoc())
 }

package/src/types.test.ts

@@ -0,0 +1,188 @@
+import { describe, expectTypeOf, it } from "vitest"
+import type { ContainerShape, ValueShape } from "./shape.js"
+import { Shape } from "./shape.js"
+import type { Infer } from "./types.js"
+
+describe("Infer type helper", () => {
+  it("infers DocShape plain type", () => {
+    const schema = Shape.doc({
+      title: Shape.text(),
+      count: Shape.counter(),
+    })
+
+    type Result = Infer<typeof schema>
+    expectTypeOf<Result>().toEqualTypeOf<{ title: string; count: number }>()
+  })
+
+  it("infers ContainerShape plain type (list)", () => {
+    const schema = Shape.list(Shape.plain.string())
+
+    type Result = Infer<typeof schema>
+    expectTypeOf<Result>().toEqualTypeOf<string[]>()
+  })
+
+  it("infers ValueShape plain type (object)", () => {
+    const schema = Shape.plain.object({
+      name: Shape.plain.string(),
+      age: Shape.plain.number(),
+    })
+
+    type Result = Infer<typeof schema>
+    expectTypeOf<Result>().toEqualTypeOf<{ name: string; age: number }>()
+  })
+
+  it("infers nested shapes", () => {
+    const schema = Shape.doc({
+      users: Shape.list(
+        Shape.map({
+          id: Shape.plain.string(),
+          profile: Shape.record(
+            Shape.plain.object({
+              bio: Shape.plain.string(),
+            }),
+          ),
+        }),
+      ),
+    })
+
+    type Result = Infer<typeof schema>
+    expectTypeOf<Result>().toEqualTypeOf<{
+      users: {
+        id: string
+        profile: Record<string, { bio: string }>
+      }[]
+    }>()
+  })
+
+  it("infers discriminated union plain type", () => {
+    const SessionStatusSchema = Shape.plain.discriminatedUnion("status", {
+      not_started: Shape.plain.object({
+        status: Shape.plain.string("not_started"),
+      }),
+      lobby: Shape.plain.object({
+        status: Shape.plain.string("lobby"),
+        lobbyPhase: Shape.plain.string("preparing", "typing"),
+      }),
+      active: Shape.plain.object({
+        status: Shape.plain.string("active"),
+        mode: Shape.plain.string("solo", "group"),
+      }),
+      paused: Shape.plain.object({
+        status: Shape.plain.string("paused"),
+        previousStatus: Shape.plain.string("lobby", "active"),
+        previousMode: Shape.plain.string("solo", "group"),
+        reason: Shape.plain.string(
+          "no_students",
+          "teacher_paused",
+          "assignment_empty",
+        ),
+      }),
+      ended: Shape.plain.object({
+        status: Shape.plain.string<"ended">("ended"),
+      }),
+    })
+
+    type Result = Infer<typeof SessionStatusSchema>
+
+    // The result should be a union of all variant types
+    type Expected =
+      | { status: "not_started" }
+      | { status: "lobby"; lobbyPhase: "preparing" | "typing" }
+      | { status: "active"; mode: "solo" | "group" }
+      | {
+          status: "paused"
+          previousStatus: "lobby" | "active"
+          previousMode: "solo" | "group"
+          reason: "no_students" | "teacher_paused" | "assignment_empty"
+        }
+      | { status: "ended" }
+
+    expectTypeOf<Result>().toEqualTypeOf<Expected>()
+  })
+
+  it("infers discriminated union inside a map container", () => {
+    const SessionStatusSchema = Shape.plain.discriminatedUnion("status", {
+      not_started: Shape.plain.object({
+        status: Shape.plain.string("not_started"),
+      }),
+      active: Shape.plain.object({
+        status: Shape.plain.string("active"),
+        mode: Shape.plain.string("solo", "group"),
+      }),
+    })
+
+    const SessionMetadataSchema = Shape.map({
+      sessionStartedAt: Shape.plain.number(),
+      sessionStatus: SessionStatusSchema,
+    })
+
+    type Result = Infer<typeof SessionMetadataSchema>
+
+    type Expected = {
+      sessionStartedAt: number
+      sessionStatus:
+        | { status: "not_started" }
+        | { status: "active"; mode: "solo" | "group" }
+    }
+
+    expectTypeOf<Result>().toEqualTypeOf<Expected>()
+  })
+
+  it("infers discriminated union inside a doc", () => {
+    const SessionStatusSchema = Shape.plain.discriminatedUnion("status", {
+      not_started: Shape.plain.object({
+        status: Shape.plain.string("not_started"),
+      }),
+      active: Shape.plain.object({
+        status: Shape.plain.string("active"),
+      }),
+    })
+
+    const DocSchema = Shape.doc({
+      metadata: Shape.map({
+        sessionStartedAt: Shape.plain.number(),
+        sessionStatus: SessionStatusSchema,
+      }),
+    })
+
+    type Result = Infer<typeof DocSchema>
+
+    type Expected = {
+      metadata: {
+        sessionStartedAt: number
+        sessionStatus: { status: "not_started" } | { status: "active" }
+      }
+    }
+
+    expectTypeOf<Result>().toEqualTypeOf<Expected>()
+  })
+
+  it("infers discriminated union type correctly when used with generic constraint", () => {
+    // This test verifies the fix for usePresence type inference
+    // The issue was that DiscriminatedUnionValueShape<any, any> in the ValueShape union
+    // caused type information to be lost when inferring through generic constraints
+    const ClientPresenceShape = Shape.plain.object({
+      type: Shape.plain.string("client"),
+      name: Shape.plain.string(),
+    })
+    const ServerPresenceShape = Shape.plain.object({
+      type: Shape.plain.string("server"),
+      tick: Shape.plain.number(),
+    })
+    const GamePresenceSchema = Shape.plain.discriminatedUnion("type", {
+      client: ClientPresenceShape,
+      server: ServerPresenceShape,
+    })
+
+    // Simulate the constraint used in usePresence: <S extends ContainerShape | ValueShape>
+    type TestInfer<S extends ContainerShape | ValueShape> = Infer<S>
+
+    type Result = TestInfer<typeof GamePresenceSchema>
+
+    type Expected =
+      | { type: "client"; name: string }
+      | { type: "server"; tick: number }
+
+    expectTypeOf<Result>().toEqualTypeOf<Expected>()
+  })
+})