@noy-db/yjs 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vLannaAi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.cjs

@@ -0,0 +1,157 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  YjsCollection: () => YjsCollection,
+  yArray: () => yArray,
+  yMap: () => yMap,
+  yText: () => yText,
+  yjsCollection: () => yjsCollection
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/yjs-collection.ts
+var Y = __toESM(require("yjs"), 1);
+var YjsCollection = class {
+  /** @internal — use `yjsCollection()` factory instead. */
+  constructor(compartment, name, opts) {
+    this.compartment = compartment;
+    this.name = name;
+    this.yFields = opts.yFields;
+    this.coll = compartment.collection(name, { crdt: "yjs" });
+  }
+  compartment;
+  name;
+  coll;
+  yFields;
+  /**
+   * Get the Y.Doc for a record.
+   *
+   * If the record does not exist, returns a fresh empty Y.Doc with the declared
+   * `yFields` initialised (Y.Text / Y.Map / Y.Array as declared).
+   *
+   * If the record exists, the stored Yjs update is applied to the returned doc.
+   */
+  async getYDoc(id) {
+    const doc = new Y.Doc();
+    this.initFields(doc);
+    const base64Update = await this.coll.get(id);
+    if (base64Update) {
+      const bytes = base64ToUint8Array(base64Update);
+      Y.applyUpdate(doc, bytes);
+    }
+    return doc;
+  }
+  /**
+   * Persist a Y.Doc by encoding its state as a Yjs update and storing it
+   * as the encrypted envelope payload.
+   */
+  async putYDoc(id, doc) {
+    const update = Y.encodeStateAsUpdate(doc);
+    const base64 = uint8ArrayToBase64(update);
+    await this.coll.put(id, base64);
+  }
+  /**
+   * Merge a Yjs update into an existing record.
+   * Reads the current doc, applies the update, then persists the merged state.
+   */
+  async applyUpdate(id, update) {
+    const doc = await this.getYDoc(id);
+    Y.applyUpdate(doc, update);
+    await this.putYDoc(id, doc);
+  }
+  /**
+   * Delete the record.
+   */
+  async delete(id) {
+    await this.coll.delete(id);
+  }
+  /**
+   * Check whether a record exists.
+   */
+  async has(id) {
+    return await this.coll.get(id) !== null;
+  }
+  // ─── Private ────────────────────────────────────────────────────────
+  initFields(doc) {
+    for (const [fieldName, descriptor] of Object.entries(this.yFields)) {
+      switch (descriptor._yjsType) {
+        case "Y.Text":
+          doc.getText(fieldName);
+          break;
+        case "Y.Map":
+          doc.getMap(fieldName);
+          break;
+        case "Y.Array":
+          doc.getArray(fieldName);
+          break;
+      }
+    }
+  }
+};
+function uint8ArrayToBase64(bytes) {
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}
+function base64ToUint8Array(base64) {
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+function yjsCollection(compartment, name, opts) {
+  return new YjsCollection(compartment, name, opts);
+}
+
+// src/descriptors.ts
+function yText() {
+  return { _yjsType: "Y.Text" };
+}
+function yMap() {
+  return { _yjsType: "Y.Map" };
+}
+function yArray() {
+  return { _yjsType: "Y.Array" };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  YjsCollection,
+  yArray,
+  yMap,
+  yText,
+  yjsCollection
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/yjs-collection.ts","../src/descriptors.ts"],"sourcesContent":["/**\n * @noy-db/yjs — Yjs Y.Doc interop for noy-db.\n *\n * Enables collaborative rich-text editing with encrypted-at-rest Yjs state.\n * Requires peer dependencies: `@noy-db/core` and `yjs >= 13`.\n *\n * @example\n * ```ts\n * import { yjsCollection, yText } from '@noy-db/yjs'\n *\n * const notes = yjsCollection(comp, 'notes', {\n *   yFields: { body: yText() },\n * })\n *\n * const doc = await notes.getYDoc('note-1')\n * doc.getText('body').insert(0, 'Hello world')\n * await notes.putYDoc('note-1', doc)\n * ```\n */\n\nexport { yjsCollection, YjsCollection } from './yjs-collection.js'\nexport type {\n  YjsCollectionOptions,\n  YjsSnapshot,\n} from './yjs-collection.js'\n\nexport { yText, yMap, yArray } from './descriptors.js'\nexport type {\n  YFieldDescriptor,\n  YTextDescriptor,\n  YMapDescriptor,\n  YArrayDescriptor,\n} from './descriptors.js'\n","/**\n * YjsCollection — wraps a noy-db Collection<string> (crdt: 'yjs') with\n * Y.Doc-aware `getYDoc` and `putYDoc` methods.\n *\n * The encrypted envelope stores base64(Y.encodeStateAsUpdate(ydoc)) in `_data`.\n * `collection.get(id)` returns this raw base64 string. `getYDoc(id)` decodes\n * it into a Y.Doc and applies any `yFields` initialisation.\n *\n * v0.9 #136\n */\n\nimport * as Y from 'yjs'\nimport type { Compartment } from '@noy-db/core'\nimport type { YFieldDescriptor } from './descriptors.js'\n\n/** A resolved snapshot of a Yjs-backed record. Field values depend on yFields descriptors. */\nexport type YjsSnapshot<YF extends Record<string, YFieldDescriptor>> = {\n  [K in keyof YF]: YF[K] extends { _yjsType: 'Y.Text' }\n    ? Y.Text\n    : YF[K] extends { _yjsType: 'Y.Map' }\n      ? Y.Map<unknown>\n      : Y.Array<unknown>\n}\n\n/** Options for creating a YjsCollection. */\nexport interface YjsCollectionOptions<YF extends Record<string, YFieldDescriptor>> {\n  /** The field descriptors — tells YjsCollection which Y.* types to initialise. */\n  yFields: YF\n}\n\n/**\n * A YjsCollection wraps a noy-db `crdt: 'yjs'` collection and exposes\n * `getYDoc(id)` and `putYDoc(id, ydoc)` instead of the raw `get`/`put` API.\n *\n * Construct via `yjsCollection(compartment, name, opts)`.\n */\nexport class YjsCollection<YF extends Record<string, YFieldDescriptor>> {\n  private readonly coll: ReturnType<Compartment['collection']>\n  private readonly yFields: YF\n\n  /** @internal — use `yjsCollection()` factory instead. */\n  constructor(\n    private readonly compartment: Compartment,\n    private readonly name: string,\n    opts: YjsCollectionOptions<YF>,\n  ) {\n    this.yFields = opts.yFields\n    // Collection<string> with crdt: 'yjs' — T = string (the base64 update blob)\n    this.coll = compartment.collection<string>(name, { crdt: 'yjs' })\n  }\n\n  /**\n   * Get the Y.Doc for a record.\n   *\n   * If the record does not exist, returns a fresh empty Y.Doc with the declared\n   * `yFields` initialised (Y.Text / Y.Map / Y.Array as declared).\n   *\n   * If the record exists, the stored Yjs update is applied to the returned doc.\n   */\n  async getYDoc(id: string): Promise<Y.Doc> {\n    const doc = new Y.Doc()\n    this.initFields(doc)\n\n    const base64Update = await this.coll.get(id) as string | null\n    if (base64Update) {\n      const bytes = base64ToUint8Array(base64Update)\n      Y.applyUpdate(doc, bytes)\n    }\n\n    return doc\n  }\n\n  /**\n   * Persist a Y.Doc by encoding its state as a Yjs update and storing it\n   * as the encrypted envelope payload.\n   */\n  async putYDoc(id: string, doc: Y.Doc): Promise<void> {\n    const update = Y.encodeStateAsUpdate(doc)\n    const base64 = uint8ArrayToBase64(update)\n    await this.coll.put(id, base64)\n  }\n\n  /**\n   * Merge a Yjs update into an existing record.\n   * Reads the current doc, applies the update, then persists the merged state.\n   */\n  async applyUpdate(id: string, update: Uint8Array): Promise<void> {\n    const doc = await this.getYDoc(id)\n    Y.applyUpdate(doc, update)\n    await this.putYDoc(id, doc)\n  }\n\n  /**\n   * Delete the record.\n   */\n  async delete(id: string): Promise<void> {\n    await this.coll.delete(id)\n  }\n\n  /**\n   * Check whether a record exists.\n   */\n  async has(id: string): Promise<boolean> {\n    return (await this.coll.get(id)) !== null\n  }\n\n  // ─── Private ────────────────────────────────────────────────────────\n\n  private initFields(doc: Y.Doc): void {\n    for (const [fieldName, descriptor] of Object.entries(this.yFields)) {\n      switch (descriptor._yjsType) {\n        case 'Y.Text':\n          doc.getText(fieldName)\n          break\n        case 'Y.Map':\n          doc.getMap(fieldName)\n          break\n        case 'Y.Array':\n          doc.getArray(fieldName)\n          break\n      }\n    }\n  }\n}\n\n// ─── Base64 helpers ───────────────────────────────────────────────────────────\n\nfunction uint8ArrayToBase64(bytes: Uint8Array): string {\n  let binary = ''\n  for (let i = 0; i < bytes.length; i++) {\n    binary += String.fromCharCode(bytes[i]!)\n  }\n  return btoa(binary)\n}\n\nfunction base64ToUint8Array(base64: string): Uint8Array {\n  const binary = atob(base64)\n  const bytes = new Uint8Array(binary.length)\n  for (let i = 0; i < binary.length; i++) {\n    bytes[i] = binary.charCodeAt(i)\n  }\n  return bytes\n}\n\n// ─── Factory function ─────────────────────────────────────────────────────────\n\n/**\n * Create a `YjsCollection` for a compartment.\n *\n * @param compartment  An opened NOYDB compartment.\n * @param name         Collection name (must not start with `_`).\n * @param opts         Field descriptors (`yFields`) and optional collection settings.\n *\n * @example\n * ```ts\n * import { yjsCollection, yText } from '@noy-db/yjs'\n *\n * const notes = yjsCollection(comp, 'notes', {\n *   yFields: { body: yText() },\n * })\n *\n * const doc = await notes.getYDoc('note-1')\n * doc.getText('body').insert(0, 'Hello world')\n * await notes.putYDoc('note-1', doc)\n * ```\n */\nexport function yjsCollection<YF extends Record<string, YFieldDescriptor>>(\n  compartment: Compartment,\n  name: string,\n  opts: YjsCollectionOptions<YF>,\n): YjsCollection<YF> {\n  return new YjsCollection(compartment, name, opts)\n}\n","/**\n * Field descriptors for Yjs-backed fields in @noy-db/yjs.\n * Mirrors the dictKey / i18nText descriptor pattern from @noy-db/core.\n */\n\n/** Descriptor for a Y.Text field (rich text, TipTap/ProseMirror compatible). */\nexport interface YTextDescriptor {\n  readonly _yjsType: 'Y.Text'\n}\n\n/** Descriptor for a Y.Map<string> field. */\nexport interface YMapDescriptor {\n  readonly _yjsType: 'Y.Map'\n}\n\n/** Descriptor for a Y.Array field. */\nexport interface YArrayDescriptor {\n  readonly _yjsType: 'Y.Array'\n}\n\nexport type YFieldDescriptor = YTextDescriptor | YMapDescriptor | YArrayDescriptor\n\n/** Declare a Y.Text field (rich text). */\nexport function yText(): YTextDescriptor {\n  return { _yjsType: 'Y.Text' }\n}\n\n/** Declare a Y.Map field. */\nexport function yMap(): YMapDescriptor {\n  return { _yjsType: 'Y.Map' }\n}\n\n/** Declare a Y.Array field. */\nexport function yArray(): YArrayDescriptor {\n  return { _yjsType: 'Y.Array' }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACWA,QAAmB;AAyBZ,IAAM,gBAAN,MAAiE;AAAA;AAAA,EAKtE,YACmB,aACA,MACjB,MACA;AAHiB;AACA;AAGjB,SAAK,UAAU,KAAK;AAEpB,SAAK,OAAO,YAAY,WAAmB,MAAM,EAAE,MAAM,MAAM,CAAC;AAAA,EAClE;AAAA,EAPmB;AAAA,EACA;AAAA,EANF;AAAA,EACA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAqBjB,MAAM,QAAQ,IAA4B;AACxC,UAAM,MAAM,IAAM,MAAI;AACtB,SAAK,WAAW,GAAG;AAEnB,UAAM,eAAe,MAAM,KAAK,KAAK,IAAI,EAAE;AAC3C,QAAI,cAAc;AAChB,YAAM,QAAQ,mBAAmB,YAAY;AAC7C,MAAE,cAAY,KAAK,KAAK;AAAA,IAC1B;AAEA,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,MAAM,QAAQ,IAAY,KAA2B;AACnD,UAAM,SAAW,sBAAoB,GAAG;AACxC,UAAM,SAAS,mBAAmB,MAAM;AACxC,UAAM,KAAK,KAAK,IAAI,IAAI,MAAM;AAAA,EAChC;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,MAAM,YAAY,IAAY,QAAmC;AAC/D,UAAM,MAAM,MAAM,KAAK,QAAQ,EAAE;AACjC,IAAE,cAAY,KAAK,MAAM;AACzB,UAAM,KAAK,QAAQ,IAAI,GAAG;AAAA,EAC5B;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,OAAO,IAA2B;AACtC,UAAM,KAAK,KAAK,OAAO,EAAE;AAAA,EAC3B;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,IAAI,IAA8B;AACtC,WAAQ,MAAM,KAAK,KAAK,IAAI,EAAE,MAAO;AAAA,EACvC;AAAA;AAAA,EAIQ,WAAW,KAAkB;AACnC,eAAW,CAAC,WAAW,UAAU,KAAK,OAAO,QAAQ,KAAK,OAAO,GAAG;AAClE,cAAQ,WAAW,UAAU;AAAA,QAC3B,KAAK;AACH,cAAI,QAAQ,SAAS;AACrB;AAAA,QACF,KAAK;AACH,cAAI,OAAO,SAAS;AACpB;AAAA,QACF,KAAK;AACH,cAAI,SAAS,SAAS;AACtB;AAAA,MACJ;AAAA,IACF;AAAA,EACF;AACF;AAIA,SAAS,mBAAmB,OAA2B;AACrD,MAAI,SAAS;AACb,WAAS,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK;AACrC,cAAU,OAAO,aAAa,MAAM,CAAC,CAAE;AAAA,EACzC;AACA,SAAO,KAAK,MAAM;AACpB;AAEA,SAAS,mBAAmB,QAA4B;AACtD,QAAM,SAAS,KAAK,MAAM;AAC1B,QAAM,QAAQ,IAAI,WAAW,OAAO,MAAM;AAC1C,WAAS,IAAI,GAAG,IAAI,OAAO,QAAQ,KAAK;AACtC,UAAM,CAAC,IAAI,OAAO,WAAW,CAAC;AAAA,EAChC;AACA,SAAO;AACT;AAwBO,SAAS,cACd,aACA,MACA,MACmB;AACnB,SAAO,IAAI,cAAc,aAAa,MAAM,IAAI;AAClD;;;ACrJO,SAAS,QAAyB;AACvC,SAAO,EAAE,UAAU,SAAS;AAC9B;AAGO,SAAS,OAAuB;AACrC,SAAO,EAAE,UAAU,QAAQ;AAC7B;AAGO,SAAS,SAA2B;AACzC,SAAO,EAAE,UAAU,UAAU;AAC/B;","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,116 @@
+import * as Y from 'yjs';
+import { Compartment } from '@noy-db/core';
+
+/**
+ * Field descriptors for Yjs-backed fields in @noy-db/yjs.
+ * Mirrors the dictKey / i18nText descriptor pattern from @noy-db/core.
+ */
+/** Descriptor for a Y.Text field (rich text, TipTap/ProseMirror compatible). */
+interface YTextDescriptor {
+    readonly _yjsType: 'Y.Text';
+}
+/** Descriptor for a Y.Map<string> field. */
+interface YMapDescriptor {
+    readonly _yjsType: 'Y.Map';
+}
+/** Descriptor for a Y.Array field. */
+interface YArrayDescriptor {
+    readonly _yjsType: 'Y.Array';
+}
+type YFieldDescriptor = YTextDescriptor | YMapDescriptor | YArrayDescriptor;
+/** Declare a Y.Text field (rich text). */
+declare function yText(): YTextDescriptor;
+/** Declare a Y.Map field. */
+declare function yMap(): YMapDescriptor;
+/** Declare a Y.Array field. */
+declare function yArray(): YArrayDescriptor;
+
+/**
+ * YjsCollection — wraps a noy-db Collection<string> (crdt: 'yjs') with
+ * Y.Doc-aware `getYDoc` and `putYDoc` methods.
+ *
+ * The encrypted envelope stores base64(Y.encodeStateAsUpdate(ydoc)) in `_data`.
+ * `collection.get(id)` returns this raw base64 string. `getYDoc(id)` decodes
+ * it into a Y.Doc and applies any `yFields` initialisation.
+ *
+ * v0.9 #136
+ */
+
+/** A resolved snapshot of a Yjs-backed record. Field values depend on yFields descriptors. */
+type YjsSnapshot<YF extends Record<string, YFieldDescriptor>> = {
+    [K in keyof YF]: YF[K] extends {
+        _yjsType: 'Y.Text';
+    } ? Y.Text : YF[K] extends {
+        _yjsType: 'Y.Map';
+    } ? Y.Map<unknown> : Y.Array<unknown>;
+};
+/** Options for creating a YjsCollection. */
+interface YjsCollectionOptions<YF extends Record<string, YFieldDescriptor>> {
+    /** The field descriptors — tells YjsCollection which Y.* types to initialise. */
+    yFields: YF;
+}
+/**
+ * A YjsCollection wraps a noy-db `crdt: 'yjs'` collection and exposes
+ * `getYDoc(id)` and `putYDoc(id, ydoc)` instead of the raw `get`/`put` API.
+ *
+ * Construct via `yjsCollection(compartment, name, opts)`.
+ */
+declare class YjsCollection<YF extends Record<string, YFieldDescriptor>> {
+    private readonly compartment;
+    private readonly name;
+    private readonly coll;
+    private readonly yFields;
+    /** @internal — use `yjsCollection()` factory instead. */
+    constructor(compartment: Compartment, name: string, opts: YjsCollectionOptions<YF>);
+    /**
+     * Get the Y.Doc for a record.
+     *
+     * If the record does not exist, returns a fresh empty Y.Doc with the declared
+     * `yFields` initialised (Y.Text / Y.Map / Y.Array as declared).
+     *
+     * If the record exists, the stored Yjs update is applied to the returned doc.
+     */
+    getYDoc(id: string): Promise<Y.Doc>;
+    /**
+     * Persist a Y.Doc by encoding its state as a Yjs update and storing it
+     * as the encrypted envelope payload.
+     */
+    putYDoc(id: string, doc: Y.Doc): Promise<void>;
+    /**
+     * Merge a Yjs update into an existing record.
+     * Reads the current doc, applies the update, then persists the merged state.
+     */
+    applyUpdate(id: string, update: Uint8Array): Promise<void>;
+    /**
+     * Delete the record.
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Check whether a record exists.
+     */
+    has(id: string): Promise<boolean>;
+    private initFields;
+}
+/**
+ * Create a `YjsCollection` for a compartment.
+ *
+ * @param compartment  An opened NOYDB compartment.
+ * @param name         Collection name (must not start with `_`).
+ * @param opts         Field descriptors (`yFields`) and optional collection settings.
+ *
+ * @example
+ * ```ts
+ * import { yjsCollection, yText } from '@noy-db/yjs'
+ *
+ * const notes = yjsCollection(comp, 'notes', {
+ *   yFields: { body: yText() },
+ * })
+ *
+ * const doc = await notes.getYDoc('note-1')
+ * doc.getText('body').insert(0, 'Hello world')
+ * await notes.putYDoc('note-1', doc)
+ * ```
+ */
+declare function yjsCollection<YF extends Record<string, YFieldDescriptor>>(compartment: Compartment, name: string, opts: YjsCollectionOptions<YF>): YjsCollection<YF>;
+
+export { type YArrayDescriptor, type YFieldDescriptor, type YMapDescriptor, type YTextDescriptor, YjsCollection, type YjsCollectionOptions, type YjsSnapshot, yArray, yMap, yText, yjsCollection };

package/dist/index.d.ts

@@ -0,0 +1,116 @@
+import * as Y from 'yjs';
+import { Compartment } from '@noy-db/core';
+
+/**
+ * Field descriptors for Yjs-backed fields in @noy-db/yjs.
+ * Mirrors the dictKey / i18nText descriptor pattern from @noy-db/core.
+ */
+/** Descriptor for a Y.Text field (rich text, TipTap/ProseMirror compatible). */
+interface YTextDescriptor {
+    readonly _yjsType: 'Y.Text';
+}
+/** Descriptor for a Y.Map<string> field. */
+interface YMapDescriptor {
+    readonly _yjsType: 'Y.Map';
+}
+/** Descriptor for a Y.Array field. */
+interface YArrayDescriptor {
+    readonly _yjsType: 'Y.Array';
+}
+type YFieldDescriptor = YTextDescriptor | YMapDescriptor | YArrayDescriptor;
+/** Declare a Y.Text field (rich text). */
+declare function yText(): YTextDescriptor;
+/** Declare a Y.Map field. */
+declare function yMap(): YMapDescriptor;
+/** Declare a Y.Array field. */
+declare function yArray(): YArrayDescriptor;
+
+/**
+ * YjsCollection — wraps a noy-db Collection<string> (crdt: 'yjs') with
+ * Y.Doc-aware `getYDoc` and `putYDoc` methods.
+ *
+ * The encrypted envelope stores base64(Y.encodeStateAsUpdate(ydoc)) in `_data`.
+ * `collection.get(id)` returns this raw base64 string. `getYDoc(id)` decodes
+ * it into a Y.Doc and applies any `yFields` initialisation.
+ *
+ * v0.9 #136
+ */
+
+/** A resolved snapshot of a Yjs-backed record. Field values depend on yFields descriptors. */
+type YjsSnapshot<YF extends Record<string, YFieldDescriptor>> = {
+    [K in keyof YF]: YF[K] extends {
+        _yjsType: 'Y.Text';
+    } ? Y.Text : YF[K] extends {
+        _yjsType: 'Y.Map';
+    } ? Y.Map<unknown> : Y.Array<unknown>;
+};
+/** Options for creating a YjsCollection. */
+interface YjsCollectionOptions<YF extends Record<string, YFieldDescriptor>> {
+    /** The field descriptors — tells YjsCollection which Y.* types to initialise. */
+    yFields: YF;
+}
+/**
+ * A YjsCollection wraps a noy-db `crdt: 'yjs'` collection and exposes
+ * `getYDoc(id)` and `putYDoc(id, ydoc)` instead of the raw `get`/`put` API.
+ *
+ * Construct via `yjsCollection(compartment, name, opts)`.
+ */
+declare class YjsCollection<YF extends Record<string, YFieldDescriptor>> {
+    private readonly compartment;
+    private readonly name;
+    private readonly coll;
+    private readonly yFields;
+    /** @internal — use `yjsCollection()` factory instead. */
+    constructor(compartment: Compartment, name: string, opts: YjsCollectionOptions<YF>);
+    /**
+     * Get the Y.Doc for a record.
+     *
+     * If the record does not exist, returns a fresh empty Y.Doc with the declared
+     * `yFields` initialised (Y.Text / Y.Map / Y.Array as declared).
+     *
+     * If the record exists, the stored Yjs update is applied to the returned doc.
+     */
+    getYDoc(id: string): Promise<Y.Doc>;
+    /**
+     * Persist a Y.Doc by encoding its state as a Yjs update and storing it
+     * as the encrypted envelope payload.
+     */
+    putYDoc(id: string, doc: Y.Doc): Promise<void>;
+    /**
+     * Merge a Yjs update into an existing record.
+     * Reads the current doc, applies the update, then persists the merged state.
+     */
+    applyUpdate(id: string, update: Uint8Array): Promise<void>;
+    /**
+     * Delete the record.
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Check whether a record exists.
+     */
+    has(id: string): Promise<boolean>;
+    private initFields;
+}
+/**
+ * Create a `YjsCollection` for a compartment.
+ *
+ * @param compartment  An opened NOYDB compartment.
+ * @param name         Collection name (must not start with `_`).
+ * @param opts         Field descriptors (`yFields`) and optional collection settings.
+ *
+ * @example
+ * ```ts
+ * import { yjsCollection, yText } from '@noy-db/yjs'
+ *
+ * const notes = yjsCollection(comp, 'notes', {
+ *   yFields: { body: yText() },
+ * })
+ *
+ * const doc = await notes.getYDoc('note-1')
+ * doc.getText('body').insert(0, 'Hello world')
+ * await notes.putYDoc('note-1', doc)
+ * ```
+ */
+declare function yjsCollection<YF extends Record<string, YFieldDescriptor>>(compartment: Compartment, name: string, opts: YjsCollectionOptions<YF>): YjsCollection<YF>;
+
+export { type YArrayDescriptor, type YFieldDescriptor, type YMapDescriptor, type YTextDescriptor, YjsCollection, type YjsCollectionOptions, type YjsSnapshot, yArray, yMap, yText, yjsCollection };

package/dist/index.js

@@ -0,0 +1,116 @@
+// src/yjs-collection.ts
+import * as Y from "yjs";
+var YjsCollection = class {
+  /** @internal — use `yjsCollection()` factory instead. */
+  constructor(compartment, name, opts) {
+    this.compartment = compartment;
+    this.name = name;
+    this.yFields = opts.yFields;
+    this.coll = compartment.collection(name, { crdt: "yjs" });
+  }
+  compartment;
+  name;
+  coll;
+  yFields;
+  /**
+   * Get the Y.Doc for a record.
+   *
+   * If the record does not exist, returns a fresh empty Y.Doc with the declared
+   * `yFields` initialised (Y.Text / Y.Map / Y.Array as declared).
+   *
+   * If the record exists, the stored Yjs update is applied to the returned doc.
+   */
+  async getYDoc(id) {
+    const doc = new Y.Doc();
+    this.initFields(doc);
+    const base64Update = await this.coll.get(id);
+    if (base64Update) {
+      const bytes = base64ToUint8Array(base64Update);
+      Y.applyUpdate(doc, bytes);
+    }
+    return doc;
+  }
+  /**
+   * Persist a Y.Doc by encoding its state as a Yjs update and storing it
+   * as the encrypted envelope payload.
+   */
+  async putYDoc(id, doc) {
+    const update = Y.encodeStateAsUpdate(doc);
+    const base64 = uint8ArrayToBase64(update);
+    await this.coll.put(id, base64);
+  }
+  /**
+   * Merge a Yjs update into an existing record.
+   * Reads the current doc, applies the update, then persists the merged state.
+   */
+  async applyUpdate(id, update) {
+    const doc = await this.getYDoc(id);
+    Y.applyUpdate(doc, update);
+    await this.putYDoc(id, doc);
+  }
+  /**
+   * Delete the record.
+   */
+  async delete(id) {
+    await this.coll.delete(id);
+  }
+  /**
+   * Check whether a record exists.
+   */
+  async has(id) {
+    return await this.coll.get(id) !== null;
+  }
+  // ─── Private ────────────────────────────────────────────────────────
+  initFields(doc) {
+    for (const [fieldName, descriptor] of Object.entries(this.yFields)) {
+      switch (descriptor._yjsType) {
+        case "Y.Text":
+          doc.getText(fieldName);
+          break;
+        case "Y.Map":
+          doc.getMap(fieldName);
+          break;
+        case "Y.Array":
+          doc.getArray(fieldName);
+          break;
+      }
+    }
+  }
+};
+function uint8ArrayToBase64(bytes) {
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}
+function base64ToUint8Array(base64) {
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+function yjsCollection(compartment, name, opts) {
+  return new YjsCollection(compartment, name, opts);
+}
+
+// src/descriptors.ts
+function yText() {
+  return { _yjsType: "Y.Text" };
+}
+function yMap() {
+  return { _yjsType: "Y.Map" };
+}
+function yArray() {
+  return { _yjsType: "Y.Array" };
+}
+export {
+  YjsCollection,
+  yArray,
+  yMap,
+  yText,
+  yjsCollection
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/yjs-collection.ts","../src/descriptors.ts"],"sourcesContent":["/**\n * YjsCollection — wraps a noy-db Collection<string> (crdt: 'yjs') with\n * Y.Doc-aware `getYDoc` and `putYDoc` methods.\n *\n * The encrypted envelope stores base64(Y.encodeStateAsUpdate(ydoc)) in `_data`.\n * `collection.get(id)` returns this raw base64 string. `getYDoc(id)` decodes\n * it into a Y.Doc and applies any `yFields` initialisation.\n *\n * v0.9 #136\n */\n\nimport * as Y from 'yjs'\nimport type { Compartment } from '@noy-db/core'\nimport type { YFieldDescriptor } from './descriptors.js'\n\n/** A resolved snapshot of a Yjs-backed record. Field values depend on yFields descriptors. */\nexport type YjsSnapshot<YF extends Record<string, YFieldDescriptor>> = {\n  [K in keyof YF]: YF[K] extends { _yjsType: 'Y.Text' }\n    ? Y.Text\n    : YF[K] extends { _yjsType: 'Y.Map' }\n      ? Y.Map<unknown>\n      : Y.Array<unknown>\n}\n\n/** Options for creating a YjsCollection. */\nexport interface YjsCollectionOptions<YF extends Record<string, YFieldDescriptor>> {\n  /** The field descriptors — tells YjsCollection which Y.* types to initialise. */\n  yFields: YF\n}\n\n/**\n * A YjsCollection wraps a noy-db `crdt: 'yjs'` collection and exposes\n * `getYDoc(id)` and `putYDoc(id, ydoc)` instead of the raw `get`/`put` API.\n *\n * Construct via `yjsCollection(compartment, name, opts)`.\n */\nexport class YjsCollection<YF extends Record<string, YFieldDescriptor>> {\n  private readonly coll: ReturnType<Compartment['collection']>\n  private readonly yFields: YF\n\n  /** @internal — use `yjsCollection()` factory instead. */\n  constructor(\n    private readonly compartment: Compartment,\n    private readonly name: string,\n    opts: YjsCollectionOptions<YF>,\n  ) {\n    this.yFields = opts.yFields\n    // Collection<string> with crdt: 'yjs' — T = string (the base64 update blob)\n    this.coll = compartment.collection<string>(name, { crdt: 'yjs' })\n  }\n\n  /**\n   * Get the Y.Doc for a record.\n   *\n   * If the record does not exist, returns a fresh empty Y.Doc with the declared\n   * `yFields` initialised (Y.Text / Y.Map / Y.Array as declared).\n   *\n   * If the record exists, the stored Yjs update is applied to the returned doc.\n   */\n  async getYDoc(id: string): Promise<Y.Doc> {\n    const doc = new Y.Doc()\n    this.initFields(doc)\n\n    const base64Update = await this.coll.get(id) as string | null\n    if (base64Update) {\n      const bytes = base64ToUint8Array(base64Update)\n      Y.applyUpdate(doc, bytes)\n    }\n\n    return doc\n  }\n\n  /**\n   * Persist a Y.Doc by encoding its state as a Yjs update and storing it\n   * as the encrypted envelope payload.\n   */\n  async putYDoc(id: string, doc: Y.Doc): Promise<void> {\n    const update = Y.encodeStateAsUpdate(doc)\n    const base64 = uint8ArrayToBase64(update)\n    await this.coll.put(id, base64)\n  }\n\n  /**\n   * Merge a Yjs update into an existing record.\n   * Reads the current doc, applies the update, then persists the merged state.\n   */\n  async applyUpdate(id: string, update: Uint8Array): Promise<void> {\n    const doc = await this.getYDoc(id)\n    Y.applyUpdate(doc, update)\n    await this.putYDoc(id, doc)\n  }\n\n  /**\n   * Delete the record.\n   */\n  async delete(id: string): Promise<void> {\n    await this.coll.delete(id)\n  }\n\n  /**\n   * Check whether a record exists.\n   */\n  async has(id: string): Promise<boolean> {\n    return (await this.coll.get(id)) !== null\n  }\n\n  // ─── Private ────────────────────────────────────────────────────────\n\n  private initFields(doc: Y.Doc): void {\n    for (const [fieldName, descriptor] of Object.entries(this.yFields)) {\n      switch (descriptor._yjsType) {\n        case 'Y.Text':\n          doc.getText(fieldName)\n          break\n        case 'Y.Map':\n          doc.getMap(fieldName)\n          break\n        case 'Y.Array':\n          doc.getArray(fieldName)\n          break\n      }\n    }\n  }\n}\n\n// ─── Base64 helpers ───────────────────────────────────────────────────────────\n\nfunction uint8ArrayToBase64(bytes: Uint8Array): string {\n  let binary = ''\n  for (let i = 0; i < bytes.length; i++) {\n    binary += String.fromCharCode(bytes[i]!)\n  }\n  return btoa(binary)\n}\n\nfunction base64ToUint8Array(base64: string): Uint8Array {\n  const binary = atob(base64)\n  const bytes = new Uint8Array(binary.length)\n  for (let i = 0; i < binary.length; i++) {\n    bytes[i] = binary.charCodeAt(i)\n  }\n  return bytes\n}\n\n// ─── Factory function ─────────────────────────────────────────────────────────\n\n/**\n * Create a `YjsCollection` for a compartment.\n *\n * @param compartment  An opened NOYDB compartment.\n * @param name         Collection name (must not start with `_`).\n * @param opts         Field descriptors (`yFields`) and optional collection settings.\n *\n * @example\n * ```ts\n * import { yjsCollection, yText } from '@noy-db/yjs'\n *\n * const notes = yjsCollection(comp, 'notes', {\n *   yFields: { body: yText() },\n * })\n *\n * const doc = await notes.getYDoc('note-1')\n * doc.getText('body').insert(0, 'Hello world')\n * await notes.putYDoc('note-1', doc)\n * ```\n */\nexport function yjsCollection<YF extends Record<string, YFieldDescriptor>>(\n  compartment: Compartment,\n  name: string,\n  opts: YjsCollectionOptions<YF>,\n): YjsCollection<YF> {\n  return new YjsCollection(compartment, name, opts)\n}\n","/**\n * Field descriptors for Yjs-backed fields in @noy-db/yjs.\n * Mirrors the dictKey / i18nText descriptor pattern from @noy-db/core.\n */\n\n/** Descriptor for a Y.Text field (rich text, TipTap/ProseMirror compatible). */\nexport interface YTextDescriptor {\n  readonly _yjsType: 'Y.Text'\n}\n\n/** Descriptor for a Y.Map<string> field. */\nexport interface YMapDescriptor {\n  readonly _yjsType: 'Y.Map'\n}\n\n/** Descriptor for a Y.Array field. */\nexport interface YArrayDescriptor {\n  readonly _yjsType: 'Y.Array'\n}\n\nexport type YFieldDescriptor = YTextDescriptor | YMapDescriptor | YArrayDescriptor\n\n/** Declare a Y.Text field (rich text). */\nexport function yText(): YTextDescriptor {\n  return { _yjsType: 'Y.Text' }\n}\n\n/** Declare a Y.Map field. */\nexport function yMap(): YMapDescriptor {\n  return { _yjsType: 'Y.Map' }\n}\n\n/** Declare a Y.Array field. */\nexport function yArray(): YArrayDescriptor {\n  return { _yjsType: 'Y.Array' }\n}\n"],"mappings":";AAWA,YAAY,OAAO;AAyBZ,IAAM,gBAAN,MAAiE;AAAA;AAAA,EAKtE,YACmB,aACA,MACjB,MACA;AAHiB;AACA;AAGjB,SAAK,UAAU,KAAK;AAEpB,SAAK,OAAO,YAAY,WAAmB,MAAM,EAAE,MAAM,MAAM,CAAC;AAAA,EAClE;AAAA,EAPmB;AAAA,EACA;AAAA,EANF;AAAA,EACA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAqBjB,MAAM,QAAQ,IAA4B;AACxC,UAAM,MAAM,IAAM,MAAI;AACtB,SAAK,WAAW,GAAG;AAEnB,UAAM,eAAe,MAAM,KAAK,KAAK,IAAI,EAAE;AAC3C,QAAI,cAAc;AAChB,YAAM,QAAQ,mBAAmB,YAAY;AAC7C,MAAE,cAAY,KAAK,KAAK;AAAA,IAC1B;AAEA,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,MAAM,QAAQ,IAAY,KAA2B;AACnD,UAAM,SAAW,sBAAoB,GAAG;AACxC,UAAM,SAAS,mBAAmB,MAAM;AACxC,UAAM,KAAK,KAAK,IAAI,IAAI,MAAM;AAAA,EAChC;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,MAAM,YAAY,IAAY,QAAmC;AAC/D,UAAM,MAAM,MAAM,KAAK,QAAQ,EAAE;AACjC,IAAE,cAAY,KAAK,MAAM;AACzB,UAAM,KAAK,QAAQ,IAAI,GAAG;AAAA,EAC5B;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,OAAO,IAA2B;AACtC,UAAM,KAAK,KAAK,OAAO,EAAE;AAAA,EAC3B;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,IAAI,IAA8B;AACtC,WAAQ,MAAM,KAAK,KAAK,IAAI,EAAE,MAAO;AAAA,EACvC;AAAA;AAAA,EAIQ,WAAW,KAAkB;AACnC,eAAW,CAAC,WAAW,UAAU,KAAK,OAAO,QAAQ,KAAK,OAAO,GAAG;AAClE,cAAQ,WAAW,UAAU;AAAA,QAC3B,KAAK;AACH,cAAI,QAAQ,SAAS;AACrB;AAAA,QACF,KAAK;AACH,cAAI,OAAO,SAAS;AACpB;AAAA,QACF,KAAK;AACH,cAAI,SAAS,SAAS;AACtB;AAAA,MACJ;AAAA,IACF;AAAA,EACF;AACF;AAIA,SAAS,mBAAmB,OAA2B;AACrD,MAAI,SAAS;AACb,WAAS,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK;AACrC,cAAU,OAAO,aAAa,MAAM,CAAC,CAAE;AAAA,EACzC;AACA,SAAO,KAAK,MAAM;AACpB;AAEA,SAAS,mBAAmB,QAA4B;AACtD,QAAM,SAAS,KAAK,MAAM;AAC1B,QAAM,QAAQ,IAAI,WAAW,OAAO,MAAM;AAC1C,WAAS,IAAI,GAAG,IAAI,OAAO,QAAQ,KAAK;AACtC,UAAM,CAAC,IAAI,OAAO,WAAW,CAAC;AAAA,EAChC;AACA,SAAO;AACT;AAwBO,SAAS,cACd,aACA,MACA,MACmB;AACnB,SAAO,IAAI,cAAc,aAAa,MAAM,IAAI;AAClD;;;ACrJO,SAAS,QAAyB;AACvC,SAAO,EAAE,UAAU,SAAS;AAC9B;AAGO,SAAS,OAAuB;AACrC,SAAO,EAAE,UAAU,QAAQ;AAC7B;AAGO,SAAS,SAA2B;AACzC,SAAO,EAAE,UAAU,UAAU;AAC/B;","names":[]}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@noy-db/yjs",
+  "version": "0.9.0",
+  "description": "Yjs Y.Doc interop for noy-db — collaborative rich-text fields with encrypted-at-rest Yjs state",
+  "license": "MIT",
+  "author": "vLannaAi <vicio@lanna.ai>",
+  "homepage": "https://github.com/vLannaAi/noy-db/tree/main/packages/yjs#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vLannaAi/noy-db.git",
+    "directory": "packages/yjs"
+  },
+  "bugs": {
+    "url": "https://github.com/vLannaAi/noy-db/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "yjs": ">=13.0.0",
+    "@noy-db/core": "0.9.0"
+  },
+  "devDependencies": {
+    "yjs": "^13.6.27",
+    "@noy-db/core": "0.9.0"
+  },
+  "keywords": [
+    "noy-db",
+    "yjs",
+    "crdt",
+    "collaborative",
+    "rich-text",
+    "encryption",
+    "offline-first"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit"
+  }
+}