@pluv/crdt-yjs 1.0.2 → 2.0.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @pluv/crdt-yjs@1.0.2 build /home/runner/work/pluv/pluv/packages/crdt-yjs
+> @pluv/crdt-yjs@2.0.0 build /home/runner/work/pluv/pluv/packages/crdt-yjs
 > 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 11.13 KB
-ESM ⚡️ Build success in 108ms
-CJS dist/index.js 12.00 KB
-CJS ⚡️ Build success in 115ms
+CJS dist/index.js 16.33 KB
+CJS ⚡️ Build success in 121ms
+ESM dist/index.mjs 15.47 KB
+ESM ⚡️ Build success in 123ms
 DTS Build start
-DTS ⚡️ Build success in 2775ms
-DTS dist/index.d.mts 3.96 KB
-DTS dist/index.d.ts  3.96 KB
+DTS ⚡️ Build success in 4131ms
+DTS dist/index.d.mts 5.14 KB
+DTS dist/index.d.ts  5.14 KB

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # @pluv/crdt-yjs
 
+## 2.0.0
+
+### Minor Changes
+
+- 0b234d1: **Deprecated** Declaring top-level types on your CRDT storage via the `yjs` utility (e.g. `yjs.array`) is now deprecated, to be removed in the next major release (v2). Continuing to use the `yjs` 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 { yjs } from "@pluv/crdt-yjs";
+
+  // Before
+  yjs.doc(() => ({
+    // Using the `yjs` utility (in this case `yjs.map`) when declaring
+    // top-level types is now deprecated
+    topType: yjs.map([
+      ["key1", yjs.text("")],
+      ["key2", yjs.text("")],
+    ]),
+  }));
+
+  // After
+  yjs.doc((t) => ({
+    // Top-level properties must now use the builder (in this case `t`).
+    // This effectively calls `yjs.getMap("topType")` to instantiate the type on
+    // the root document.
+    // This simply returns the native Yjs shared-types (e.g. Y.Map), which
+    // allows you operate on your yjs shared-typess in a more native way.
+    topType: t.map("topType", [
+      // Declaring nested types should continue to use the `yjs` utilities
+      // you've used before
+      ["key1", yjs.text("")],
+      ["key2", yjs.text("")],
+    ]),
+  }));
+  ```
+
+  The functions on the builder type calls the native yjs shared-type instantiating methods and returns the native types (e.g. `t.map("topType")` is simply just a `Y.Doc.getMap("topType")`) call under the hood. This allows you to declare your type in a more yjs-native and predictable way, and enables declaring more complex initial storage states if needed.
+
+### Patch Changes
+
+- 0b234d1: Fixed `Y.XmlText` types transforming into `Y.Text` types on the initial initializaion of storage states.
+- Updated dependencies [047a1d8]
+  - @pluv/types@2.0.0
+  - @pluv/crdt@2.0.0
+
 ## 1.0.2
 
 ### Patch Changes

package/dist/index.d.mts

@@ -1,5 +1,6 @@
 import { Array, Doc, Map, Text, XmlElement, XmlText, XmlFragment } from 'yjs';
-import { CrdtType, AbstractCrdtDoc, DocApplyEncodedStateParams, DocBatchApplyEncodedStateParams, DocSubscribeCallbackParams, InferCrdtJson, AbstractCrdtDocFactory } from '@pluv/crdt';
+import { CrdtType, DocApplyEncodedStateParams, DocBatchApplyEncodedStateParams, DocSubscribeCallbackParams, InferCrdtJson, AbstractCrdtDocFactory } from '@pluv/crdt';
+import { CrdtDocLike } from '@pluv/types';
 
 type YjsType<TValue extends unknown, TJson extends unknown = any> = CrdtType<TValue, TJson> & {
     initialValue?: any;
@@ -8,11 +9,22 @@ type YjsType<TValue extends unknown, TJson extends unknown = any> = CrdtType<TVa
 
 declare const array: <T extends unknown>(value?: T[] | readonly T[]) => YjsType<Array<T>, T[]>;
 
-declare class CrdtYjsDoc<TStorage extends Record<string, YjsType<any, any>>> extends AbstractCrdtDoc<TStorage> {
+type YjsBuilder = ReturnType<typeof builder>;
+declare const builder: (doc: Doc) => {
+    array<T extends unknown>(name: string, value?: T[] | readonly T[]): YjsType<Array<T>, T[]>;
+    map<T extends unknown>(name: string, value?: readonly (readonly [key: string, value: T])[]): YjsType<Map<T>, Record<string, T>>;
+    text(name: string, value?: string): YjsType<Text, string>;
+    xmlElement(name: string, children?: (XmlElement | XmlText)[] | readonly (XmlElement | XmlText)[]): YjsType<XmlElement, string>;
+    xmlFragment(name: string, children?: (XmlElement | XmlText)[] | readonly (XmlElement | XmlText)[]): YjsType<XmlFragment, string>;
+    xmlText(name: string): YjsType<XmlText, string>;
+};
+
+type CrdtYjsDocParams<TStorage extends Record<string, YjsType<any, any>>> = (builder: YjsBuilder) => TStorage;
+declare class CrdtYjsDoc<TStorage extends Record<string, YjsType<any, any>>> implements CrdtDocLike<TStorage> {
     value: Doc;
     private _storage;
     private _undoManager;
-    constructor(value?: TStorage);
+    constructor(params?: CrdtYjsDocParams<TStorage>);
     applyEncodedState(params: DocApplyEncodedStateParams): this;
     batchApplyEncodedState(params: DocBatchApplyEncodedStateParams): this;
     canRedo(): boolean;
@@ -30,20 +42,26 @@ declare class CrdtYjsDoc<TStorage extends Record<string, YjsType<any, any>>> ext
     toJson(): InferCrdtJson<TStorage>;
     toJson<TKey extends keyof TStorage>(type: TKey): InferCrdtJson<TStorage[TKey]>;
     undo(): this;
+    private _warn;
 }
 
-declare class CrdtYjsDocFactory<TStorage extends Record<string, YjsType<any, any>>> extends AbstractCrdtDocFactory<TStorage> {
-    private _initialStorage;
-    constructor(initialStorage?: () => TStorage);
+declare class CrdtYjsDocFactory<TStorage extends Record<string, YjsType<any, any>> = {}> extends AbstractCrdtDocFactory<TStorage> {
+    readonly _initialStorage: (builder: YjsBuilder) => TStorage;
+    constructor(initialStorage?: (builder: YjsBuilder) => TStorage);
     getEmpty(): CrdtYjsDoc<TStorage>;
-    getFactory(initialStorage?: (() => TStorage) | undefined): CrdtYjsDocFactory<TStorage>;
-    getInitialized(initialStorage?: () => TStorage): CrdtYjsDoc<TStorage>;
+    getFactory(initialStorage: (builder: YjsBuilder) => TStorage): CrdtYjsDocFactory<TStorage>;
+    getInitialized(initialStorage?: (builder: YjsBuilder) => TStorage): CrdtYjsDoc<TStorage>;
 }
 
-declare const doc: <TStorage extends Record<string, YjsType<any, any>>>(value?: () => TStorage) => CrdtYjsDocFactory<TStorage>;
+declare const doc: <TStorage extends Record<string, YjsType<any, any>>>(value?: (buidler: YjsBuilder) => TStorage) => CrdtYjsDocFactory<TStorage>;
 
 declare const map: <T extends unknown>(value?: readonly (readonly [key: string, value: T])[]) => YjsType<Map<T>, Record<string, T>>;
 
+/**
+ * @deprecated This will be removed in v2.0.0. Use yjs.map instead
+ * @description Creates a Yjs map, but declare it like it's an object
+ * @date May 8, 2025
+ */
 declare const object: <T extends Record<string, any>>(value?: T) => YjsType<Map<T[keyof T]>, T>;
 
 declare const text: (value?: string) => YjsType<Text, string>;
@@ -68,6 +86,7 @@ declare const xmlText: () => YjsType<XmlText, string>;
 
 declare const kind: "yjs";
 
+type yjs_YjsBuilder = YjsBuilder;
 type yjs_YjsType<TValue extends unknown, TJson extends unknown = any> = YjsType<TValue, TJson>;
 declare const yjs_array: typeof array;
 declare const yjs_doc: typeof doc;
@@ -79,7 +98,7 @@ declare const yjs_xmlElement: typeof xmlElement;
 declare const yjs_xmlFragment: typeof xmlFragment;
 declare const yjs_xmlText: typeof xmlText;
 declare namespace yjs {
-  export { type yjs_YjsType as YjsType, yjs_array as array, yjs_doc as doc, yjs_kind as kind, yjs_map as map, yjs_object as object, yjs_text as text, yjs_xmlElement as xmlElement, yjs_xmlFragment as xmlFragment, yjs_xmlText as xmlText };
+  export { type yjs_YjsBuilder as YjsBuilder, type yjs_YjsType as YjsType, yjs_array as array, yjs_doc as doc, yjs_kind as kind, yjs_map as map, yjs_object as object, yjs_text as text, yjs_xmlElement as xmlElement, yjs_xmlFragment as xmlFragment, yjs_xmlText as xmlText };
 }
 
 export { yjs };

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { Array, Doc, Map, Text, XmlElement, XmlText, XmlFragment } from 'yjs';
-import { CrdtType, AbstractCrdtDoc, DocApplyEncodedStateParams, DocBatchApplyEncodedStateParams, DocSubscribeCallbackParams, InferCrdtJson, AbstractCrdtDocFactory } from '@pluv/crdt';
+import { CrdtType, DocApplyEncodedStateParams, DocBatchApplyEncodedStateParams, DocSubscribeCallbackParams, InferCrdtJson, AbstractCrdtDocFactory } from '@pluv/crdt';
+import { CrdtDocLike } from '@pluv/types';
 
 type YjsType<TValue extends unknown, TJson extends unknown = any> = CrdtType<TValue, TJson> & {
     initialValue?: any;
@@ -8,11 +9,22 @@ type YjsType<TValue extends unknown, TJson extends unknown = any> = CrdtType<TVa
 
 declare const array: <T extends unknown>(value?: T[] | readonly T[]) => YjsType<Array<T>, T[]>;
 
-declare class CrdtYjsDoc<TStorage extends Record<string, YjsType<any, any>>> extends AbstractCrdtDoc<TStorage> {
+type YjsBuilder = ReturnType<typeof builder>;
+declare const builder: (doc: Doc) => {
+    array<T extends unknown>(name: string, value?: T[] | readonly T[]): YjsType<Array<T>, T[]>;
+    map<T extends unknown>(name: string, value?: readonly (readonly [key: string, value: T])[]): YjsType<Map<T>, Record<string, T>>;
+    text(name: string, value?: string): YjsType<Text, string>;
+    xmlElement(name: string, children?: (XmlElement | XmlText)[] | readonly (XmlElement | XmlText)[]): YjsType<XmlElement, string>;
+    xmlFragment(name: string, children?: (XmlElement | XmlText)[] | readonly (XmlElement | XmlText)[]): YjsType<XmlFragment, string>;
+    xmlText(name: string): YjsType<XmlText, string>;
+};
+
+type CrdtYjsDocParams<TStorage extends Record<string, YjsType<any, any>>> = (builder: YjsBuilder) => TStorage;
+declare class CrdtYjsDoc<TStorage extends Record<string, YjsType<any, any>>> implements CrdtDocLike<TStorage> {
     value: Doc;
     private _storage;
     private _undoManager;
-    constructor(value?: TStorage);
+    constructor(params?: CrdtYjsDocParams<TStorage>);
     applyEncodedState(params: DocApplyEncodedStateParams): this;
     batchApplyEncodedState(params: DocBatchApplyEncodedStateParams): this;
     canRedo(): boolean;
@@ -30,20 +42,26 @@ declare class CrdtYjsDoc<TStorage extends Record<string, YjsType<any, any>>> ext
     toJson(): InferCrdtJson<TStorage>;
     toJson<TKey extends keyof TStorage>(type: TKey): InferCrdtJson<TStorage[TKey]>;
     undo(): this;
+    private _warn;
 }
 
-declare class CrdtYjsDocFactory<TStorage extends Record<string, YjsType<any, any>>> extends AbstractCrdtDocFactory<TStorage> {
-    private _initialStorage;
-    constructor(initialStorage?: () => TStorage);
+declare class CrdtYjsDocFactory<TStorage extends Record<string, YjsType<any, any>> = {}> extends AbstractCrdtDocFactory<TStorage> {
+    readonly _initialStorage: (builder: YjsBuilder) => TStorage;
+    constructor(initialStorage?: (builder: YjsBuilder) => TStorage);
     getEmpty(): CrdtYjsDoc<TStorage>;
-    getFactory(initialStorage?: (() => TStorage) | undefined): CrdtYjsDocFactory<TStorage>;
-    getInitialized(initialStorage?: () => TStorage): CrdtYjsDoc<TStorage>;
+    getFactory(initialStorage: (builder: YjsBuilder) => TStorage): CrdtYjsDocFactory<TStorage>;
+    getInitialized(initialStorage?: (builder: YjsBuilder) => TStorage): CrdtYjsDoc<TStorage>;
 }
 
-declare const doc: <TStorage extends Record<string, YjsType<any, any>>>(value?: () => TStorage) => CrdtYjsDocFactory<TStorage>;
+declare const doc: <TStorage extends Record<string, YjsType<any, any>>>(value?: (buidler: YjsBuilder) => TStorage) => CrdtYjsDocFactory<TStorage>;
 
 declare const map: <T extends unknown>(value?: readonly (readonly [key: string, value: T])[]) => YjsType<Map<T>, Record<string, T>>;
 
+/**
+ * @deprecated This will be removed in v2.0.0. Use yjs.map instead
+ * @description Creates a Yjs map, but declare it like it's an object
+ * @date May 8, 2025
+ */
 declare const object: <T extends Record<string, any>>(value?: T) => YjsType<Map<T[keyof T]>, T>;
 
 declare const text: (value?: string) => YjsType<Text, string>;
@@ -68,6 +86,7 @@ declare const xmlText: () => YjsType<XmlText, string>;
 
 declare const kind: "yjs";
 
+type yjs_YjsBuilder = YjsBuilder;
 type yjs_YjsType<TValue extends unknown, TJson extends unknown = any> = YjsType<TValue, TJson>;
 declare const yjs_array: typeof array;
 declare const yjs_doc: typeof doc;
@@ -79,7 +98,7 @@ declare const yjs_xmlElement: typeof xmlElement;
 declare const yjs_xmlFragment: typeof xmlFragment;
 declare const yjs_xmlText: typeof xmlText;
 declare namespace yjs {
-  export { type yjs_YjsType as YjsType, yjs_array as array, yjs_doc as doc, yjs_kind as kind, yjs_map as map, yjs_object as object, yjs_text as text, yjs_xmlElement as xmlElement, yjs_xmlFragment as xmlFragment, yjs_xmlText as xmlText };
+  export { type yjs_YjsBuilder as YjsBuilder, type yjs_YjsType as YjsType, yjs_array as array, yjs_doc as doc, yjs_kind as kind, yjs_map as map, yjs_object as object, yjs_text as text, yjs_xmlElement as xmlElement, yjs_xmlFragment as xmlFragment, yjs_xmlText as xmlText };
 }
 
 export { yjs };

package/dist/index.js

@@ -74,9 +74,8 @@ var array = (value = []) => {
 };
 
 // src/doc/CrdtYjsDoc.ts
-var import_crdt = require("@pluv/crdt");
 var import_js_base64 = require("js-base64");
-var import_yjs8 = require("yjs");
+var import_yjs9 = require("yjs");
 
 // src/map/YjsMap.ts
 var import_yjs2 = require("yjs");
@@ -114,6 +113,11 @@ var YjsText = class extends import_yjs4.Text {
   }
 };
 
+// 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/xmlElement/YjsXmlElement.ts
 var import_yjs5 = require("yjs");
 var YjsXmlElement = class extends import_yjs5.XmlElement {
@@ -152,57 +156,139 @@ var YjsXmlText = class extends import_yjs7.XmlText {
   }
 };
 
+// src/doc/builder.ts
+var import_yjs8 = require("yjs");
+var builder = (doc2) => {
+  return {
+    array(name, value = []) {
+      const array2 = doc2.getArray(name);
+      if (!!value.length) array2.insert(0, value);
+      return array2;
+    },
+    map(name, value = []) {
+      const map2 = doc2.getMap(name);
+      value.forEach(([k, v]) => {
+        map2.set(k, v);
+      });
+      return map2;
+    },
+    text(name, value = "") {
+      const text2 = doc2.getText(name);
+      if (!!value) text2.insert(0, value);
+      return text2;
+    },
+    xmlElement(name, children = []) {
+      const xmlElement2 = doc2.getXmlElement(name);
+      if (!!children.length) xmlElement2.insert(0, children);
+      return xmlElement2;
+    },
+    xmlFragment(name, children = []) {
+      const xmlFragment2 = doc2.getXmlFragment(name);
+      if (!!children.length) xmlFragment2.insert(0, children);
+      return xmlFragment2;
+    },
+    xmlText(name) {
+      const xmlText2 = doc2.get(name, import_yjs8.XmlText);
+      return xmlText2;
+    }
+  };
+};
+
 // src/doc/CrdtYjsDoc.ts
 var MERGE_INTERVAL_MS = 1e3;
-var CrdtYjsDoc = class extends import_crdt.AbstractCrdtDoc {
-  constructor(value = {}) {
-    super();
-    this.value = new import_yjs8.Doc();
+var CrdtYjsDoc = class {
+  constructor(params = () => ({})) {
+    this.value = new import_yjs9.Doc();
     this._undoManager = null;
-    this._storage = Object.entries(value).reduce((acc, [key, node]) => {
+    const storage = params(builder(this.value));
+    const keys = this.value.share.keys().reduce((set, key) => set.add(key), /* @__PURE__ */ new Set());
+    this._storage = Object.entries(storage).reduce((acc, [key, node]) => {
       var _a, _b, _c, _d, _e, _f, _g, _h;
+      if (keys.has(key)) return __spreadProps(__spreadValues({}, acc), { [key]: node });
+      if (node instanceof YjsXmlElement) {
+        this._warn(oneLine`
+                    Warning: You are using \`yjs.xmlElement\` 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 yXmlElement = this.value.getXmlElement(key);
+        if (!!((_a = node.initialValue) == null ? void 0 : _a.length)) {
+          yXmlElement.insert(0, (_b = node.initialValue) == null ? void 0 : _b.slice(0));
+        }
+        return __spreadProps(__spreadValues({}, acc), { [key]: yXmlElement });
+      }
+      if (node instanceof YjsXmlFragment) {
+        this._warn(oneLine`
+                    Warning: You are using \`yjs.xmlFragment\` 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 yXmlFragment = this.value.getXmlFragment(key);
+        if (!!((_c = node.initialValue) == null ? void 0 : _c.length)) {
+          yXmlFragment.insert(0, (_d = node.initialValue) == null ? void 0 : _d.slice(0));
+        }
+        return __spreadProps(__spreadValues({}, acc), { [key]: yXmlFragment });
+      }
+      if (node instanceof YjsXmlText) {
+        this._warn(oneLine`
+                    Warning: You are using \`yjs.xmlText\` 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 yXmlText = this.value.get(key, import_yjs9.XmlText);
+        return __spreadProps(__spreadValues({}, acc), { [key]: yXmlText });
+      }
       if (node instanceof YjsArray) {
+        this._warn(oneLine`
+                    Warning: You are using \`yjs.array\` 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 yArray = this.value.getArray(key);
-        if (!!((_a = node.initialValue) == null ? void 0 : _a.length)) yArray.insert(0, (_b = node.initialValue) == null ? void 0 : _b.slice(0));
+        if (!!((_e = node.initialValue) == null ? void 0 : _e.length)) yArray.insert(0, (_f = node.initialValue) == null ? void 0 : _f.slice(0));
         return __spreadProps(__spreadValues({}, acc), { [key]: yArray });
       }
       if (node instanceof YjsMap) {
+        this._warn(oneLine`
+                    Warning: You are using \`yjs.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 yMap = this.value.getMap(key);
-        ((_c = node.initialValue) != null ? _c : []).forEach(([k, v]) => {
+        ((_g = node.initialValue) != null ? _g : []).forEach(([k, v]) => {
           yMap.set(k.toString(), v);
         });
         return __spreadProps(__spreadValues({}, acc), { [key]: yMap });
       }
       if (node instanceof YjsObject) {
+        this._warn(oneLine`
+                    Warning: You are using \`yjs.object\` 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 yMap = this.value.getMap(key);
-        Object.entries((_d = node.initialValue) != null ? _d : {}).forEach(([k, v]) => {
+        Object.entries((_h = node.initialValue) != null ? _h : {}).forEach(([k, v]) => {
           yMap.set(k.toString(), v);
         });
         return __spreadProps(__spreadValues({}, acc), { [key]: yMap });
       }
       if (node instanceof YjsText) {
+        this._warn(oneLine`
+                    Warning: You are using \`yjs.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 yText = this.value.getText(key);
         if (typeof node.initialValue === "string") yText.insert(0, node.initialValue);
         return __spreadProps(__spreadValues({}, acc), { [key]: yText });
       }
-      if (node instanceof YjsXmlElement) {
-        const yXmlElement = this.value.getXmlElement(key);
-        if (!!((_e = node.initialValue) == null ? void 0 : _e.length)) {
-          yXmlElement.insert(0, (_f = node.initialValue) == null ? void 0 : _f.slice(0));
-        }
-        return __spreadProps(__spreadValues({}, acc), { [key]: yXmlElement });
-      }
-      if (node instanceof YjsXmlFragment) {
-        const yXmlFragment = this.value.getXmlFragment(key);
-        if (!!((_g = node.initialValue) == null ? void 0 : _g.length)) {
-          yXmlFragment.insert(0, (_h = node.initialValue) == null ? void 0 : _h.slice(0));
-        }
-        return __spreadProps(__spreadValues({}, acc), { [key]: yXmlFragment });
-      }
-      if (node instanceof YjsXmlText) {
-        const yXmlText = this.value.get(key, import_yjs8.XmlText);
-        return __spreadProps(__spreadValues({}, acc), { [key]: yXmlText });
-      }
       return acc;
     }, {});
   }
@@ -210,7 +296,7 @@ var CrdtYjsDoc = class extends import_crdt.AbstractCrdtDoc {
     const { origin, update } = params;
     if (update === null || typeof update === "undefined") return this;
     const uint8Update = typeof update === "string" ? (0, import_js_base64.toUint8Array)(update) : update;
-    (0, import_yjs8.applyUpdate)(this.value, uint8Update, origin);
+    (0, import_yjs9.applyUpdate)(this.value, uint8Update, origin);
     return this;
   }
   batchApplyEncodedState(params) {
@@ -230,7 +316,7 @@ var CrdtYjsDoc = class extends import_crdt.AbstractCrdtDoc {
       return acc;
     }, []);
     if (!filtered.length) return this;
-    const merged = (0, import_yjs8.mergeUpdates)(filtered);
+    const merged = (0, import_yjs9.mergeUpdates)(filtered);
     return this.applyEncodedState({ origin, update: merged });
   }
   canRedo() {
@@ -251,7 +337,7 @@ var CrdtYjsDoc = class extends import_crdt.AbstractCrdtDoc {
     return this._storage[type];
   }
   getEncodedState() {
-    return (0, import_js_base64.fromUint8Array)((0, import_yjs8.encodeStateAsUpdate)(this.value));
+    return (0, import_js_base64.fromUint8Array)((0, import_yjs9.encodeStateAsUpdate)(this.value));
   }
   isEmpty() {
     return !this.value.share.size;
@@ -263,16 +349,16 @@ var CrdtYjsDoc = class extends import_crdt.AbstractCrdtDoc {
       return this;
     }
     this._storage = Object.entries(reference).reduce((acc, [key, node]) => {
-      if (node instanceof import_yjs8.Array) return __spreadProps(__spreadValues({}, acc), { [key]: this.value.getArray(key) });
-      if (node instanceof import_yjs8.Map) return __spreadProps(__spreadValues({}, acc), { [key]: this.value.getMap(key) });
-      if (node instanceof import_yjs8.Text) return __spreadProps(__spreadValues({}, acc), { [key]: this.value.getText(key) });
-      if (node instanceof import_yjs8.XmlElement) {
+      if (node instanceof import_yjs9.XmlElement) {
         return __spreadProps(__spreadValues({}, acc), { [key]: this.value.getXmlElement(key) });
       }
-      if (node instanceof import_yjs8.XmlFragment) {
+      if (node instanceof import_yjs9.XmlFragment) {
         return __spreadProps(__spreadValues({}, acc), { [key]: this.value.getXmlFragment(key) });
       }
-      if (node instanceof import_yjs8.XmlText) return __spreadProps(__spreadValues({}, acc), { [key]: this.value.get(key, import_yjs8.XmlText) });
+      if (node instanceof import_yjs9.XmlText) return __spreadProps(__spreadValues({}, acc), { [key]: this.value.get(key, import_yjs9.XmlText) });
+      if (node instanceof import_yjs9.Array) return __spreadProps(__spreadValues({}, acc), { [key]: this.value.getArray(key) });
+      if (node instanceof import_yjs9.Map) return __spreadProps(__spreadValues({}, acc), { [key]: this.value.getMap(key) });
+      if (node instanceof import_yjs9.Text) return __spreadProps(__spreadValues({}, acc), { [key]: this.value.getText(key) });
       return acc;
     }, {});
     return this.track();
@@ -301,7 +387,7 @@ var CrdtYjsDoc = class extends import_crdt.AbstractCrdtDoc {
     if (this._undoManager) this._undoManager.destroy();
     const sharedTypes = Object.values(this._storage).reduce(
       (acc, type) => {
-        if (type instanceof import_yjs8.Array || type instanceof import_yjs8.Map || type instanceof import_yjs8.Text || type instanceof import_yjs8.XmlElement || type instanceof import_yjs8.XmlFragment || type instanceof import_yjs8.XmlText) {
+        if (type instanceof import_yjs9.Array || type instanceof import_yjs9.Map || type instanceof import_yjs9.Text || type instanceof import_yjs9.XmlElement || type instanceof import_yjs9.XmlFragment || type instanceof import_yjs9.XmlText) {
           acc.push(type);
         }
         return acc;
@@ -313,7 +399,7 @@ var CrdtYjsDoc = class extends import_crdt.AbstractCrdtDoc {
       this._undoManager = null;
       return this;
     }
-    this._undoManager = new import_yjs8.UndoManager(sharedTypes, { captureTimeout: MERGE_INTERVAL_MS });
+    this._undoManager = new import_yjs9.UndoManager(sharedTypes, { captureTimeout: MERGE_INTERVAL_MS });
     return this;
   }
   transact(fn) {
@@ -332,13 +418,19 @@ var CrdtYjsDoc = 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/CrdtYjsDocFactory.ts
-var import_crdt2 = require("@pluv/crdt");
-var CrdtYjsDocFactory = class _CrdtYjsDocFactory extends import_crdt2.AbstractCrdtDocFactory {
+var import_crdt = require("@pluv/crdt");
+var CrdtYjsDocFactory = class _CrdtYjsDocFactory extends import_crdt.AbstractCrdtDocFactory {
   constructor(initialStorage = () => ({})) {
-    super();
+    super(initialStorage);
     this._initialStorage = initialStorage;
   }
   getEmpty() {
@@ -348,8 +440,7 @@ var CrdtYjsDocFactory = class _CrdtYjsDocFactory extends import_crdt2.AbstractCr
     return new _CrdtYjsDocFactory(initialStorage != null ? initialStorage : this._initialStorage);
   }
   getInitialized(initialStorage) {
-    var _a;
-    return new CrdtYjsDoc((_a = initialStorage == null ? void 0 : initialStorage()) != null ? _a : this._initialStorage());
+    return new CrdtYjsDoc(initialStorage != null ? initialStorage : this._initialStorage);
   }
 };
 

package/dist/index.mjs

@@ -55,17 +55,16 @@ var array = (value = []) => {
 };
 
 // src/doc/CrdtYjsDoc.ts
-import { AbstractCrdtDoc } from "@pluv/crdt";
 import { fromUint8Array, toUint8Array } from "js-base64";
 import {
   UndoManager,
-  Array as YArray2,
-  Doc as YDoc,
-  Map as YMap3,
-  Text as YText2,
-  XmlElement as YXmlElement2,
-  XmlFragment as YXmlFragment2,
-  XmlText as YXmlText2,
+  Array as YArray3,
+  Doc as YDoc2,
+  Map as YMap4,
+  Text as YText3,
+  XmlElement as YXmlElement3,
+  XmlFragment as YXmlFragment3,
+  XmlText as YXmlText3,
   applyUpdate,
   encodeStateAsUpdate,
   mergeUpdates
@@ -107,6 +106,11 @@ var YjsText = class extends YText {
   }
 };
 
+// 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/xmlElement/YjsXmlElement.ts
 import { XmlElement as YXmlElement } from "yjs";
 var YjsXmlElement = class extends YXmlElement {
@@ -145,57 +149,141 @@ var YjsXmlText = class extends YXmlText {
   }
 };
 
+// src/doc/builder.ts
+import {
+  XmlText as YXmlText2
+} from "yjs";
+var builder = (doc2) => {
+  return {
+    array(name, value = []) {
+      const array2 = doc2.getArray(name);
+      if (!!value.length) array2.insert(0, value);
+      return array2;
+    },
+    map(name, value = []) {
+      const map2 = doc2.getMap(name);
+      value.forEach(([k, v]) => {
+        map2.set(k, v);
+      });
+      return map2;
+    },
+    text(name, value = "") {
+      const text2 = doc2.getText(name);
+      if (!!value) text2.insert(0, value);
+      return text2;
+    },
+    xmlElement(name, children = []) {
+      const xmlElement2 = doc2.getXmlElement(name);
+      if (!!children.length) xmlElement2.insert(0, children);
+      return xmlElement2;
+    },
+    xmlFragment(name, children = []) {
+      const xmlFragment2 = doc2.getXmlFragment(name);
+      if (!!children.length) xmlFragment2.insert(0, children);
+      return xmlFragment2;
+    },
+    xmlText(name) {
+      const xmlText2 = doc2.get(name, YXmlText2);
+      return xmlText2;
+    }
+  };
+};
+
 // src/doc/CrdtYjsDoc.ts
 var MERGE_INTERVAL_MS = 1e3;
-var CrdtYjsDoc = class extends AbstractCrdtDoc {
-  constructor(value = {}) {
-    super();
-    this.value = new YDoc();
+var CrdtYjsDoc = class {
+  constructor(params = () => ({})) {
+    this.value = new YDoc2();
     this._undoManager = null;
-    this._storage = Object.entries(value).reduce((acc, [key, node]) => {
+    const storage = params(builder(this.value));
+    const keys = this.value.share.keys().reduce((set, key) => set.add(key), /* @__PURE__ */ new Set());
+    this._storage = Object.entries(storage).reduce((acc, [key, node]) => {
       var _a, _b, _c, _d, _e, _f, _g, _h;
+      if (keys.has(key)) return __spreadProps(__spreadValues({}, acc), { [key]: node });
+      if (node instanceof YjsXmlElement) {
+        this._warn(oneLine`
+                    Warning: You are using \`yjs.xmlElement\` 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 yXmlElement = this.value.getXmlElement(key);
+        if (!!((_a = node.initialValue) == null ? void 0 : _a.length)) {
+          yXmlElement.insert(0, (_b = node.initialValue) == null ? void 0 : _b.slice(0));
+        }
+        return __spreadProps(__spreadValues({}, acc), { [key]: yXmlElement });
+      }
+      if (node instanceof YjsXmlFragment) {
+        this._warn(oneLine`
+                    Warning: You are using \`yjs.xmlFragment\` 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 yXmlFragment = this.value.getXmlFragment(key);
+        if (!!((_c = node.initialValue) == null ? void 0 : _c.length)) {
+          yXmlFragment.insert(0, (_d = node.initialValue) == null ? void 0 : _d.slice(0));
+        }
+        return __spreadProps(__spreadValues({}, acc), { [key]: yXmlFragment });
+      }
+      if (node instanceof YjsXmlText) {
+        this._warn(oneLine`
+                    Warning: You are using \`yjs.xmlText\` 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 yXmlText = this.value.get(key, YXmlText3);
+        return __spreadProps(__spreadValues({}, acc), { [key]: yXmlText });
+      }
       if (node instanceof YjsArray) {
+        this._warn(oneLine`
+                    Warning: You are using \`yjs.array\` 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 yArray = this.value.getArray(key);
-        if (!!((_a = node.initialValue) == null ? void 0 : _a.length)) yArray.insert(0, (_b = node.initialValue) == null ? void 0 : _b.slice(0));
+        if (!!((_e = node.initialValue) == null ? void 0 : _e.length)) yArray.insert(0, (_f = node.initialValue) == null ? void 0 : _f.slice(0));
         return __spreadProps(__spreadValues({}, acc), { [key]: yArray });
       }
       if (node instanceof YjsMap) {
+        this._warn(oneLine`
+                    Warning: You are using \`yjs.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 yMap = this.value.getMap(key);
-        ((_c = node.initialValue) != null ? _c : []).forEach(([k, v]) => {
+        ((_g = node.initialValue) != null ? _g : []).forEach(([k, v]) => {
           yMap.set(k.toString(), v);
         });
         return __spreadProps(__spreadValues({}, acc), { [key]: yMap });
       }
       if (node instanceof YjsObject) {
+        this._warn(oneLine`
+                    Warning: You are using \`yjs.object\` 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 yMap = this.value.getMap(key);
-        Object.entries((_d = node.initialValue) != null ? _d : {}).forEach(([k, v]) => {
+        Object.entries((_h = node.initialValue) != null ? _h : {}).forEach(([k, v]) => {
           yMap.set(k.toString(), v);
         });
         return __spreadProps(__spreadValues({}, acc), { [key]: yMap });
       }
       if (node instanceof YjsText) {
+        this._warn(oneLine`
+                    Warning: You are using \`yjs.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 yText = this.value.getText(key);
         if (typeof node.initialValue === "string") yText.insert(0, node.initialValue);
         return __spreadProps(__spreadValues({}, acc), { [key]: yText });
       }
-      if (node instanceof YjsXmlElement) {
-        const yXmlElement = this.value.getXmlElement(key);
-        if (!!((_e = node.initialValue) == null ? void 0 : _e.length)) {
-          yXmlElement.insert(0, (_f = node.initialValue) == null ? void 0 : _f.slice(0));
-        }
-        return __spreadProps(__spreadValues({}, acc), { [key]: yXmlElement });
-      }
-      if (node instanceof YjsXmlFragment) {
-        const yXmlFragment = this.value.getXmlFragment(key);
-        if (!!((_g = node.initialValue) == null ? void 0 : _g.length)) {
-          yXmlFragment.insert(0, (_h = node.initialValue) == null ? void 0 : _h.slice(0));
-        }
-        return __spreadProps(__spreadValues({}, acc), { [key]: yXmlFragment });
-      }
-      if (node instanceof YjsXmlText) {
-        const yXmlText = this.value.get(key, YXmlText2);
-        return __spreadProps(__spreadValues({}, acc), { [key]: yXmlText });
-      }
       return acc;
     }, {});
   }
@@ -256,16 +344,16 @@ var CrdtYjsDoc = class extends AbstractCrdtDoc {
       return this;
     }
     this._storage = Object.entries(reference).reduce((acc, [key, node]) => {
-      if (node instanceof YArray2) return __spreadProps(__spreadValues({}, acc), { [key]: this.value.getArray(key) });
-      if (node instanceof YMap3) return __spreadProps(__spreadValues({}, acc), { [key]: this.value.getMap(key) });
-      if (node instanceof YText2) return __spreadProps(__spreadValues({}, acc), { [key]: this.value.getText(key) });
-      if (node instanceof YXmlElement2) {
+      if (node instanceof YXmlElement3) {
         return __spreadProps(__spreadValues({}, acc), { [key]: this.value.getXmlElement(key) });
       }
-      if (node instanceof YXmlFragment2) {
+      if (node instanceof YXmlFragment3) {
         return __spreadProps(__spreadValues({}, acc), { [key]: this.value.getXmlFragment(key) });
       }
-      if (node instanceof YXmlText2) return __spreadProps(__spreadValues({}, acc), { [key]: this.value.get(key, YXmlText2) });
+      if (node instanceof YXmlText3) return __spreadProps(__spreadValues({}, acc), { [key]: this.value.get(key, YXmlText3) });
+      if (node instanceof YArray3) return __spreadProps(__spreadValues({}, acc), { [key]: this.value.getArray(key) });
+      if (node instanceof YMap4) return __spreadProps(__spreadValues({}, acc), { [key]: this.value.getMap(key) });
+      if (node instanceof YText3) return __spreadProps(__spreadValues({}, acc), { [key]: this.value.getText(key) });
       return acc;
     }, {});
     return this.track();
@@ -294,7 +382,7 @@ var CrdtYjsDoc = class extends AbstractCrdtDoc {
     if (this._undoManager) this._undoManager.destroy();
     const sharedTypes = Object.values(this._storage).reduce(
       (acc, type) => {
-        if (type instanceof YArray2 || type instanceof YMap3 || type instanceof YText2 || type instanceof YXmlElement2 || type instanceof YXmlFragment2 || type instanceof YXmlText2) {
+        if (type instanceof YArray3 || type instanceof YMap4 || type instanceof YText3 || type instanceof YXmlElement3 || type instanceof YXmlFragment3 || type instanceof YXmlText3) {
           acc.push(type);
         }
         return acc;
@@ -325,13 +413,19 @@ var CrdtYjsDoc = 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/CrdtYjsDocFactory.ts
 import { AbstractCrdtDocFactory } from "@pluv/crdt";
 var CrdtYjsDocFactory = class _CrdtYjsDocFactory extends AbstractCrdtDocFactory {
   constructor(initialStorage = () => ({})) {
-    super();
+    super(initialStorage);
     this._initialStorage = initialStorage;
   }
   getEmpty() {
@@ -341,8 +435,7 @@ var CrdtYjsDocFactory = class _CrdtYjsDocFactory extends AbstractCrdtDocFactory
     return new _CrdtYjsDocFactory(initialStorage != null ? initialStorage : this._initialStorage);
   }
   getInitialized(initialStorage) {
-    var _a;
-    return new CrdtYjsDoc((_a = initialStorage == null ? void 0 : initialStorage()) != null ? _a : this._initialStorage());
+    return new CrdtYjsDoc(initialStorage != null ? initialStorage : this._initialStorage);
   }
 };
 

package/package.json

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

package/src/doc/CrdtYjsDoc.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 {
     AbstractType,
@@ -25,25 +25,100 @@ import { YjsMap } from "../map/YjsMap";
 import { YjsObject } from "../object/YjsObject";
 import { YjsText } from "../text/YjsText";
 import type { YjsType } from "../types";
+import { oneLine } from "../utils";
 import { YjsXmlElement } from "../xmlElement/YjsXmlElement";
 import { YjsXmlFragment } from "../xmlFragment/YjsXmlFragment";
 import { YjsXmlText } from "../xmlText/YjsXmlText";
+import type { YjsBuilder } from "./builder";
+import { builder } from "./builder";
 
 const MERGE_INTERVAL_MS = 1_000;
 
-export class CrdtYjsDoc<
-    TStorage extends Record<string, YjsType<any, any>>,
-> extends AbstractCrdtDoc<TStorage> {
+export type CrdtYjsDocParams<TStorage extends Record<string, YjsType<any, any>>> = (
+    builder: YjsBuilder,
+) => TStorage;
+
+export class CrdtYjsDoc<TStorage extends Record<string, YjsType<any, any>>>
+    implements CrdtDocLike<TStorage>
+{
     public value: YDoc = new YDoc();
 
     private _storage: TStorage;
     private _undoManager: UndoManager | null = null;
 
-    constructor(value: TStorage = {} as TStorage) {
-        super();
+    constructor(params: CrdtYjsDocParams<TStorage> = () => ({}) as TStorage) {
+        const storage = params(builder(this.value));
+        const keys = this.value.share.keys().reduce((set, key) => set.add(key), new Set<string>());
+
+        this._storage = Object.entries(storage).reduce((acc, [key, node]) => {
+            /**
+             * @description These are all shared 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 };
+
+            /**
+             * @description It is important that the XML shared-types be checked before the others
+             * because they extend off the non-xml types (thereby you can mistakenly identify the
+             * wrong type if checked in the reverse order)
+             * @date May 9 ,2025
+             */
+            if (node instanceof YjsXmlElement) {
+                this._warn(oneLine`
+                    Warning: You are using \`yjs.xmlElement\` 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 yXmlElement = this.value.getXmlElement(key);
+
+                if (!!node.initialValue?.length) {
+                    yXmlElement.insert(0, node.initialValue?.slice(0));
+                }
+
+                return { ...acc, [key]: yXmlElement };
+            }
+
+            if (node instanceof YjsXmlFragment) {
+                this._warn(oneLine`
+                    Warning: You are using \`yjs.xmlFragment\` 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 yXmlFragment = this.value.getXmlFragment(key);
+
+                if (!!node.initialValue?.length) {
+                    yXmlFragment.insert(0, node.initialValue?.slice(0));
+                }
+
+                return { ...acc, [key]: yXmlFragment };
+            }
+
+            if (node instanceof YjsXmlText) {
+                this._warn(oneLine`
+                    Warning: You are using \`yjs.xmlText\` 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 yXmlText = this.value.get(key, YXmlText) as YXmlText;
+
+                return { ...acc, [key]: yXmlText };
+            }
 
-        this._storage = Object.entries(value).reduce((acc, [key, node]) => {
             if (node instanceof YjsArray) {
+                this._warn(oneLine`
+                    Warning: You are using \`yjs.array\` 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 yArray = this.value.getArray(key);
 
                 if (!!node.initialValue?.length) yArray.insert(0, node.initialValue?.slice(0));
@@ -52,6 +127,13 @@ export class CrdtYjsDoc<
             }
 
             if (node instanceof YjsMap) {
+                this._warn(oneLine`
+                    Warning: You are using \`yjs.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 yMap = this.value.getMap(key);
 
                 (node.initialValue ?? []).forEach(([k, v]) => {
@@ -62,6 +144,13 @@ export class CrdtYjsDoc<
             }
 
             if (node instanceof YjsObject) {
+                this._warn(oneLine`
+                    Warning: You are using \`yjs.object\` 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 yMap = this.value.getMap(key);
 
                 Object.entries(node.initialValue ?? {}).forEach(([k, v]) => {
@@ -72,6 +161,13 @@ export class CrdtYjsDoc<
             }
 
             if (node instanceof YjsText) {
+                this._warn(oneLine`
+                    Warning: You are using \`yjs.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 yText = this.value.getText(key);
 
                 if (typeof node.initialValue === "string") yText.insert(0, node.initialValue);
@@ -79,32 +175,6 @@ export class CrdtYjsDoc<
                 return { ...acc, [key]: yText };
             }
 
-            if (node instanceof YjsXmlElement) {
-                const yXmlElement = this.value.getXmlElement(key);
-
-                if (!!node.initialValue?.length) {
-                    yXmlElement.insert(0, node.initialValue?.slice(0));
-                }
-
-                return { ...acc, [key]: yXmlElement };
-            }
-
-            if (node instanceof YjsXmlFragment) {
-                const yXmlFragment = this.value.getXmlFragment(key);
-
-                if (!!node.initialValue?.length) {
-                    yXmlFragment.insert(0, node.initialValue?.slice(0));
-                }
-
-                return { ...acc, [key]: yXmlFragment };
-            }
-
-            if (node instanceof YjsXmlText) {
-                const yXmlText = this.value.get(key, YXmlText) as YXmlText;
-
-                return { ...acc, [key]: yXmlText };
-            }
-
             return acc;
         }, {} as TStorage);
     }
@@ -186,9 +256,12 @@ export class CrdtYjsDoc<
         }
 
         this._storage = Object.entries(reference).reduce((acc, [key, node]) => {
-            if (node instanceof YArray) return { ...acc, [key]: this.value.getArray(key) };
-            if (node instanceof YMap) return { ...acc, [key]: this.value.getMap(key) };
-            if (node instanceof YText) return { ...acc, [key]: this.value.getText(key) };
+            /**
+             * @description It is important that the XML shared-types be checked before the others
+             * because they extend off the non-xml types (thereby you can mistakenly identify the
+             * wrong type if checked in the reverse order)
+             * @date May 9 ,2025
+             */
             if (node instanceof YXmlElement) {
                 return { ...acc, [key]: this.value.getXmlElement(key) };
             }
@@ -196,6 +269,9 @@ export class CrdtYjsDoc<
                 return { ...acc, [key]: this.value.getXmlFragment(key) };
             }
             if (node instanceof YXmlText) return { ...acc, [key]: this.value.get(key, YXmlText) };
+            if (node instanceof YArray) return { ...acc, [key]: this.value.getArray(key) };
+            if (node instanceof YMap) return { ...acc, [key]: this.value.getMap(key) };
+            if (node instanceof YText) return { ...acc, [key]: this.value.getText(key) };
 
             return acc;
         }, {} as TStorage);
@@ -281,4 +357,10 @@ export class CrdtYjsDoc<
 
         return this;
     }
+
+    private _warn(...data: any[]) {
+        if (typeof process === "undefined") return;
+        if (process.env?.NODE_ENV === "production") return;
+        console.log(...data);
+    }
 }

package/src/doc/CrdtYjsDocFactory.ts

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

package/src/doc/builder.ts

@@ -0,0 +1,71 @@
+import {
+    Array as YArray,
+    Doc as YDoc,
+    Map as YMap,
+    Text as YText,
+    XmlElement as YXmlElement,
+    XmlFragment as YXmlFragment,
+    XmlText as YXmlText,
+} from "yjs";
+import { YjsType } from "../types";
+
+export type YjsBuilder = ReturnType<typeof builder>;
+
+export const builder = (doc: YDoc) => {
+    return {
+        array<T extends unknown>(
+            name: string,
+            value: T[] | readonly T[] = [],
+        ): YjsType<YArray<T>, T[]> {
+            const array = doc.getArray<T>(name);
+
+            if (!!value.length) array.insert(0, value as T[]);
+
+            return array as unknown as YjsType<YArray<T>, T[]>;
+        },
+        map<T extends unknown>(
+            name: string,
+            value: readonly (readonly [key: string, value: T])[] = [],
+        ): YjsType<YMap<T>, Record<string, T>> {
+            const map = doc.getMap(name);
+
+            value.forEach(([k, v]) => {
+                map.set(k, v);
+            });
+
+            return map as unknown as YjsType<YMap<T>, Record<string, T>>;
+        },
+        text(name: string, value: string = ""): YjsType<YText, string> {
+            const text = doc.getText(name);
+
+            if (!!value) text.insert(0, value);
+
+            return text as unknown as YjsType<YText, string>;
+        },
+        xmlElement(
+            name: string,
+            children: (YXmlElement | YXmlText)[] | readonly (YXmlElement | YXmlText)[] = [],
+        ): YjsType<YXmlElement, string> {
+            const xmlElement = doc.getXmlElement(name);
+
+            if (!!children.length) xmlElement.insert(0, children as (YXmlElement | YXmlText)[]);
+
+            return xmlElement as unknown as YjsType<YXmlElement, string>;
+        },
+        xmlFragment(
+            name: string,
+            children: (YXmlElement | YXmlText)[] | readonly (YXmlElement | YXmlText)[] = [],
+        ): YjsType<YXmlFragment, string> {
+            const xmlFragment = doc.getXmlFragment(name);
+
+            if (!!children.length) xmlFragment.insert(0, children as (YXmlElement | YXmlText)[]);
+
+            return xmlFragment as unknown as YjsType<YXmlFragment, string>;
+        },
+        xmlText(name: string): YjsType<YXmlText, string> {
+            const xmlText = doc.get(name, YXmlText);
+
+            return xmlText as unknown as YjsType<YXmlText, string>;
+        },
+    };
+};

package/src/doc/doc.ts

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

package/src/doc/index.ts

@@ -1,3 +1,4 @@
+export type { YjsBuilder } from "./builder";
 export { CrdtYjsDoc } from "./CrdtYjsDoc";
 export { CrdtYjsDocFactory } from "./CrdtYjsDocFactory";
 export { doc } from "./doc";

package/src/object/object.ts

@@ -2,6 +2,11 @@ import type { Map as YMap } from "yjs";
 import type { YjsType } from "../types";
 import { YjsObject } from "./YjsObject";
 
+/**
+ * @deprecated This will be removed in v2.0.0. Use yjs.map instead
+ * @description Creates a Yjs map, but declare it like it's an object
+ * @date May 8, 2025
+ */
 export const object = <T extends Record<string, any>>(
     value: T = {} as T,
 ): YjsType<YMap<T[keyof T]>, T> => {

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();
+};

package/src/yjs.ts

@@ -1,5 +1,6 @@
 export { array } from "./array";
 export { doc } from "./doc";
+export type { YjsBuilder } from "./doc";
 export { map } from "./map";
 export { object } from "./object";
 export { text } from "./text";