@loro-extended/change 0.6.0 → 0.8.0

package/README.md

@@ -32,7 +32,7 @@ import { TypedDoc, Shape } from "@loro-extended/change";
 
 // Define your document schema
 const schema = Shape.doc({
-  title: Shape.text(),
+  title: Shape.text().placeholder("My Todo List"),
   todos: Shape.list(
     Shape.plain.object({
       id: Shape.plain.string(),
@@ -42,14 +42,8 @@ const schema = Shape.doc({
   ),
 });
 
-// Define empty state (default values)
-const emptyState = {
-  title: "My Todo List",
-  todos: [],
-};
-
 // Create a typed document
-const doc = new TypedDoc(schema, emptyState);
+const doc = new TypedDoc(schema);
 
 // Make changes with natural syntax
 const result = doc.change((draft) => {
@@ -109,19 +103,26 @@ const blogSchema = Shape.doc({
 Empty state provides default values that are merged when CRDT containers are empty, keeping the whole document typesafe:
 
 ```typescript
-const emptyState = {
-  title: "Untitled Document", // unusual empty state, but technically ok
-  viewCount: 0,
-  tags: [],
-  metadata: {
-    author: "Anonymous",
-    publishedAt: "",
-    featured: false,
-  },
-  sections: [],
-};
+// Use .placeholder() to set default values
+const blogSchemaWithDefaults = Shape.doc({
+  title: Shape.text().placeholder("Untitled Document"),
+  viewCount: Shape.counter(), // defaults to 0
+  tags: Shape.list(Shape.plain.string()), // defaults to []
+  metadata: Shape.map({
+    author: Shape.plain.string().placeholder("Anonymous"),
+    publishedAt: Shape.plain.string(), // defaults to ""
+    featured: Shape.plain.boolean(), // defaults to false
+  }),
+  sections: Shape.movableList(
+    Shape.map({
+      heading: Shape.text(),
+      content: Shape.text(),
+      order: Shape.plain.number(),
+    })
+  ),
+});
 
-const doc = new TypedDoc(blogSchema, emptyState);
+const doc = new TypedDoc(blogSchemaWithDefaults);
 
 // Initially returns empty state
 console.log(doc.value);
@@ -351,13 +352,13 @@ doc.change((draft) => {
 
 ### Core Functions
 
-#### `new TypedDoc<T>(schema, emptyState, existingDoc?)`
+#### `new TypedDoc<T>(schema, existingDoc?)`
 
 Creates a new typed Loro document.
 
 ```typescript
-const doc = new TypedDoc(schema, emptyState);
-const docFromExisting = new TypedDoc(schema, emptyState, existingLoroDoc);
+const doc = new TypedDoc(schema);
+const docFromExisting = new TypedDoc(schema, existingLoroDoc);
 ```
 
 #### `doc.change(mutator)`
@@ -571,14 +572,8 @@ const todoSchema = Shape.doc({
   ),
 });
 
-// Define empty state that matches your interface
-const emptyState: TodoDoc = {
-  title: "My Todos",
-  todos: [],
-};
-
 // TypeScript will ensure the schema produces the correct type
-const doc = new TypedDoc(todoSchema, emptyState);
+const doc = new TypedDoc(todoSchema);
 
 // The result will be properly typed as TodoDoc
 const result: TodoDoc = doc.change((draft) => {
@@ -610,7 +605,7 @@ import { LoroDoc } from "loro-crdt";
 
 // Wrap existing LoroDoc
 const existingDoc = new LoroDoc();
-const typedDoc = new TypedDoc(schema, emptyState, existingDoc);
+const typedDoc = new TypedDoc(schema, existingDoc);
 
 // Access underlying LoroDoc
 const loroDoc = typedDoc.loroDoc;

package/dist/index.d.ts

@@ -1,20 +1,53 @@
 import { LoroList, LoroMovableList, Container, LoroMap, Value, LoroText, LoroCounter, LoroTree, LoroDoc } from 'loro-crdt';
 
-type InferPlainType<T> = T extends Shape<infer P, any, any> ? P : never;
+/**
+ * Infers the plain (JSON-serializable) type from any Shape.
+ *
+ * This is the recommended way to extract types from shapes.
+ * Works with DocShape, ContainerShape, and ValueShape.
+ *
+ * @example
+ * ```typescript
+ * const ChatSchema = Shape.doc({
+ *   messages: Shape.list(Shape.map({
+ *     id: Shape.plain.string(),
+ *     content: Shape.text(),
+ *   })),
+ * })
+ *
+ * // Extract the document type
+ * type ChatDoc = Infer<typeof ChatSchema>
+ * // Result: { messages: { id: string; content: string }[] }
+ *
+ * const PresenceSchema = Shape.plain.object({
+ *   name: Shape.plain.string(),
+ *   cursor: Shape.plain.object({ x: Shape.plain.number(), y: Shape.plain.number() }),
+ * })
+ *
+ * // Extract the presence type
+ * type Presence = Infer<typeof PresenceSchema>
+ * // Result: { name: string; cursor: { x: number; y: number } }
+ * ```
+ */
+type Infer<T> = T extends Shape<infer P, any, any> ? P : never;
 type InferDraftType<T> = T extends Shape<any, infer D, any> ? D : never;
 /**
- * Extracts the valid empty state type from a shape.
+ * Extracts the valid placeholder type from a shape.
  *
  * For dynamic containers (list, record, etc.), this will be constrained to
  * empty values ([] or {}) to prevent users from expecting per-entry merging.
  */
-type InferEmptyStateType<T> = T extends Shape<any, any, infer E> ? E : never;
+type InferPlaceholderType<T> = T extends Shape<any, any, infer P> ? P : never;
 type Draft<T extends DocShape<Record<string, ContainerShape>>> = InferDraftType<T>;
+type DeepReadonly<T> = {
+    readonly [P in keyof T]: DeepReadonly<T[P]>;
+};
 
 type DraftNodeParams<Shape extends DocShape | ContainerShape> = {
     shape: Shape;
-    emptyState?: InferPlainType<Shape>;
+    placeholder?: Infer<Shape>;
     getContainer: () => ShapeToContainer<Shape>;
+    readonly?: boolean;
 };
 declare abstract class DraftNode<Shape extends DocShape | ContainerShape> {
     protected _params: DraftNodeParams<Shape>;
@@ -22,7 +55,8 @@ declare abstract class DraftNode<Shape extends DocShape | ContainerShape> {
     constructor(_params: DraftNodeParams<Shape>);
     abstract absorbPlainValues(): void;
     protected get shape(): Shape;
-    protected get emptyState(): InferPlainType<Shape> | undefined;
+    protected get placeholder(): Infer<Shape> | undefined;
+    protected get readonly(): boolean;
     protected get container(): ShapeToContainer<Shape>;
 }
 
@@ -43,7 +77,7 @@ declare abstract class ListDraftNodeBase<NestedShape extends ContainerOrValueSha
     protected pushWithConversion(item: Item): void;
     getDraftNodeParams(index: number, shape: ContainerShape): DraftNodeParams<ContainerShape>;
     protected getPredicateItem(index: number): Item;
-    protected getDraftItem(index: number): DraftItem;
+    protected getDraftItem(index: number): any;
     find(predicate: (item: Item, index: number) => boolean): DraftItem | undefined;
     findIndex(predicate: (item: Item, index: number) => boolean): number;
     map<ReturnType>(callback: (item: Item, index: number) => ReturnType): ReturnType[];
@@ -64,6 +98,7 @@ declare abstract class ListDraftNodeBase<NestedShape extends ContainerOrValueSha
 }
 
 declare class ListDraftNode<NestedShape extends ContainerOrValueShape> extends ListDraftNodeBase<NestedShape> {
+    [index: number]: Infer<NestedShape>;
     protected get container(): LoroList;
     protected absorbValueAtIndex(index: number, value: any): void;
 }
@@ -75,7 +110,7 @@ declare class MapDraftNode<NestedShapes extends Record<string, ContainerOrValueS
     protected get container(): LoroMap;
     absorbPlainValues(): void;
     getDraftNodeParams<S extends ContainerShape>(key: string, shape: S): DraftNodeParams<ContainerShape>;
-    getOrCreateNode<Shape extends ContainerShape | ValueShape>(key: string, shape: Shape): Shape extends ContainerShape ? DraftNode<Shape> : Value;
+    getOrCreateNode<Shape extends ContainerShape | ValueShape>(key: string, shape: Shape): any;
     private createLazyProperties;
     get(key: string): any;
     set(key: string, value: Value): void;
@@ -88,6 +123,7 @@ declare class MapDraftNode<NestedShapes extends Record<string, ContainerOrValueS
 }
 
 declare class MovableListDraftNode<NestedShape extends ContainerOrValueShape, Item = NestedShape["_plain"]> extends ListDraftNodeBase<NestedShape> {
+    [index: number]: Infer<NestedShape>;
     protected get container(): LoroMovableList;
     protected absorbValueAtIndex(index: number, value: any): void;
     move(from: number, to: number): void;
@@ -95,13 +131,13 @@ declare class MovableListDraftNode<NestedShape extends ContainerOrValueShape, It
 }
 
 declare class RecordDraftNode<NestedShape extends ContainerOrValueShape> extends DraftNode<any> {
+    [key: string]: Infer<NestedShape> | any;
     private nodeCache;
-    constructor(params: DraftNodeParams<RecordContainerShape<NestedShape>>);
     protected get shape(): RecordContainerShape<NestedShape>;
     protected get container(): LoroMap;
     absorbPlainValues(): void;
     getDraftNodeParams<S extends ContainerShape>(key: string, shape: S): DraftNodeParams<ContainerShape>;
-    getOrCreateNode(key: string): InferDraftType<NestedShape>;
+    getOrCreateNode(key: string): any;
     get(key: string): InferDraftType<NestedShape>;
     set(key: string, value: any): void;
     setContainer<C extends Container>(key: string, container: C): C;
@@ -131,12 +167,15 @@ declare class TextDraftNode extends DraftNode<TextContainerShape> {
     get length(): number;
 }
 
+type WithPlaceholder<S extends Shape<any, any, any>> = S & {
+    placeholder(value: S["_placeholder"]): S;
+};
 interface DocShape<NestedShapes extends Record<string, ContainerShape> = Record<string, ContainerShape>> 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";
     readonly shapes: NestedShapes;
@@ -164,7 +203,7 @@ interface MapContainerShape<NestedShapes extends Record<string, ContainerOrValue
 }, 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";
     readonly shapes: NestedShapes;
@@ -205,7 +244,7 @@ interface ObjectValueShape<T extends Record<string, ValueShape> = Record<string,
 }, {
     [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";
@@ -221,7 +260,7 @@ interface ArrayValueShape<T extends ValueShape = ValueShape> extends Shape<T["_p
     readonly valueType: "array";
     readonly shape: T;
 }
-interface UnionValueShape<T extends ValueShape[] = ValueShape[]> extends Shape<T[number]["_plain"], T[number]["_draft"], T[number]["_emptyState"]> {
+interface UnionValueShape<T extends ValueShape[] = ValueShape[]> extends Shape<T[number]["_plain"], T[number]["_draft"], T[number]["_placeholder"]> {
     readonly _type: "value";
     readonly valueType: "union";
     readonly shapes: T;
@@ -239,7 +278,7 @@ interface UnionValueShape<T extends ValueShape[] = ValueShape[]> extends Shape<T
  * @typeParam K - The discriminant key (e.g., "type")
  * @typeParam T - A record mapping discriminant values to their object shapes
  */
-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]["_emptyState"]> {
+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"]> {
     readonly _type: "value";
     readonly valueType: "discriminatedUnion";
     readonly discriminantKey: K;
@@ -247,11 +286,11 @@ interface DiscriminatedUnionValueShape<K extends string = string, T extends Reco
 }
 type ValueShape = StringValueShape | NumberValueShape | BooleanValueShape | NullValueShape | UndefinedValueShape | Uint8ArrayValueShape | ObjectValueShape | RecordValueShape | ArrayValueShape | UnionValueShape | DiscriminatedUnionValueShape;
 type ContainerOrValueShape = ContainerShape | ValueShape;
-interface Shape<Plain, Draft, EmptyState = Plain> {
+interface Shape<Plain, Draft, Placeholder = Plain> {
     readonly _type: string;
     readonly _plain: Plain;
     readonly _draft: Draft;
-    readonly _emptyState: EmptyState;
+    readonly _placeholder: Placeholder;
 }
 /**
  * The LoroShape factory object
@@ -262,24 +301,24 @@ interface Shape<Plain, Draft, EmptyState = Plain> {
  */
 declare const Shape: {
     doc: <T extends Record<string, ContainerShape>>(shape: T) => DocShape<T>;
-    counter: () => CounterContainerShape;
+    counter: () => WithPlaceholder<CounterContainerShape>;
     list: <T extends ContainerOrValueShape>(shape: T) => ListContainerShape<T>;
     map: <T extends Record<string, ContainerOrValueShape>>(shape: T) => MapContainerShape<T>;
     record: <T extends ContainerOrValueShape>(shape: T) => RecordContainerShape<T>;
     movableList: <T extends ContainerOrValueShape>(shape: T) => MovableListContainerShape<T>;
-    text: () => TextContainerShape;
+    text: () => WithPlaceholder<TextContainerShape>;
     tree: <T extends MapContainerShape>(shape: T) => TreeContainerShape;
     plain: {
-        string: <T extends string = string>(...options: T[]) => StringValueShape<T>;
-        number: () => NumberValueShape;
-        boolean: () => BooleanValueShape;
+        string: <T extends string = string>(...options: T[]) => WithPlaceholder<StringValueShape<T>>;
+        number: () => WithPlaceholder<NumberValueShape>;
+        boolean: () => WithPlaceholder<BooleanValueShape>;
         null: () => NullValueShape;
         undefined: () => UndefinedValueShape;
         uint8Array: () => Uint8ArrayValueShape;
         object: <T extends Record<string, ValueShape>>(shape: T) => ObjectValueShape<T>;
         record: <T extends ValueShape>(shape: T) => RecordValueShape<T>;
         array: <T extends ValueShape>(shape: T) => ArrayValueShape<T>;
-        union: <T extends ValueShape[]>(shapes: T) => UnionValueShape<T>;
+        union: <T extends ValueShape[]>(shapes: T) => WithPlaceholder<UnionValueShape<T>>;
         /**
          * Creates a discriminated union shape for type-safe tagged unions.
          *
@@ -306,11 +345,41 @@ declare const Shape: {
          * @param discriminantKey - The key used to discriminate between variants (e.g., "type")
          * @param variants - A record mapping discriminant values to their object shapes
          */
-        discriminatedUnion: <K extends string, T extends Record<string, ObjectValueShape>>(discriminantKey: K, variants: T) => DiscriminatedUnionValueShape<K, T>;
+        discriminatedUnion: <K extends string, T extends Record<string, ObjectValueShape>>(discriminantKey: K, variants: T) => WithPlaceholder<DiscriminatedUnionValueShape<K, T>>;
     };
 };
 type ShapeToContainer<T extends DocShape | ContainerShape> = T extends TextContainerShape ? LoroText : T extends CounterContainerShape ? LoroCounter : T extends ListContainerShape ? LoroList : T extends MovableListContainerShape ? LoroMovableList : T extends MapContainerShape | RecordContainerShape ? LoroMap : T extends TreeContainerShape ? LoroTree : never;
 
+/**
+ * Derives the placeholder state from a schema by composing placeholder values.
+ *
+ * For leaf nodes (text, counter, values): uses _placeholder directly
+ * For containers (map, list, record): recurses into nested shapes
+ */
+declare function derivePlaceholder<T extends DocShape>(schema: T): InferPlaceholderType<T>;
+/**
+ * Derives placeholder for a single shape.
+ *
+ * Leaf nodes: return _placeholder directly
+ * Containers: recurse into nested shapes (ignore _placeholder on containers)
+ */
+declare function deriveShapePlaceholder(shape: ContainerOrValueShape): unknown;
+
+/**
+ * Overlays CRDT state with placeholder defaults
+ */
+declare function overlayPlaceholder<Shape extends DocShape>(shape: Shape, crdtValue: {
+    [key: string]: Value;
+}, placeholderValue: {
+    [key: string]: Value;
+}): {
+    [key: string]: Value;
+};
+/**
+ * Merges individual CRDT values with placeholder defaults
+ */
+declare function mergeValue<Shape extends ContainerShape | ValueShape>(shape: Shape, crdtValue: Value, placeholderValue: Value): Value;
+
 /** biome-ignore-all lint/suspicious/noExplicitAny: JSON Patch values can be any type */
 
 type JsonPatchAddOperation = {
@@ -349,20 +418,28 @@ type JsonPatch = JsonPatchOperation[];
 
 declare class TypedDoc<Shape extends DocShape> {
     private shape;
-    private emptyState;
+    private placeholder;
     private doc;
     /**
-     * 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(shape: Shape, emptyState: InferEmptyStateType<Shape>, doc?: LoroDoc);
-    get value(): InferPlainType<Shape>;
-    change(fn: (draft: Draft<Shape>) => void): InferPlainType<Shape>;
+    constructor(shape: Shape, doc?: LoroDoc);
+    /**
+     * 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>>;
+    /**
+     * 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>;
+    change(fn: (draft: Draft<Shape>) => void): Infer<Shape>;
     /**
      * Apply JSON Patch operations to the document
      *
@@ -378,32 +455,17 @@ declare class TypedDoc<Shape extends DocShape> {
      * ])
      * ```
      */
-    applyPatch(patch: JsonPatch, pathPrefix?: (string | number)[]): InferPlainType<Shape>;
+    applyPatch(patch: JsonPatch, pathPrefix?: (string | number)[]): Infer<Shape>;
     get loroDoc(): LoroDoc;
     get docShape(): Shape;
     get rawValue(): any;
 }
-declare function createTypedDoc<Shape extends DocShape>(shape: Shape, emptyState: InferEmptyStateType<Shape>, existingDoc?: LoroDoc): TypedDoc<Shape>;
-
-/**
- * Overlays CRDT state with empty state defaults
- */
-declare function overlayEmptyState<Shape extends DocShape>(shape: Shape, crdtValue: {
-    [key: string]: Value;
-}, emptyValue: {
-    [key: string]: Value;
-}): {
-    [key: string]: Value;
-};
-/**
- * Merges individual CRDT values with empty state defaults
- */
-declare function mergeValue<Shape extends ContainerShape | ValueShape>(shape: Shape, crdtValue: Value, emptyValue: Value): Value;
+declare function createTypedDoc<Shape extends DocShape>(shape: Shape, existingDoc?: LoroDoc): TypedDoc<Shape>;
 
 /**
- * Validates empty state against schema structure without using Zod
- * Combines the functionality of createEmptyStateValidator and createValueValidator
+ * Validates placeholder against schema structure without using Zod
+ * Combines the functionality of createPlaceholderValidator and createValueValidator
  */
-declare function validateEmptyState<T extends DocShape>(emptyState: unknown, schema: T): InferPlainType<T>;
+declare function validatePlaceholder<T extends DocShape>(placeholder: unknown, schema: T): Infer<T>;
 
-export { type ArrayValueShape, type ContainerOrValueShape, type ContainerShape, type CounterContainerShape, type DiscriminatedUnionValueShape, type DocShape, type Draft, type InferDraftType, type InferEmptyStateType, type InferPlainType, type ListContainerShape, type MapContainerShape, type MovableListContainerShape, type ObjectValueShape, type RecordContainerShape, type RecordValueShape, type ContainerType as RootContainerType, Shape, type TextContainerShape, type TreeContainerShape, TypedDoc, type UnionValueShape, type ValueShape, createTypedDoc, mergeValue, overlayEmptyState, validateEmptyState };
+export { type ArrayValueShape, type ContainerOrValueShape, type ContainerShape, type CounterContainerShape, type DeepReadonly, type DiscriminatedUnionValueShape, type DocShape, type Draft, type Infer, type InferDraftType, type InferPlaceholderType, type ListContainerShape, type MapContainerShape, type MovableListContainerShape, type ObjectValueShape, type RecordContainerShape, type RecordValueShape, type ContainerType as RootContainerType, Shape, type TextContainerShape, type TreeContainerShape, TypedDoc, type UnionValueShape, type ValueShape, type WithPlaceholder, createTypedDoc, derivePlaceholder, deriveShapePlaceholder, mergeValue, overlayPlaceholder, validatePlaceholder };