@pluv/crdt-loro 1.0.1 → 2.0.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @pluv/crdt-loro@1.0.1 build /home/runner/work/pluv/pluv/packages/crdt-loro
+> @pluv/crdt-loro@2.0.0 build /home/runner/work/pluv/pluv/packages/crdt-loro
 > tsup src/index.ts --format esm,cjs --dts
 
 CLI Building entry: src/index.ts
@@ -8,11 +8,11 @@
 CLI Target: es6
 ESM Build start
 CJS Build start
-ESM dist/index.mjs 8.73 KB
-ESM ⚡️ Build success in 83ms
-CJS dist/index.js 9.78 KB
-CJS ⚡️ Build success in 82ms
+ESM dist/index.mjs 14.35 KB
+ESM ⚡️ Build success in 71ms
+CJS dist/index.js 15.55 KB
+CJS ⚡️ Build success in 77ms
 DTS Build start
-DTS ⚡️ Build success in 2550ms
-DTS dist/index.d.mts 3.46 KB
-DTS dist/index.d.ts  3.46 KB
+DTS ⚡️ Build success in 4019ms
+DTS dist/index.d.mts 4.57 KB
+DTS dist/index.d.ts  4.57 KB

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # @pluv/crdt-loro
 
+## 2.0.0
+
+### Minor Changes
+
+- 0b234d1: **Deprecated** Declaring top-level types on your CRDT storage via the `loro` utility (e.g. `loro.list`) is now deprecated, to be removed in the next major release (v2). Continuing to use the `loro` utility to declare top-level types will log a warning to your console while in development mode (i.e. when `process.env.NODE_ENV === "development"`). To declare top-level types, you should now use the builder type exposed in the storage factory function. See the example below:
+
+  ```ts
+  import { loro } from "@pluv/crdt-loro";
+
+  // Before
+  loro.doc(() => ({
+    // Using the `loro` utility (in this case `loro.map`) when declaring
+    // top-level types is now deprecated
+    topType: loro.map({
+      key1: loro.text(""),
+      key2: loro.text(""),
+    }),
+  }));
+
+  // After
+  loro.doc((t) => ({
+    // Top-level properties must now use the builder (in this case `t`).
+    // This effectively calls `loro.getMap("topType")` to instantiate the type on
+    // the root document.
+    // This simply returns the native Loro container type (e.g. LoroMap), which
+    // allows you operate on your loro container types in a more native way.
+    topType: t.map("topType", {
+      // Declaring nested types should continue to use the `loro` utilities
+      // you've used before
+      key1: loro.text(""),
+      key2: loro.text(""),
+    }),
+  }));
+  ```
+
+  The functions on the builder type calls the native loro container instantiating methods and returns the native types (e.g. `t.map("topType")` is simply just a `LoroDoc.getMap("topType")`) call under the hood. This allows you to declare your type in a more loro-native and predictable way, and enables declaring more complex initial storage states if needed.
+
+### Patch Changes
+
+- Updated dependencies [047a1d8]
+  - @pluv/types@2.0.0
+  - @pluv/crdt@2.0.0
+
+## 1.0.2
+
+### Patch Changes
+
+- @pluv/crdt@1.0.2
+- @pluv/types@1.0.2
+
 ## 1.0.1
 
 ### Patch Changes

package/dist/index.d.mts

@@ -1,16 +1,31 @@
-import { CrdtType, AbstractCrdtDoc, DocApplyEncodedStateParams, DocBatchApplyEncodedStateParams, InferCrdtJson, DocSubscribeCallbackParams, AbstractCrdtDocFactory } from '@pluv/crdt';
-import { LoroDoc, LoroList, LoroMap, LoroMovableList, LoroText, LoroTree } from 'loro-crdt';
+import * as loro_crdt from 'loro-crdt';
+import { LoroCounter, LoroDoc, LoroList, LoroMap, LoroMovableList, LoroText, LoroTree } from 'loro-crdt';
+import { CrdtType, DocApplyEncodedStateParams, DocBatchApplyEncodedStateParams, InferCrdtJson, DocSubscribeCallbackParams, AbstractCrdtDocFactory } from '@pluv/crdt';
+import { CrdtDocLike } from '@pluv/types';
+
+declare const counter: () => LoroCounter;
 
 type LoroType<TValue extends unknown, TJson extends unknown = any> = TValue & CrdtType<TValue, TJson> & {
     toJSON?: () => any;
     toString?: () => string;
 };
 
-declare class CrdtLoroDoc<TStorage extends Record<string, LoroType<any, any>>> extends AbstractCrdtDoc<TStorage> {
+type LoroBuilder = ReturnType<typeof builder>;
+declare const builder: (doc: LoroDoc) => {
+    counter(name: string): LoroCounter;
+    list<T extends unknown>(name: string, value?: T[] | readonly T[]): LoroType<LoroList<T>, T[]>;
+    map<T extends Record<string, unknown>>(name: string, value?: T): LoroType<LoroMap<T>, T>;
+    moveableList<T extends unknown>(name: string, value?: T[] | readonly T[]): LoroType<LoroMovableList<T>, T[]>;
+    text(name: string, value?: string): LoroType<LoroText, string>;
+    tree(name: string): loro_crdt.LoroTree<Record<string, unknown>>;
+};
+
+type CrdtLoroDocParams<TStorage extends Record<string, LoroType<any, any>>> = (builder: LoroBuilder) => TStorage;
+declare class CrdtLoroDoc<TStorage extends Record<string, LoroType<any, any>>> implements CrdtDocLike<TStorage> {
     value: LoroDoc;
     private _storage;
     private _undoManager;
-    constructor(value?: TStorage);
+    constructor(params?: CrdtLoroDocParams<TStorage>);
     applyEncodedState(params: DocApplyEncodedStateParams): this;
     batchApplyEncodedState(params: DocBatchApplyEncodedStateParams): this;
     canRedo(): boolean;
@@ -22,7 +37,7 @@ declare class CrdtLoroDoc<TStorage extends Record<string, LoroType<any, any>>> e
     toJson(): InferCrdtJson<TStorage>;
     toJson<TKey extends keyof TStorage>(type: TKey): InferCrdtJson<TStorage[TKey]>;
     isEmpty(): boolean;
-    rebuildStorage(): this;
+    rebuildStorage(reference: TStorage): this;
     redo(): this;
     subscribe(listener: (params: DocSubscribeCallbackParams<TStorage>) => void): () => void;
     track(): this;
@@ -32,17 +47,18 @@ declare class CrdtLoroDoc<TStorage extends Record<string, LoroType<any, any>>> e
      */
     transact(fn: () => void): this;
     undo(): this;
+    private _warn;
 }
 
 declare class CrdtLoroDocFactory<TStorage extends Record<string, LoroType<any, any>>> extends AbstractCrdtDocFactory<TStorage> {
-    private _initialStorage;
-    constructor(initialStorage?: () => TStorage);
+    readonly _initialStorage: (builder: LoroBuilder) => TStorage;
+    constructor(initialStorage?: (builder: LoroBuilder) => TStorage);
     getEmpty(): CrdtLoroDoc<TStorage>;
-    getFactory(initialStorage?: (() => TStorage) | undefined): CrdtLoroDocFactory<TStorage>;
-    getInitialized(initialStorage?: () => TStorage): CrdtLoroDoc<TStorage>;
+    getFactory(initialStorage?: ((builder: LoroBuilder) => TStorage) | undefined): CrdtLoroDocFactory<TStorage>;
+    getInitialized(initialStorage?: (builder: LoroBuilder) => TStorage): CrdtLoroDoc<TStorage>;
 }
 
-declare const doc: <TStorage extends Record<string, LoroType<any, any>>>(value?: () => TStorage) => CrdtLoroDocFactory<TStorage>;
+declare const doc: <TStorage extends Record<string, LoroType<any, any>>>(value?: (builder: LoroBuilder) => TStorage) => CrdtLoroDocFactory<TStorage>;
 
 declare const list: <T extends unknown>(value?: T[] | readonly T[]) => LoroType<LoroList<T>, T[]>;
 
@@ -60,7 +76,9 @@ declare const kind: "loro";
 
 type loro_CrdtLoroDoc<TStorage extends Record<string, LoroType<any, any>>> = CrdtLoroDoc<TStorage>;
 declare const loro_CrdtLoroDoc: typeof CrdtLoroDoc;
+type loro_LoroBuilder = LoroBuilder;
 type loro_LoroType<TValue extends unknown, TJson extends unknown = any> = LoroType<TValue, TJson>;
+declare const loro_counter: typeof counter;
 declare const loro_doc: typeof doc;
 declare const loro_kind: typeof kind;
 declare const loro_list: typeof list;
@@ -70,7 +88,7 @@ declare const loro_object: typeof object;
 declare const loro_text: typeof text;
 declare const loro_tree: typeof tree;
 declare namespace loro {
-  export { loro_CrdtLoroDoc as CrdtLoroDoc, type loro_LoroType as LoroType, loro_doc as doc, loro_kind as kind, loro_list as list, loro_map as map, loro_movableList as movableList, loro_object as object, loro_text as text, loro_tree as tree };
+  export { loro_CrdtLoroDoc as CrdtLoroDoc, type loro_LoroBuilder as LoroBuilder, type loro_LoroType as LoroType, loro_counter as counter, loro_doc as doc, loro_kind as kind, loro_list as list, loro_map as map, loro_movableList as movableList, loro_object as object, loro_text as text, loro_tree as tree };
 }
 
 export { loro };

package/dist/index.d.ts

@@ -1,16 +1,31 @@
-import { CrdtType, AbstractCrdtDoc, DocApplyEncodedStateParams, DocBatchApplyEncodedStateParams, InferCrdtJson, DocSubscribeCallbackParams, AbstractCrdtDocFactory } from '@pluv/crdt';
-import { LoroDoc, LoroList, LoroMap, LoroMovableList, LoroText, LoroTree } from 'loro-crdt';
+import * as loro_crdt from 'loro-crdt';
+import { LoroCounter, LoroDoc, LoroList, LoroMap, LoroMovableList, LoroText, LoroTree } from 'loro-crdt';
+import { CrdtType, DocApplyEncodedStateParams, DocBatchApplyEncodedStateParams, InferCrdtJson, DocSubscribeCallbackParams, AbstractCrdtDocFactory } from '@pluv/crdt';
+import { CrdtDocLike } from '@pluv/types';
+
+declare const counter: () => LoroCounter;
 
 type LoroType<TValue extends unknown, TJson extends unknown = any> = TValue & CrdtType<TValue, TJson> & {
     toJSON?: () => any;
     toString?: () => string;
 };
 
-declare class CrdtLoroDoc<TStorage extends Record<string, LoroType<any, any>>> extends AbstractCrdtDoc<TStorage> {
+type LoroBuilder = ReturnType<typeof builder>;
+declare const builder: (doc: LoroDoc) => {
+    counter(name: string): LoroCounter;
+    list<T extends unknown>(name: string, value?: T[] | readonly T[]): LoroType<LoroList<T>, T[]>;
+    map<T extends Record<string, unknown>>(name: string, value?: T): LoroType<LoroMap<T>, T>;
+    moveableList<T extends unknown>(name: string, value?: T[] | readonly T[]): LoroType<LoroMovableList<T>, T[]>;
+    text(name: string, value?: string): LoroType<LoroText, string>;
+    tree(name: string): loro_crdt.LoroTree<Record<string, unknown>>;
+};
+
+type CrdtLoroDocParams<TStorage extends Record<string, LoroType<any, any>>> = (builder: LoroBuilder) => TStorage;
+declare class CrdtLoroDoc<TStorage extends Record<string, LoroType<any, any>>> implements CrdtDocLike<TStorage> {
     value: LoroDoc;
     private _storage;
     private _undoManager;
-    constructor(value?: TStorage);
+    constructor(params?: CrdtLoroDocParams<TStorage>);
     applyEncodedState(params: DocApplyEncodedStateParams): this;
     batchApplyEncodedState(params: DocBatchApplyEncodedStateParams): this;
     canRedo(): boolean;
@@ -22,7 +37,7 @@ declare class CrdtLoroDoc<TStorage extends Record<string, LoroType<any, any>>> e
     toJson(): InferCrdtJson<TStorage>;
     toJson<TKey extends keyof TStorage>(type: TKey): InferCrdtJson<TStorage[TKey]>;
     isEmpty(): boolean;
-    rebuildStorage(): this;
+    rebuildStorage(reference: TStorage): this;
     redo(): this;
     subscribe(listener: (params: DocSubscribeCallbackParams<TStorage>) => void): () => void;
     track(): this;
@@ -32,17 +47,18 @@ declare class CrdtLoroDoc<TStorage extends Record<string, LoroType<any, any>>> e
      */
     transact(fn: () => void): this;
     undo(): this;
+    private _warn;
 }
 
 declare class CrdtLoroDocFactory<TStorage extends Record<string, LoroType<any, any>>> extends AbstractCrdtDocFactory<TStorage> {
-    private _initialStorage;
-    constructor(initialStorage?: () => TStorage);
+    readonly _initialStorage: (builder: LoroBuilder) => TStorage;
+    constructor(initialStorage?: (builder: LoroBuilder) => TStorage);
     getEmpty(): CrdtLoroDoc<TStorage>;
-    getFactory(initialStorage?: (() => TStorage) | undefined): CrdtLoroDocFactory<TStorage>;
-    getInitialized(initialStorage?: () => TStorage): CrdtLoroDoc<TStorage>;
+    getFactory(initialStorage?: ((builder: LoroBuilder) => TStorage) | undefined): CrdtLoroDocFactory<TStorage>;
+    getInitialized(initialStorage?: (builder: LoroBuilder) => TStorage): CrdtLoroDoc<TStorage>;
 }
 
-declare const doc: <TStorage extends Record<string, LoroType<any, any>>>(value?: () => TStorage) => CrdtLoroDocFactory<TStorage>;
+declare const doc: <TStorage extends Record<string, LoroType<any, any>>>(value?: (builder: LoroBuilder) => TStorage) => CrdtLoroDocFactory<TStorage>;
 
 declare const list: <T extends unknown>(value?: T[] | readonly T[]) => LoroType<LoroList<T>, T[]>;
 
@@ -60,7 +76,9 @@ declare const kind: "loro";
 
 type loro_CrdtLoroDoc<TStorage extends Record<string, LoroType<any, any>>> = CrdtLoroDoc<TStorage>;
 declare const loro_CrdtLoroDoc: typeof CrdtLoroDoc;
+type loro_LoroBuilder = LoroBuilder;
 type loro_LoroType<TValue extends unknown, TJson extends unknown = any> = LoroType<TValue, TJson>;
+declare const loro_counter: typeof counter;
 declare const loro_doc: typeof doc;
 declare const loro_kind: typeof kind;
 declare const loro_list: typeof list;
@@ -70,7 +88,7 @@ declare const loro_object: typeof object;
 declare const loro_text: typeof text;
 declare const loro_tree: typeof tree;
 declare namespace loro {
-  export { loro_CrdtLoroDoc as CrdtLoroDoc, type loro_LoroType as LoroType, loro_doc as doc, loro_kind as kind, loro_list as list, loro_map as map, loro_movableList as movableList, loro_object as object, loro_text as text, loro_tree as tree };
+  export { loro_CrdtLoroDoc as CrdtLoroDoc, type loro_LoroBuilder as LoroBuilder, type loro_LoroType as LoroType, loro_counter as counter, loro_doc as doc, loro_kind as kind, loro_list as list, loro_map as map, loro_movableList as movableList, loro_object as object, loro_text as text, loro_tree as tree };
 }
 
 export { loro };

package/dist/index.js

@@ -45,6 +45,7 @@ module.exports = __toCommonJS(index_exports);
 var loro_exports = {};
 __export(loro_exports, {
   CrdtLoroDoc: () => CrdtLoroDoc,
+  counter: () => counter,
   doc: () => doc,
   kind: () => kind,
   list: () => list,
@@ -55,39 +56,151 @@ __export(loro_exports, {
   tree: () => tree
 });
 
+// src/counter.ts
+var import_loro_crdt = require("loro-crdt");
+var counter = () => {
+  const counter2 = new import_loro_crdt.LoroCounter();
+  return counter2;
+};
+
 // src/doc/CrdtLoroDoc.ts
-var import_crdt = require("@pluv/crdt");
 var import_js_base64 = require("js-base64");
-var import_loro_crdt = require("loro-crdt");
+var import_loro_crdt3 = require("loro-crdt");
+
+// src/utils/oneLine.ts
+var oneLine = (strings, ...values) => {
+  return strings.map((str) => str.replace(/\s+/g, " ").trim()).reduce((acc, str, i) => acc + str + (i < values.length ? values[i] : ""), "").replace(/\s+/g, " ").trim();
+};
+
+// src/doc/builder.ts
+var import_loro_crdt2 = require("loro-crdt");
+var builder = (doc2) => {
+  return {
+    counter(name) {
+      return doc2.getCounter(name);
+    },
+    list(name, value = []) {
+      const list2 = doc2.getList(name);
+      value.forEach((item, i) => {
+        if ((0, import_loro_crdt2.isContainer)(item)) list2.insertContainer(i, item);
+        else list2.insert(i, item);
+      });
+      return list2;
+    },
+    map(name, value = {}) {
+      const container = doc2.getMap(name);
+      Object.entries(value).forEach(([key, item]) => {
+        if ((0, import_loro_crdt2.isContainer)(item)) container.setContainer(key, item);
+        else container.set(key, item);
+      });
+      return container;
+    },
+    moveableList(name, value = []) {
+      const list2 = doc2.getMovableList(name);
+      value.forEach((item, i) => {
+        if ((0, import_loro_crdt2.isContainer)(item)) list2.insertContainer(i, item);
+        else list2.insert(i, item);
+      });
+      return list2;
+    },
+    text(name, value = "") {
+      const text2 = doc2.getText(name);
+      text2.insert(0, value);
+      return text2;
+    },
+    tree(name) {
+      return doc2.getTree(name);
+    }
+  };
+};
+
+// src/doc/CrdtLoroDoc.ts
 var MAX_UNDO_STEPS = 100;
 var MERGE_INTERVAL_MS = 1e3;
-var CrdtLoroDoc = class extends import_crdt.AbstractCrdtDoc {
-  constructor(value = {}) {
-    super();
-    this.value = new import_loro_crdt.LoroDoc();
+var CrdtLoroDoc = class {
+  constructor(params = () => ({})) {
+    this.value = new import_loro_crdt3.LoroDoc();
     this._undoManager = null;
-    this._storage = Object.entries(value).reduce((acc, [key, node]) => {
-      if (node instanceof import_loro_crdt.LoroList) {
+    const storage = params(builder(this.value));
+    const keys = Object.keys(this.value.toJSON()).reduce(
+      (set, key) => set.add(key),
+      /* @__PURE__ */ new Set()
+    );
+    this._storage = Object.entries(storage).reduce((acc, [key, node]) => {
+      if (keys.has(key)) return __spreadProps(__spreadValues({}, acc), { [key]: node });
+      if (node instanceof import_loro_crdt3.LoroCounter) {
+        this._warn(oneLine`
+                    Warning: You are using \`loro.counter\` to declare top-level storage value \`${key}\`.
+                    Adding top-level values this way has been deprecated, to be removed in v2.
+                    Please follow the v2 migration guide to declare top-level types correctly:
+                    https://pluv.io/docs/migration-guides/v2
+                `);
+        const container = this.value.getCounter(key);
+        return __spreadProps(__spreadValues({}, acc), { [key]: container });
+      }
+      if (node instanceof import_loro_crdt3.LoroList) {
+        this._warn(oneLine`
+                    Warning: You are using \`loro.list\` to declare top-level storage value \`${key}\`.
+                    Adding top-level values this way has been deprecated, to be removed in v2.
+                    Please follow the v2 migration guide to declare top-level types correctly:
+                    https://pluv.io/docs/migration-guides/v2
+                `);
         const container = this.value.getList(key);
         node.toArray().forEach((item, i) => {
-          if ((0, import_loro_crdt.isContainer)(item)) container.insertContainer(i, item);
+          if ((0, import_loro_crdt3.isContainer)(item)) container.insertContainer(i, item);
           else container.insert(i, item);
         });
         return __spreadProps(__spreadValues({}, acc), { [key]: container });
       }
-      if (node instanceof import_loro_crdt.LoroMap) {
+      if (node instanceof import_loro_crdt3.LoroMap) {
+        this._warn(oneLine`
+                    Warning: You are using \`loro.map\` to declare top-level storage value \`${key}\`.
+                    Adding top-level values this way has been deprecated, to be removed in v2.
+                    Please follow the v2 migration guide to declare top-level types correctly:
+                    https://pluv.io/docs/migration-guides/v2
+                `);
         const container = this.value.getMap(key);
         container.entries().forEach(([key2, item]) => {
-          if ((0, import_loro_crdt.isContainer)(item)) container.setContainer(key2, item);
+          if ((0, import_loro_crdt3.isContainer)(item)) container.setContainer(key2, item);
           else container.set(key2, item);
         });
         return __spreadProps(__spreadValues({}, acc), { [key]: container });
       }
-      if (node instanceof import_loro_crdt.LoroText) {
+      if (node instanceof import_loro_crdt3.LoroMovableList) {
+        this._warn(oneLine`
+                    Warning: You are using \`loro.moveableList\` to declare top-level storage value \`${key}\`.
+                    Adding top-level values this way has been deprecated, to be removed in v2.
+                    Please follow the v2 migration guide to declare top-level types correctly:
+                    https://pluv.io/docs/migration-guides/v2
+                `);
+        const container = this.value.getMovableList(key);
+        node.toArray().forEach((item, i) => {
+          if ((0, import_loro_crdt3.isContainer)(item)) container.insertContainer(i, item);
+          else container.insert(i, item);
+        });
+        return __spreadProps(__spreadValues({}, acc), { [key]: container });
+      }
+      if (node instanceof import_loro_crdt3.LoroText) {
+        this._warn(oneLine`
+                    Warning: You are using \`loro.text\` to declare top-level storage value \`${key}\`.
+                    Adding top-level values this way has been deprecated, to be removed in v2.
+                    Please follow the v2 migration guide to declare top-level types correctly:
+                    https://pluv.io/docs/migration-guides/v2
+                `);
         const container = this.value.getText(key);
         container.insert(0, node.toString());
         return __spreadProps(__spreadValues({}, acc), { [key]: container });
       }
+      if (node instanceof import_loro_crdt3.LoroTree) {
+        this._warn(oneLine`
+                    Warning: You are using \`loro.tree\` to declare top-level storage value \`${key}\`.
+                    Adding top-level values this way has been deprecated, to be removed in v2.
+                    Please follow the v2 migration guide to declare top-level types correctly:
+                    https://pluv.io/docs/migration-guides/v2
+                `);
+        const container = this.value.getTree(key);
+        return __spreadProps(__spreadValues({}, acc), { [key]: container });
+      }
       return acc;
     }, {});
     this.value.commit();
@@ -143,11 +256,11 @@ var CrdtLoroDoc = class extends import_crdt.AbstractCrdtDoc {
   toJson(type) {
     if (typeof type === "string") {
       const container = this._storage[type];
-      return container instanceof import_loro_crdt.LoroText ? container.toString() : container instanceof import_loro_crdt.LoroCounter ? container.value : container.toJSON();
+      return container instanceof import_loro_crdt3.LoroText ? container.toString() : container instanceof import_loro_crdt3.LoroCounter ? container.value : container.toJSON();
     }
     return Object.entries(this._storage).reduce(
       (acc, [key, value]) => __spreadProps(__spreadValues({}, acc), {
-        [key]: value instanceof import_loro_crdt.LoroText ? value.toString() : value.toJSON()
+        [key]: value instanceof import_loro_crdt3.LoroText ? value.toString() : value.toJSON()
       }),
       {}
     );
@@ -156,16 +269,22 @@ var CrdtLoroDoc = class extends import_crdt.AbstractCrdtDoc {
     const serialized = this.value.toJSON();
     return !serialized || !Object.keys(serialized).length;
   }
-  rebuildStorage() {
+  rebuildStorage(reference) {
     const isBuilt = !!Object.keys(this._storage).length;
     if (isBuilt) {
       console.warn("Attempted to rebuild storage multiple times");
       return this;
     }
-    const keys = Object.keys(this.value.toJSON());
-    this._storage = keys.reduce((acc, key) => {
-      const container = this.value.getByPath(key);
-      return (0, import_loro_crdt.isContainer)(container) ? __spreadProps(__spreadValues({}, acc), { [key]: container }) : acc;
+    this._storage = Object.entries(reference).reduce((acc, [key, node]) => {
+      if (node instanceof import_loro_crdt3.LoroCounter) return __spreadProps(__spreadValues({}, acc), { [key]: this.value.getCounter(key) });
+      if (node instanceof import_loro_crdt3.LoroList) return __spreadProps(__spreadValues({}, acc), { [key]: this.value.getList(key) });
+      if (node instanceof import_loro_crdt3.LoroMap) return __spreadProps(__spreadValues({}, acc), { [key]: this.value.getMap(key) });
+      if (node instanceof import_loro_crdt3.LoroMovableList) {
+        return __spreadProps(__spreadValues({}, acc), { [key]: this.value.getMovableList(key) });
+      }
+      if (node instanceof import_loro_crdt3.LoroText) return __spreadProps(__spreadValues({}, acc), { [key]: this.value.getText(key) });
+      if (node instanceof import_loro_crdt3.LoroTree) return __spreadProps(__spreadValues({}, acc), { [key]: this.value.getTree(key) });
+      return acc;
     }, {});
     return this.track();
   }
@@ -203,7 +322,7 @@ var CrdtLoroDoc = class extends import_crdt.AbstractCrdtDoc {
       this._undoManager.free();
       this._undoManager = null;
     }
-    this._undoManager = new import_loro_crdt.UndoManager(this.value, {
+    this._undoManager = new import_loro_crdt3.UndoManager(this.value, {
       maxUndoSteps: MAX_UNDO_STEPS,
       mergeInterval: MERGE_INTERVAL_MS
     });
@@ -223,13 +342,19 @@ var CrdtLoroDoc = class extends import_crdt.AbstractCrdtDoc {
     (_a = this._undoManager) == null ? void 0 : _a.undo();
     return this;
   }
+  _warn(...data) {
+    var _a;
+    if (typeof process === "undefined") return;
+    if (((_a = process.env) == null ? void 0 : _a.NODE_ENV) === "production") return;
+    console.log(...data);
+  }
 };
 
 // src/doc/CrdtLoroDocFactory.ts
-var import_crdt2 = require("@pluv/crdt");
-var CrdtLoroDocFactory = class _CrdtLoroDocFactory extends import_crdt2.AbstractCrdtDocFactory {
+var import_crdt = require("@pluv/crdt");
+var CrdtLoroDocFactory = class _CrdtLoroDocFactory extends import_crdt.AbstractCrdtDocFactory {
   constructor(initialStorage = () => ({})) {
-    super();
+    super(initialStorage);
     this._initialStorage = initialStorage;
   }
   getEmpty() {
@@ -239,8 +364,7 @@ var CrdtLoroDocFactory = class _CrdtLoroDocFactory extends import_crdt2.Abstract
     return new _CrdtLoroDocFactory(initialStorage != null ? initialStorage : this._initialStorage);
   }
   getInitialized(initialStorage) {
-    var _a;
-    return new CrdtLoroDoc((_a = initialStorage == null ? void 0 : initialStorage()) != null ? _a : this._initialStorage());
+    return new CrdtLoroDoc(initialStorage != null ? initialStorage : this._initialStorage);
   }
 };
 
@@ -250,61 +374,61 @@ var doc = (value = () => ({})) => {
 };
 
 // src/list.ts
-var import_loro_crdt2 = require("loro-crdt");
+var import_loro_crdt4 = require("loro-crdt");
 var list = (value = []) => {
-  const container = new import_loro_crdt2.LoroList();
+  const container = new import_loro_crdt4.LoroList();
   value.forEach((item, i) => {
-    if ((0, import_loro_crdt2.isContainer)(item)) container.insertContainer(i, item);
+    if ((0, import_loro_crdt4.isContainer)(item)) container.insertContainer(i, item);
     else container.insert(i, item);
   });
   return container;
 };
 
 // src/map.ts
-var import_loro_crdt3 = require("loro-crdt");
+var import_loro_crdt5 = require("loro-crdt");
 var map = (value = []) => {
-  const container = new import_loro_crdt3.LoroMap();
+  const container = new import_loro_crdt5.LoroMap();
   value.forEach(([key, item]) => {
-    if ((0, import_loro_crdt3.isContainer)(item)) container.setContainer(key, item);
+    if ((0, import_loro_crdt5.isContainer)(item)) container.setContainer(key, item);
     else container.set(key, item);
   });
   return container;
 };
 
 // src/movableList.ts
-var import_loro_crdt4 = require("loro-crdt");
+var import_loro_crdt6 = require("loro-crdt");
 var movableList = (value = []) => {
-  const container = new import_loro_crdt4.LoroMovableList();
+  const container = new import_loro_crdt6.LoroMovableList();
   value.forEach((item, i) => {
-    if ((0, import_loro_crdt4.isContainer)(item)) container.insertContainer(i, item);
+    if ((0, import_loro_crdt6.isContainer)(item)) container.insertContainer(i, item);
     else container.insert(i, item);
   });
   return container;
 };
 
 // src/object.ts
-var import_loro_crdt5 = require("loro-crdt");
+var import_loro_crdt7 = require("loro-crdt");
 var object = (value) => {
-  const container = new import_loro_crdt5.LoroMap();
+  const container = new import_loro_crdt7.LoroMap();
   Object.entries(value).forEach(([key, item]) => {
-    if ((0, import_loro_crdt5.isContainer)(item)) container.setContainer(key, item);
+    if ((0, import_loro_crdt7.isContainer)(item)) container.setContainer(key, item);
     else container.set(key, item);
   });
   return container;
 };
 
 // src/text.ts
-var import_loro_crdt6 = require("loro-crdt");
+var import_loro_crdt8 = require("loro-crdt");
 var text = (value = "") => {
-  const container = new import_loro_crdt6.LoroText();
+  const container = new import_loro_crdt8.LoroText();
   container.insert(0, value);
   return container;
 };
 
 // src/tree.ts
-var import_loro_crdt7 = require("loro-crdt");
+var import_loro_crdt9 = require("loro-crdt");
 var tree = () => {
-  const container = new import_loro_crdt7.LoroTree();
+  const container = new import_loro_crdt9.LoroTree();
   return container;
 };
 

package/dist/index.mjs

@@ -26,6 +26,7 @@ var __export = (target, all) => {
 var loro_exports = {};
 __export(loro_exports, {
   CrdtLoroDoc: () => CrdtLoroDoc,
+  counter: () => counter,
   doc: () => doc,
   kind: () => kind,
   list: () => list,
@@ -36,47 +37,161 @@ __export(loro_exports, {
   tree: () => tree
 });
 
+// src/counter.ts
+import { LoroCounter } from "loro-crdt";
+var counter = () => {
+  const counter2 = new LoroCounter();
+  return counter2;
+};
+
 // src/doc/CrdtLoroDoc.ts
-import { AbstractCrdtDoc } from "@pluv/crdt";
 import { fromUint8Array, toUint8Array } from "js-base64";
 import {
-  LoroCounter,
+  LoroCounter as LoroCounter2,
   LoroDoc,
   LoroList,
   LoroMap,
+  LoroMovableList,
   LoroText,
+  LoroTree,
   UndoManager,
-  isContainer
+  isContainer as isContainer2
 } from "loro-crdt";
+
+// src/utils/oneLine.ts
+var oneLine = (strings, ...values) => {
+  return strings.map((str) => str.replace(/\s+/g, " ").trim()).reduce((acc, str, i) => acc + str + (i < values.length ? values[i] : ""), "").replace(/\s+/g, " ").trim();
+};
+
+// src/doc/builder.ts
+import { isContainer } from "loro-crdt";
+var builder = (doc2) => {
+  return {
+    counter(name) {
+      return doc2.getCounter(name);
+    },
+    list(name, value = []) {
+      const list2 = doc2.getList(name);
+      value.forEach((item, i) => {
+        if (isContainer(item)) list2.insertContainer(i, item);
+        else list2.insert(i, item);
+      });
+      return list2;
+    },
+    map(name, value = {}) {
+      const container = doc2.getMap(name);
+      Object.entries(value).forEach(([key, item]) => {
+        if (isContainer(item)) container.setContainer(key, item);
+        else container.set(key, item);
+      });
+      return container;
+    },
+    moveableList(name, value = []) {
+      const list2 = doc2.getMovableList(name);
+      value.forEach((item, i) => {
+        if (isContainer(item)) list2.insertContainer(i, item);
+        else list2.insert(i, item);
+      });
+      return list2;
+    },
+    text(name, value = "") {
+      const text2 = doc2.getText(name);
+      text2.insert(0, value);
+      return text2;
+    },
+    tree(name) {
+      return doc2.getTree(name);
+    }
+  };
+};
+
+// src/doc/CrdtLoroDoc.ts
 var MAX_UNDO_STEPS = 100;
 var MERGE_INTERVAL_MS = 1e3;
-var CrdtLoroDoc = class extends AbstractCrdtDoc {
-  constructor(value = {}) {
-    super();
+var CrdtLoroDoc = class {
+  constructor(params = () => ({})) {
     this.value = new LoroDoc();
     this._undoManager = null;
-    this._storage = Object.entries(value).reduce((acc, [key, node]) => {
+    const storage = params(builder(this.value));
+    const keys = Object.keys(this.value.toJSON()).reduce(
+      (set, key) => set.add(key),
+      /* @__PURE__ */ new Set()
+    );
+    this._storage = Object.entries(storage).reduce((acc, [key, node]) => {
+      if (keys.has(key)) return __spreadProps(__spreadValues({}, acc), { [key]: node });
+      if (node instanceof LoroCounter2) {
+        this._warn(oneLine`
+                    Warning: You are using \`loro.counter\` to declare top-level storage value \`${key}\`.
+                    Adding top-level values this way has been deprecated, to be removed in v2.
+                    Please follow the v2 migration guide to declare top-level types correctly:
+                    https://pluv.io/docs/migration-guides/v2
+                `);
+        const container = this.value.getCounter(key);
+        return __spreadProps(__spreadValues({}, acc), { [key]: container });
+      }
       if (node instanceof LoroList) {
+        this._warn(oneLine`
+                    Warning: You are using \`loro.list\` to declare top-level storage value \`${key}\`.
+                    Adding top-level values this way has been deprecated, to be removed in v2.
+                    Please follow the v2 migration guide to declare top-level types correctly:
+                    https://pluv.io/docs/migration-guides/v2
+                `);
         const container = this.value.getList(key);
         node.toArray().forEach((item, i) => {
-          if (isContainer(item)) container.insertContainer(i, item);
+          if (isContainer2(item)) container.insertContainer(i, item);
           else container.insert(i, item);
         });
         return __spreadProps(__spreadValues({}, acc), { [key]: container });
       }
       if (node instanceof LoroMap) {
+        this._warn(oneLine`
+                    Warning: You are using \`loro.map\` to declare top-level storage value \`${key}\`.
+                    Adding top-level values this way has been deprecated, to be removed in v2.
+                    Please follow the v2 migration guide to declare top-level types correctly:
+                    https://pluv.io/docs/migration-guides/v2
+                `);
         const container = this.value.getMap(key);
         container.entries().forEach(([key2, item]) => {
-          if (isContainer(item)) container.setContainer(key2, item);
+          if (isContainer2(item)) container.setContainer(key2, item);
           else container.set(key2, item);
         });
         return __spreadProps(__spreadValues({}, acc), { [key]: container });
       }
+      if (node instanceof LoroMovableList) {
+        this._warn(oneLine`
+                    Warning: You are using \`loro.moveableList\` to declare top-level storage value \`${key}\`.
+                    Adding top-level values this way has been deprecated, to be removed in v2.
+                    Please follow the v2 migration guide to declare top-level types correctly:
+                    https://pluv.io/docs/migration-guides/v2
+                `);
+        const container = this.value.getMovableList(key);
+        node.toArray().forEach((item, i) => {
+          if (isContainer2(item)) container.insertContainer(i, item);
+          else container.insert(i, item);
+        });
+        return __spreadProps(__spreadValues({}, acc), { [key]: container });
+      }
       if (node instanceof LoroText) {
+        this._warn(oneLine`
+                    Warning: You are using \`loro.text\` to declare top-level storage value \`${key}\`.
+                    Adding top-level values this way has been deprecated, to be removed in v2.
+                    Please follow the v2 migration guide to declare top-level types correctly:
+                    https://pluv.io/docs/migration-guides/v2
+                `);
         const container = this.value.getText(key);
         container.insert(0, node.toString());
         return __spreadProps(__spreadValues({}, acc), { [key]: container });
       }
+      if (node instanceof LoroTree) {
+        this._warn(oneLine`
+                    Warning: You are using \`loro.tree\` to declare top-level storage value \`${key}\`.
+                    Adding top-level values this way has been deprecated, to be removed in v2.
+                    Please follow the v2 migration guide to declare top-level types correctly:
+                    https://pluv.io/docs/migration-guides/v2
+                `);
+        const container = this.value.getTree(key);
+        return __spreadProps(__spreadValues({}, acc), { [key]: container });
+      }
       return acc;
     }, {});
     this.value.commit();
@@ -132,7 +247,7 @@ var CrdtLoroDoc = class extends AbstractCrdtDoc {
   toJson(type) {
     if (typeof type === "string") {
       const container = this._storage[type];
-      return container instanceof LoroText ? container.toString() : container instanceof LoroCounter ? container.value : container.toJSON();
+      return container instanceof LoroText ? container.toString() : container instanceof LoroCounter2 ? container.value : container.toJSON();
     }
     return Object.entries(this._storage).reduce(
       (acc, [key, value]) => __spreadProps(__spreadValues({}, acc), {
@@ -145,16 +260,22 @@ var CrdtLoroDoc = class extends AbstractCrdtDoc {
     const serialized = this.value.toJSON();
     return !serialized || !Object.keys(serialized).length;
   }
-  rebuildStorage() {
+  rebuildStorage(reference) {
     const isBuilt = !!Object.keys(this._storage).length;
     if (isBuilt) {
       console.warn("Attempted to rebuild storage multiple times");
       return this;
     }
-    const keys = Object.keys(this.value.toJSON());
-    this._storage = keys.reduce((acc, key) => {
-      const container = this.value.getByPath(key);
-      return isContainer(container) ? __spreadProps(__spreadValues({}, acc), { [key]: container }) : acc;
+    this._storage = Object.entries(reference).reduce((acc, [key, node]) => {
+      if (node instanceof LoroCounter2) return __spreadProps(__spreadValues({}, acc), { [key]: this.value.getCounter(key) });
+      if (node instanceof LoroList) return __spreadProps(__spreadValues({}, acc), { [key]: this.value.getList(key) });
+      if (node instanceof LoroMap) return __spreadProps(__spreadValues({}, acc), { [key]: this.value.getMap(key) });
+      if (node instanceof LoroMovableList) {
+        return __spreadProps(__spreadValues({}, acc), { [key]: this.value.getMovableList(key) });
+      }
+      if (node instanceof LoroText) return __spreadProps(__spreadValues({}, acc), { [key]: this.value.getText(key) });
+      if (node instanceof LoroTree) return __spreadProps(__spreadValues({}, acc), { [key]: this.value.getTree(key) });
+      return acc;
     }, {});
     return this.track();
   }
@@ -212,13 +333,19 @@ var CrdtLoroDoc = class extends AbstractCrdtDoc {
     (_a = this._undoManager) == null ? void 0 : _a.undo();
     return this;
   }
+  _warn(...data) {
+    var _a;
+    if (typeof process === "undefined") return;
+    if (((_a = process.env) == null ? void 0 : _a.NODE_ENV) === "production") return;
+    console.log(...data);
+  }
 };
 
 // src/doc/CrdtLoroDocFactory.ts
 import { AbstractCrdtDocFactory } from "@pluv/crdt";
 var CrdtLoroDocFactory = class _CrdtLoroDocFactory extends AbstractCrdtDocFactory {
   constructor(initialStorage = () => ({})) {
-    super();
+    super(initialStorage);
     this._initialStorage = initialStorage;
   }
   getEmpty() {
@@ -228,8 +355,7 @@ var CrdtLoroDocFactory = class _CrdtLoroDocFactory extends AbstractCrdtDocFactor
     return new _CrdtLoroDocFactory(initialStorage != null ? initialStorage : this._initialStorage);
   }
   getInitialized(initialStorage) {
-    var _a;
-    return new CrdtLoroDoc((_a = initialStorage == null ? void 0 : initialStorage()) != null ? _a : this._initialStorage());
+    return new CrdtLoroDoc(initialStorage != null ? initialStorage : this._initialStorage);
   }
 };
 
@@ -239,44 +365,44 @@ var doc = (value = () => ({})) => {
 };
 
 // src/list.ts
-import { LoroList as LoroList2, isContainer as isContainer2 } from "loro-crdt";
+import { LoroList as LoroList2, isContainer as isContainer3 } from "loro-crdt";
 var list = (value = []) => {
   const container = new LoroList2();
   value.forEach((item, i) => {
-    if (isContainer2(item)) container.insertContainer(i, item);
+    if (isContainer3(item)) container.insertContainer(i, item);
     else container.insert(i, item);
   });
   return container;
 };
 
 // src/map.ts
-import { LoroMap as LoroMap2, isContainer as isContainer3 } from "loro-crdt";
+import { LoroMap as LoroMap2, isContainer as isContainer4 } from "loro-crdt";
 var map = (value = []) => {
   const container = new LoroMap2();
   value.forEach(([key, item]) => {
-    if (isContainer3(item)) container.setContainer(key, item);
+    if (isContainer4(item)) container.setContainer(key, item);
     else container.set(key, item);
   });
   return container;
 };
 
 // src/movableList.ts
-import { isContainer as isContainer4, LoroMovableList } from "loro-crdt";
+import { isContainer as isContainer5, LoroMovableList as LoroMovableList2 } from "loro-crdt";
 var movableList = (value = []) => {
-  const container = new LoroMovableList();
+  const container = new LoroMovableList2();
   value.forEach((item, i) => {
-    if (isContainer4(item)) container.insertContainer(i, item);
+    if (isContainer5(item)) container.insertContainer(i, item);
     else container.insert(i, item);
   });
   return container;
 };
 
 // src/object.ts
-import { LoroMap as LoroMap3, isContainer as isContainer5 } from "loro-crdt";
+import { LoroMap as LoroMap3, isContainer as isContainer6 } from "loro-crdt";
 var object = (value) => {
   const container = new LoroMap3();
   Object.entries(value).forEach(([key, item]) => {
-    if (isContainer5(item)) container.setContainer(key, item);
+    if (isContainer6(item)) container.setContainer(key, item);
     else container.set(key, item);
   });
   return container;
@@ -291,9 +417,9 @@ var text = (value = "") => {
 };
 
 // src/tree.ts
-import { LoroTree } from "loro-crdt";
+import { LoroTree as LoroTree2 } from "loro-crdt";
 var tree = () => {
-  const container = new LoroTree();
+  const container = new LoroTree2();
   return container;
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pluv/crdt-loro",
-  "version": "1.0.1",
+  "version": "2.0.0",
   "description": "loro for @pluv/io",
   "author": "leedavidcs",
   "license": "MIT",
@@ -18,19 +18,20 @@
   },
   "dependencies": {
     "js-base64": "^3.7.7",
-    "@pluv/crdt": "^1.0.1",
-    "@pluv/types": "^1.0.1"
+    "@pluv/crdt": "^2.0.0",
+    "@pluv/types": "^2.0.0"
   },
   "peerDependencies": {
     "loro-crdt": "^1.0.0"
   },
   "devDependencies": {
+    "@types/node": "^22.15.3",
     "eslint": "^9.25.1",
     "loro-crdt": "^1.5.4",
     "tsup": "^8.4.0",
     "typescript": "^5.8.3",
-    "@pluv/tsconfig": "^1.0.1",
-    "eslint-config-pluv": "^1.0.1"
+    "@pluv/tsconfig": "^2.0.0",
+    "eslint-config-pluv": "^2.0.0"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --dts",

package/src/counter.ts

@@ -0,0 +1,8 @@
+import { LoroCounter } from "loro-crdt";
+import { LoroType } from "./types";
+
+export const counter = (): LoroCounter => {
+    const counter = new LoroCounter();
+
+    return counter as unknown as LoroType<LoroCounter, number>;
+};

package/src/doc/CrdtLoroDoc.ts

@@ -4,7 +4,7 @@ import type {
     DocSubscribeCallbackParams,
     InferCrdtJson,
 } from "@pluv/crdt";
-import { AbstractCrdtDoc } from "@pluv/crdt";
+import type { CrdtDocLike } from "@pluv/types";
 import { fromUint8Array, toUint8Array } from "js-base64";
 import type { Container } from "loro-crdt";
 import {
@@ -13,28 +13,69 @@ import {
     LoroEventBatch,
     LoroList,
     LoroMap,
+    LoroMovableList,
     LoroText,
+    LoroTree,
     UndoManager,
     isContainer,
 } from "loro-crdt";
 import type { LoroType } from "../types";
+import { oneLine } from "../utils";
+import type { LoroBuilder } from "./builder";
+import { builder } from "./builder";
 
 const MAX_UNDO_STEPS = 100;
 const MERGE_INTERVAL_MS = 1_000;
 
-export class CrdtLoroDoc<
-    TStorage extends Record<string, LoroType<any, any>>,
-> extends AbstractCrdtDoc<TStorage> {
+export type CrdtLoroDocParams<TStorage extends Record<string, LoroType<any, any>>> = (
+    builder: LoroBuilder,
+) => TStorage;
+
+export class CrdtLoroDoc<TStorage extends Record<string, LoroType<any, any>>>
+    implements CrdtDocLike<TStorage>
+{
     public value: LoroDoc = new LoroDoc();
 
     private _storage: TStorage;
     private _undoManager: UndoManager | null = null;
 
-    constructor(value: TStorage = {} as TStorage) {
-        super();
+    constructor(params: CrdtLoroDocParams<TStorage> = () => ({}) as TStorage) {
+        const storage = params(builder(this.value));
+
+        const keys = Object.keys(this.value.toJSON()).reduce(
+            (set, key) => set.add(key),
+            new Set<string>(),
+        );
+
+        this._storage = Object.entries(storage).reduce((acc, [key, node]) => {
+            /**
+             * @description These are all container types that we declared directly on the root
+             * document. So we're going to store these on the storage type directly.
+             * @date May 8, 2025
+             */
+            if (keys.has(key)) return { ...acc, [key]: node };
+
+            if (node instanceof LoroCounter) {
+                this._warn(oneLine`
+                    Warning: You are using \`loro.counter\` to declare top-level storage value \`${key}\`.
+                    Adding top-level values this way has been deprecated, to be removed in v2.
+                    Please follow the v2 migration guide to declare top-level types correctly:
+                    https://pluv.io/docs/migration-guides/v2
+                `);
+
+                const container = this.value.getCounter(key);
+
+                return { ...acc, [key]: container };
+            }
 
-        this._storage = Object.entries(value).reduce((acc, [key, node]) => {
             if (node instanceof LoroList) {
+                this._warn(oneLine`
+                    Warning: You are using \`loro.list\` to declare top-level storage value \`${key}\`.
+                    Adding top-level values this way has been deprecated, to be removed in v2.
+                    Please follow the v2 migration guide to declare top-level types correctly:
+                    https://pluv.io/docs/migration-guides/v2
+                `);
+
                 const container = this.value.getList(key);
 
                 node.toArray().forEach((item, i) => {
@@ -46,6 +87,13 @@ export class CrdtLoroDoc<
             }
 
             if (node instanceof LoroMap) {
+                this._warn(oneLine`
+                    Warning: You are using \`loro.map\` to declare top-level storage value \`${key}\`.
+                    Adding top-level values this way has been deprecated, to be removed in v2.
+                    Please follow the v2 migration guide to declare top-level types correctly:
+                    https://pluv.io/docs/migration-guides/v2
+                `);
+
                 const container = this.value.getMap(key);
 
                 container.entries().forEach(([key, item]) => {
@@ -56,7 +104,32 @@ export class CrdtLoroDoc<
                 return { ...acc, [key]: container };
             }
 
+            if (node instanceof LoroMovableList) {
+                this._warn(oneLine`
+                    Warning: You are using \`loro.moveableList\` to declare top-level storage value \`${key}\`.
+                    Adding top-level values this way has been deprecated, to be removed in v2.
+                    Please follow the v2 migration guide to declare top-level types correctly:
+                    https://pluv.io/docs/migration-guides/v2
+                `);
+
+                const container = this.value.getMovableList(key);
+
+                node.toArray().forEach((item, i) => {
+                    if (isContainer(item)) container.insertContainer(i, item);
+                    else container.insert(i, item);
+                });
+
+                return { ...acc, [key]: container };
+            }
+
             if (node instanceof LoroText) {
+                this._warn(oneLine`
+                    Warning: You are using \`loro.text\` to declare top-level storage value \`${key}\`.
+                    Adding top-level values this way has been deprecated, to be removed in v2.
+                    Please follow the v2 migration guide to declare top-level types correctly:
+                    https://pluv.io/docs/migration-guides/v2
+                `);
+
                 const container = this.value.getText(key);
 
                 container.insert(0, node.toString());
@@ -64,6 +137,19 @@ export class CrdtLoroDoc<
                 return { ...acc, [key]: container };
             }
 
+            if (node instanceof LoroTree) {
+                this._warn(oneLine`
+                    Warning: You are using \`loro.tree\` to declare top-level storage value \`${key}\`.
+                    Adding top-level values this way has been deprecated, to be removed in v2.
+                    Please follow the v2 migration guide to declare top-level types correctly:
+                    https://pluv.io/docs/migration-guides/v2
+                `);
+
+                const container = this.value.getTree(key);
+
+                return { ...acc, [key]: container };
+            }
+
             return acc;
         }, {} as TStorage);
 
@@ -171,7 +257,7 @@ export class CrdtLoroDoc<
         return !serialized || !Object.keys(serialized).length;
     }
 
-    public rebuildStorage(): this {
+    public rebuildStorage(reference: TStorage): this {
         const isBuilt = !!Object.keys(this._storage).length;
 
         if (isBuilt) {
@@ -179,12 +265,17 @@ export class CrdtLoroDoc<
             return this;
         }
 
-        const keys = Object.keys(this.value.toJSON());
-
-        this._storage = keys.reduce((acc, key) => {
-            const container = this.value.getByPath(key);
+        this._storage = Object.entries(reference).reduce((acc, [key, node]) => {
+            if (node instanceof LoroCounter) return { ...acc, [key]: this.value.getCounter(key) };
+            if (node instanceof LoroList) return { ...acc, [key]: this.value.getList(key) };
+            if (node instanceof LoroMap) return { ...acc, [key]: this.value.getMap(key) };
+            if (node instanceof LoroMovableList) {
+                return { ...acc, [key]: this.value.getMovableList(key) };
+            }
+            if (node instanceof LoroText) return { ...acc, [key]: this.value.getText(key) };
+            if (node instanceof LoroTree) return { ...acc, [key]: this.value.getTree(key) };
 
-            return isContainer(container) ? { ...acc, [key]: container } : acc;
+            return acc;
         }, {} as TStorage);
 
         return this.track();
@@ -257,4 +348,10 @@ export class CrdtLoroDoc<
 
         return this;
     }
+
+    private _warn(...data: any[]) {
+        if (typeof process === "undefined") return;
+        if (process.env?.NODE_ENV === "production") return;
+        console.log(...data);
+    }
 }

package/src/doc/CrdtLoroDocFactory.ts

@@ -1,14 +1,15 @@
 import { AbstractCrdtDocFactory } from "@pluv/crdt";
 import type { LoroType } from "../types";
 import { CrdtLoroDoc } from "./CrdtLoroDoc";
+import type { LoroBuilder } from "./builder";
 
 export class CrdtLoroDocFactory<
     TStorage extends Record<string, LoroType<any, any>>,
 > extends AbstractCrdtDocFactory<TStorage> {
-    private _initialStorage: () => TStorage;
+    public readonly _initialStorage: (builder: LoroBuilder) => TStorage;
 
-    constructor(initialStorage: () => TStorage = () => ({}) as TStorage) {
-        super();
+    constructor(initialStorage: (builder: LoroBuilder) => TStorage = () => ({}) as TStorage) {
+        super(initialStorage);
 
         this._initialStorage = initialStorage;
     }
@@ -17,11 +18,15 @@ export class CrdtLoroDocFactory<
         return new CrdtLoroDoc<TStorage>();
     }
 
-    public getFactory(initialStorage?: (() => TStorage) | undefined): CrdtLoroDocFactory<TStorage> {
+    public getFactory(
+        initialStorage?: ((builder: LoroBuilder) => TStorage) | undefined,
+    ): CrdtLoroDocFactory<TStorage> {
         return new CrdtLoroDocFactory<TStorage>(initialStorage ?? this._initialStorage);
     }
 
-    public getInitialized(initialStorage?: () => TStorage): CrdtLoroDoc<TStorage> {
-        return new CrdtLoroDoc<TStorage>(initialStorage?.() ?? this._initialStorage());
+    public getInitialized(
+        initialStorage?: (builder: LoroBuilder) => TStorage,
+    ): CrdtLoroDoc<TStorage> {
+        return new CrdtLoroDoc<TStorage>(initialStorage ?? this._initialStorage);
     }
 }

package/src/doc/builder.ts

@@ -0,0 +1,70 @@
+import type {
+    Container,
+    LoroCounter,
+    LoroDoc,
+    LoroList,
+    LoroMap,
+    LoroMovableList,
+    LoroText,
+} from "loro-crdt";
+import { isContainer } from "loro-crdt";
+import type { LoroType } from "../types";
+
+export type LoroBuilder = ReturnType<typeof builder>;
+
+export const builder = (doc: LoroDoc) => {
+    return {
+        counter(name: string): LoroCounter {
+            return doc.getCounter(name);
+        },
+        list<T extends unknown>(
+            name: string,
+            value: T[] | readonly T[] = [],
+        ): LoroType<LoroList<T>, T[]> {
+            const list = doc.getList(name);
+
+            value.forEach((item, i) => {
+                if (isContainer(item)) list.insertContainer(i, item);
+                else list.insert(i, item as Exclude<T, Container>);
+            });
+
+            return list as unknown as LoroType<LoroList<T>, T[]>;
+        },
+        map<T extends Record<string, unknown>>(
+            name: string,
+            value: T = {} as T,
+        ): LoroType<LoroMap<T>, T> {
+            const container = doc.getMap(name);
+
+            Object.entries(value).forEach(([key, item]) => {
+                if (isContainer(item)) container.setContainer(key, item);
+                else container.set(key, item as Exclude<T, Container>);
+            });
+
+            return container as unknown as LoroType<LoroMap<T>, T>;
+        },
+        moveableList<T extends unknown>(
+            name: string,
+            value: T[] | readonly T[] = [],
+        ): LoroType<LoroMovableList<T>, T[]> {
+            const list = doc.getMovableList(name);
+
+            value.forEach((item, i) => {
+                if (isContainer(item)) list.insertContainer(i, item);
+                else list.insert(i, item as Exclude<T, Container>);
+            });
+
+            return list as unknown as LoroType<LoroMovableList<T>, T[]>;
+        },
+        text(name: string, value: string = ""): LoroType<LoroText, string> {
+            const text = doc.getText(name);
+
+            text.insert(0, value);
+
+            return text as unknown as LoroType<LoroText, string>;
+        },
+        tree(name: string) {
+            return doc.getTree(name);
+        },
+    };
+};

package/src/doc/doc.ts

@@ -1,8 +1,9 @@
 import type { LoroType } from "../types";
+import type { LoroBuilder } from "./builder";
 import { CrdtLoroDocFactory } from "./CrdtLoroDocFactory";
 
 export const doc = <TStorage extends Record<string, LoroType<any, any>>>(
-    value: () => TStorage = () => ({}) as TStorage,
+    value: (builder: LoroBuilder) => TStorage = () => ({}) as TStorage,
 ): CrdtLoroDocFactory<TStorage> => {
     return new CrdtLoroDocFactory<TStorage>(value);
 };

package/src/doc/index.ts

@@ -1,3 +1,4 @@
+export type { LoroBuilder } from "./builder";
 export { CrdtLoroDoc } from "./CrdtLoroDoc";
 export { CrdtLoroDocFactory } from "./CrdtLoroDocFactory";
 export { doc } from "./doc";

package/src/loro.ts

@@ -1,4 +1,6 @@
+export { counter } from "./counter";
 export { CrdtLoroDoc, doc } from "./doc";
+export type { LoroBuilder } from "./doc";
 export { list } from "./list";
 export { map } from "./map";
 export { movableList } from "./movableList";

package/src/utils/index.ts

@@ -0,0 +1 @@
+export { oneLine } from "./oneLine";

package/src/utils/oneLine.ts

@@ -0,0 +1,7 @@
+export const oneLine = (strings: TemplateStringsArray, ...values: unknown[]): string => {
+    return strings
+        .map((str) => str.replace(/\s+/g, " ").trim())
+        .reduce((acc, str, i) => acc + str + (i < values.length ? values[i] : ""), "")
+        .replace(/\s+/g, " ")
+        .trim();
+};