@pluv/crdt-yjs 0.11.1 → 0.12.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @pluv/crdt-yjs@0.11.1 build /home/runner/work/pluv/pluv/packages/crdt-yjs
+> @pluv/crdt-yjs@0.12.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
-CJS dist/index.js 4.87 KB
-CJS ⚡️ Build success in 81ms
-ESM dist/index.mjs 3.68 KB
-ESM ⚡️ Build success in 81ms
+ESM dist/index.mjs 4.70 KB
+ESM ⚡️ Build success in 68ms
+CJS dist/index.js 5.88 KB
+CJS ⚡️ Build success in 68ms
 DTS Build start
-DTS ⚡️ Build success in 1101ms
-DTS dist/index.d.mts 3.11 KB
-DTS dist/index.d.ts  3.11 KB
+DTS ⚡️ Build success in 1225ms
+DTS dist/index.d.mts 3.41 KB
+DTS dist/index.d.ts  3.41 KB

package/CHANGELOG.md

@@ -1,5 +1,249 @@
 # @pluv/crdt-yjs
 
+## 0.12.0
+
+### Minor Changes
+
+- 436040b: Added ability to undo and redo changes to storage.
+
+  ## @pluv/crdt-yjs
+
+  `@pluv/crdt-yjs` now exposes 5 new methods: `canRedo`, `canUndo`, `redo`, `undo` and `trackOrigins`.
+
+  Refer to the code-example below to better understand how to undo and redo with your doc.
+
+  ```ts
+  // Example
+  import { array, doc } from "@pluv/crdt-yjs";
+
+  // Create your doc with your shared-types
+  const myDoc = doc({
+    messages: array<string>([]),
+  });
+
+  /**
+   * @description Track origins to enable undos and redos for your document.
+   * trackOrigins must be called before any storage mutations, to enable those
+   * mutations to be undone/redone.
+   */
+  myDoc.trackOrigins({
+    /**
+     * @description This is the same `captureTimeout` option from yjs's UndoManager.
+     * This specifies a number in ms, during which edits are merged together to be
+     * undone together. Set this to 0, to track each transacted change individually.
+     * @see (@link https://docs.yjs.dev/api/undo-manager)
+     * @default 500
+     */
+    captureTimeout: 500,
+    /**
+     * @desription This is the same `trackedOrigins` option from yjs's UndoManager.
+     * This specifies transaction origins (strings only) to filter which transactions
+     * can be undone.
+     * @see (@link https://docs.yjs.dev/api/undo-manager)
+     * @default undefined
+     */
+    trackedOrigins: ["user-123"],
+  });
+
+  /**
+   * @description Check whether calling undo will mutate storage
+   * @returns boolean
+   */
+  myDoc.canUndo();
+  /**
+   * @description Check whether calling redo will mutate storage
+   * @returns boolean
+   */
+  myDoc.canRedo();
+
+  // Perform a storage mutation within a transaction so that it can be affected
+  // by undo/redo operations.
+  myDoc.transact(() => {
+    myDoc.get("messages").push(["hello world!"]);
+  }, "user-123");
+
+  /**
+   * @description Undoes the last valid mutation to storage
+   */
+  myDoc.undo();
+
+  /**
+   * @description Re-applies the last undone mutation to storage
+   */
+  myDoc.redo();
+  ```
+
+  ## @pluv/client
+
+  `@pluv/client`'s `PluvRoom` and `MockedRoom` now exposes 5 new methods: `canRedo`, `canUndo`, `redo`, `undo` and `transact`.
+
+  Refer to the code-example below to better understand how to undo and redo with your `PluvRoom`.
+
+  ```ts
+  import { createClient, y } from "@pluv/client";
+
+  const client = createClient({});
+
+  /**
+   * @description When a room is created, undo/redo will automatically
+   * be configured to filter for changes made by the connected user
+   * (so that users only undo/redo their changes).
+   */
+  const room = client.createRoom("my-room", {
+    initialStorage: () => ({
+      messages: y.array<string>([]),
+    }),
+    /**
+     * @description This is the same `captureTimeout` option from yjs's UndoManager.
+     * This specifies a number in ms, during which edits are merged together to be
+     * undone together. Set this to 0, to track each transacted change individually.
+     * @see (@link https://docs.yjs.dev/api/undo-manager)
+     * @default 500
+     */
+    captureTimeout: 500,
+    /**
+     * @desription This is the same `trackedOrigins` option from yjs's UndoManager.
+     * This specifies transaction origins (strings only) to filter which transactions
+     * can be undone.
+     * When omitted, the user's connection id will be tracked. When provided,
+     * specifies additional tracked origins besides the user's connection id.
+     * @see (@link https://docs.yjs.dev/api/undo-manager)
+     * @default undefined
+     */
+    trackedOrigins: ["user-123"],
+  });
+
+  /**
+   * @description Check whether calling undo will mutate storage
+   * @returns boolean
+   */
+  room.canUndo();
+  /**
+   * @description Check whether calling redo will mutate storage
+   * @returns boolean
+   */
+  room.canRedo();
+
+  /**
+   * @description Calling transact will enable a storage mutation to be undone/redone.
+   * When called without an origin, the origin will default to the user's connection
+   * id.
+   *
+   * You can specify a 2nd parameter to transact with a different transaction origin.
+   */
+  room.transact(() => {
+    room.get("messages").push(["hello world!"]);
+  });
+
+  // This will also be undoable because `"user-123"` is a tracked origin.
+  room.transact(() => {
+    room.get("messages").push(["hello world!"]);
+  }, "user-123");
+
+  /**
+   * @description Undoes the last valid mutation to storage
+   */
+  room.undo();
+
+  /**
+   * @description Re-applies the last undone mutation to storage
+   */
+  room.redo();
+  ```
+
+  ## @pluv/react
+
+  `@pluv/react`'s `createRoomBundle` now exposes 5 new react hooks: `usePluvCanRedo`, `usePluvCanUndo`, `usePluvRedo`, `usePluvUndo` and `usePluvTransact`.
+
+  Refer to the code-example below to better understand how to undo and redo with your `createRoomBundle`.
+
+  ```tsx
+  import { createBundle, createClient, y } from "@pluv/react";
+  import { type io } from "./io";
+
+  const client = createClient<typeof io>();
+
+  const { createRoomBundle } = createBundle(client);
+
+  const {
+    usePluvCanRedo,
+    usePluvCanUndo,
+    usePluvRedo,
+    usePluvStorage,
+    usePluvTransact,
+    usePluvUndo,
+  } = createRoomBundle({
+    initialStorage: () => ({
+      messages: y.array<string>([]),
+    }),
+    /**
+     * @description This is the same `captureTimeout` option from yjs's UndoManager.
+     * This specifies a number in ms, during which edits are merged together to be
+     * undone together. Set this to 0, to track each transacted change individually.
+     * @see (@link https://docs.yjs.dev/api/undo-manager)
+     * @default 500
+     */
+    captureTimeout: 500,
+    /**
+     * @desription This is the same `trackedOrigins` option from yjs's UndoManager.
+     * This specifies transaction origins (strings only) to filter which transactions
+     * can be undone.
+     * When omitted, the user's connection id will be tracked. When provided,
+     * specifies additional tracked origins besides the user's connection id.
+     * @see (@link https://docs.yjs.dev/api/undo-manager)
+     * @default undefined
+     */
+    trackedOrigins: ["user-123"],
+  });
+
+  /**
+   * @description Check whether calling undo will mutate storage
+   */
+  const canUndo: boolean = usePluvCanUndo();
+  /**
+   * @description Check whether calling redo will mutate storage
+   */
+  const canRedo: boolean = usePluvCanRedo();
+
+  const [messages, sharedType] = usePluvStorage("messages");
+
+  /**
+   * @description Calling transact will enable a storage mutation to be undone/redone.
+   * When called without an origin, the origin will default to the user's connection
+   * id.
+   *
+   * You can specify a 2nd parameter to transact with a different transaction origin.
+   */
+  const transact = usePluvTransact();
+
+  transact(() => {
+    sharedType?.push(["hello world!"]);
+  });
+
+  // This will also be undoable because `"user-123"` is a tracked origin.
+  transact(() => {
+    sharedType?.push(["hello world!"]);
+  }, "user-123");
+
+  /**
+   * @description Undoes the last valid mutation to storage
+   */
+  const undo = usePluvUndo();
+
+  undo();
+
+  /**
+   * @description Re-applies the last undone mutation to storage
+   */
+  const redo = usePluvRedo();
+
+  redo();
+  ```
+
+### Patch Changes
+
+- @pluv/types@0.12.0
+
 ## 0.11.1
 
 ### Patch Changes

package/dist/index.d.mts

@@ -20,20 +20,31 @@ type InferYjsSharedTypeJson<TShared extends unknown> = TShared extends AbstractT
     [P in keyof IObject]: InferYjsSharedTypeJson<IObject[P]>;
 } : TShared extends Map<infer IItem> ? Record<string, InferYjsSharedTypeJson<IItem>> : TShared extends Text | XmlElement | XmlFragment | XmlText ? string : never : TShared;
 
+interface TrackOriginOptions {
+    captureTimeout?: number;
+    trackedOrigins?: readonly string[];
+}
 declare class YjsDoc<T extends Record<string, AbstractType<any>> = {}> {
     value: Doc;
+    private _undoManager;
+    get storage(): T;
     private get _storage();
     constructor(value?: T);
     applyUpdate(update?: string | Uint8Array | null, origin?: string): this;
+    canRedo(): boolean;
+    canUndo(): boolean;
     destroy(): void;
     encodeStateAsUpdate(): string;
     get<TKey extends keyof T>(key: TKey): T[TKey];
     getSharedTypes(): T;
+    redo(): void;
     subscribe(fn: (update: string, origin: any, doc: Doc, transaction: Transaction) => void): () => void;
     toJSON(): InferYjsDocJson<this>;
+    trackOrigins(options: TrackOriginOptions): void;
     transact(fn: (transaction: Transaction) => void, origin?: any): void;
     static fromUint8Array(u8a: Uint8Array): string;
     static toUint8Array(str: string): Uint8Array;
+    undo(): void;
 }
 declare const doc: <T extends Record<string, AbstractType<any>> = {}>(value?: T | undefined) => YjsDoc<T>;
 
@@ -53,4 +64,4 @@ declare const xmlFragment: (params?: XmlFragmentParams) => XmlFragment;
 
 declare const xmlText: (value?: string) => XmlText;
 
-export { InferYjsDocJson, InferYjsDocSharedType, InferYjsDocSharedTypeJson, InferYjsDocSharedTypes, InferYjsSharedTypeJson, XmlElementParams, XmlFragmentParams, YObject, YObjectValue, YjsDoc, array, doc, map, object, text, xmlElement, xmlFragment, xmlText };
+export { InferYjsDocJson, InferYjsDocSharedType, InferYjsDocSharedTypeJson, InferYjsDocSharedTypes, InferYjsSharedTypeJson, TrackOriginOptions, XmlElementParams, XmlFragmentParams, YObject, YObjectValue, YjsDoc, array, doc, map, object, text, xmlElement, xmlFragment, xmlText };

package/dist/index.d.ts

@@ -20,20 +20,31 @@ type InferYjsSharedTypeJson<TShared extends unknown> = TShared extends AbstractT
     [P in keyof IObject]: InferYjsSharedTypeJson<IObject[P]>;
 } : TShared extends Map<infer IItem> ? Record<string, InferYjsSharedTypeJson<IItem>> : TShared extends Text | XmlElement | XmlFragment | XmlText ? string : never : TShared;
 
+interface TrackOriginOptions {
+    captureTimeout?: number;
+    trackedOrigins?: readonly string[];
+}
 declare class YjsDoc<T extends Record<string, AbstractType<any>> = {}> {
     value: Doc;
+    private _undoManager;
+    get storage(): T;
     private get _storage();
     constructor(value?: T);
     applyUpdate(update?: string | Uint8Array | null, origin?: string): this;
+    canRedo(): boolean;
+    canUndo(): boolean;
     destroy(): void;
     encodeStateAsUpdate(): string;
     get<TKey extends keyof T>(key: TKey): T[TKey];
     getSharedTypes(): T;
+    redo(): void;
     subscribe(fn: (update: string, origin: any, doc: Doc, transaction: Transaction) => void): () => void;
     toJSON(): InferYjsDocJson<this>;
+    trackOrigins(options: TrackOriginOptions): void;
     transact(fn: (transaction: Transaction) => void, origin?: any): void;
     static fromUint8Array(u8a: Uint8Array): string;
     static toUint8Array(str: string): Uint8Array;
+    undo(): void;
 }
 declare const doc: <T extends Record<string, AbstractType<any>> = {}>(value?: T | undefined) => YjsDoc<T>;
 
@@ -53,4 +64,4 @@ declare const xmlFragment: (params?: XmlFragmentParams) => XmlFragment;
 
 declare const xmlText: (value?: string) => XmlText;
 
-export { InferYjsDocJson, InferYjsDocSharedType, InferYjsDocSharedTypeJson, InferYjsDocSharedTypes, InferYjsSharedTypeJson, XmlElementParams, XmlFragmentParams, YObject, YObjectValue, YjsDoc, array, doc, map, object, text, xmlElement, xmlFragment, xmlText };
+export { InferYjsDocJson, InferYjsDocSharedType, InferYjsDocSharedTypeJson, InferYjsDocSharedTypes, InferYjsSharedTypeJson, TrackOriginOptions, XmlElementParams, XmlFragmentParams, YObject, YObjectValue, YjsDoc, array, doc, map, object, text, xmlElement, xmlFragment, xmlText };

package/dist/index.js

@@ -63,6 +63,7 @@ var import_yjs2 = require("yjs");
 var YjsDoc = class _YjsDoc {
   constructor(value) {
     this.value = new import_yjs2.Doc();
+    this._undoManager = null;
     if (!value)
       return;
     const storage = this.value.getMap("storage");
@@ -70,6 +71,14 @@ var YjsDoc = class _YjsDoc {
       storage.set(key, node);
     });
   }
+  get storage() {
+    const storage = this._storage;
+    const keys = Array.from(storage.keys());
+    return keys.reduce(
+      (acc, key) => __spreadProps(__spreadValues({}, acc), { [key]: storage.get(key) }),
+      {}
+    );
+  }
   get _storage() {
     return this.value.getMap("storage");
   }
@@ -80,7 +89,17 @@ var YjsDoc = class _YjsDoc {
     (0, import_yjs2.applyUpdate)(this.value, uint8Update, origin);
     return this;
   }
+  canRedo() {
+    var _a;
+    return !!((_a = this._undoManager) == null ? void 0 : _a.canRedo());
+  }
+  canUndo() {
+    var _a;
+    return !!((_a = this._undoManager) == null ? void 0 : _a.canUndo());
+  }
   destroy() {
+    var _a;
+    (_a = this._undoManager) == null ? void 0 : _a.destroy();
     this.value.destroy();
   }
   encodeStateAsUpdate() {
@@ -95,6 +114,10 @@ var YjsDoc = class _YjsDoc {
       {}
     );
   }
+  redo() {
+    var _a;
+    (_a = this._undoManager) == null ? void 0 : _a.redo();
+  }
   subscribe(fn) {
     const _fn = (update, origin, doc2, transaction) => fn(_YjsDoc.fromUint8Array(update), origin, doc2, transaction);
     this.value.on("update", _fn);
@@ -105,6 +128,16 @@ var YjsDoc = class _YjsDoc {
   toJSON() {
     return this._storage.toJSON();
   }
+  trackOrigins(options) {
+    const { captureTimeout, trackedOrigins } = options;
+    if (this._undoManager) {
+      this._undoManager.destroy();
+    }
+    this._undoManager = new import_yjs2.UndoManager(this._storage, {
+      captureTimeout,
+      trackedOrigins: trackedOrigins ? new Set(trackedOrigins) : void 0
+    });
+  }
   transact(fn, origin) {
     this.value.transact((tx) => {
       fn(tx);
@@ -116,6 +149,10 @@ var YjsDoc = class _YjsDoc {
   static toUint8Array(str) {
     return (0, import_js_base64.toUint8Array)(str);
   }
+  undo() {
+    var _a;
+    (_a = this._undoManager) == null ? void 0 : _a.undo();
+  }
 };
 var doc = (value) => {
   return new YjsDoc(value);

package/dist/index.mjs

@@ -29,6 +29,7 @@ var array = (value = []) => {
 // src/doc.ts
 import { fromUint8Array, toUint8Array } from "js-base64";
 import {
+  UndoManager,
   Doc as YDoc,
   applyUpdate,
   encodeStateAsUpdate
@@ -36,6 +37,7 @@ import {
 var YjsDoc = class _YjsDoc {
   constructor(value) {
     this.value = new YDoc();
+    this._undoManager = null;
     if (!value)
       return;
     const storage = this.value.getMap("storage");
@@ -43,6 +45,14 @@ var YjsDoc = class _YjsDoc {
       storage.set(key, node);
     });
   }
+  get storage() {
+    const storage = this._storage;
+    const keys = Array.from(storage.keys());
+    return keys.reduce(
+      (acc, key) => __spreadProps(__spreadValues({}, acc), { [key]: storage.get(key) }),
+      {}
+    );
+  }
   get _storage() {
     return this.value.getMap("storage");
   }
@@ -53,7 +63,17 @@ var YjsDoc = class _YjsDoc {
     applyUpdate(this.value, uint8Update, origin);
     return this;
   }
+  canRedo() {
+    var _a;
+    return !!((_a = this._undoManager) == null ? void 0 : _a.canRedo());
+  }
+  canUndo() {
+    var _a;
+    return !!((_a = this._undoManager) == null ? void 0 : _a.canUndo());
+  }
   destroy() {
+    var _a;
+    (_a = this._undoManager) == null ? void 0 : _a.destroy();
     this.value.destroy();
   }
   encodeStateAsUpdate() {
@@ -68,6 +88,10 @@ var YjsDoc = class _YjsDoc {
       {}
     );
   }
+  redo() {
+    var _a;
+    (_a = this._undoManager) == null ? void 0 : _a.redo();
+  }
   subscribe(fn) {
     const _fn = (update, origin, doc2, transaction) => fn(_YjsDoc.fromUint8Array(update), origin, doc2, transaction);
     this.value.on("update", _fn);
@@ -78,6 +102,16 @@ var YjsDoc = class _YjsDoc {
   toJSON() {
     return this._storage.toJSON();
   }
+  trackOrigins(options) {
+    const { captureTimeout, trackedOrigins } = options;
+    if (this._undoManager) {
+      this._undoManager.destroy();
+    }
+    this._undoManager = new UndoManager(this._storage, {
+      captureTimeout,
+      trackedOrigins: trackedOrigins ? new Set(trackedOrigins) : void 0
+    });
+  }
   transact(fn, origin) {
     this.value.transact((tx) => {
       fn(tx);
@@ -89,6 +123,10 @@ var YjsDoc = class _YjsDoc {
   static toUint8Array(str) {
     return toUint8Array(str);
   }
+  undo() {
+    var _a;
+    (_a = this._undoManager) == null ? void 0 : _a.undo();
+  }
 };
 var doc = (value) => {
   return new YjsDoc(value);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pluv/crdt-yjs",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "yjs for @pluv/io",
   "author": "leedavidcs",
   "license": "MIT",
@@ -18,18 +18,18 @@
   },
   "dependencies": {
     "js-base64": "^3.7.5",
-    "@pluv/types": "^0.11.1"
+    "@pluv/types": "^0.12.0"
   },
   "peerDependencies": {
     "yjs": "^13.0.0"
   },
   "devDependencies": {
-    "eslint": "^8.49.0",
+    "eslint": "^8.50.0",
     "tsup": "^7.2.0",
     "typescript": "^5.2.2",
-    "yjs": "^13.6.7",
-    "@pluv/tsconfig": "^0.11.1",
-    "eslint-config-pluv": "^0.11.1"
+    "yjs": "^13.6.8",
+    "@pluv/tsconfig": "^0.12.0",
+    "eslint-config-pluv": "^0.12.0"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --dts",

package/src/doc.ts

@@ -2,6 +2,7 @@ import { fromUint8Array, toUint8Array } from "js-base64";
 import {
     AbstractType,
     Transaction,
+    UndoManager,
     Doc as YDoc,
     Map as YMap,
     applyUpdate,
@@ -9,8 +10,25 @@ import {
 } from "yjs";
 import type { InferYjsDocJson } from "./types";
 
+export interface TrackOriginOptions {
+    captureTimeout?: number;
+    trackedOrigins?: readonly string[];
+}
+
 export class YjsDoc<T extends Record<string, AbstractType<any>> = {}> {
     public value: YDoc = new YDoc();
+    private _undoManager: UndoManager | null = null;
+
+    public get storage(): T {
+        const storage = this._storage;
+
+        const keys = Array.from(storage.keys());
+
+        return keys.reduce<T>(
+            (acc, key) => ({ ...acc, [key]: storage.get(key) }),
+            {} as T,
+        );
+    }
 
     private get _storage(): YMap<any> {
         return this.value.getMap("storage");
@@ -40,7 +58,16 @@ export class YjsDoc<T extends Record<string, AbstractType<any>> = {}> {
         return this;
     }
 
+    public canRedo(): boolean {
+        return !!this._undoManager?.canRedo();
+    }
+
+    public canUndo(): boolean {
+        return !!this._undoManager?.canUndo();
+    }
+
     public destroy(): void {
+        this._undoManager?.destroy();
         this.value.destroy();
     }
 
@@ -59,6 +86,10 @@ export class YjsDoc<T extends Record<string, AbstractType<any>> = {}> {
         );
     }
 
+    public redo(): void {
+        this._undoManager?.redo();
+    }
+
     public subscribe(
         fn: (
             update: string,
@@ -85,6 +116,21 @@ export class YjsDoc<T extends Record<string, AbstractType<any>> = {}> {
         return this._storage.toJSON() as InferYjsDocJson<this>;
     }
 
+    public trackOrigins(options: TrackOriginOptions): void {
+        const { captureTimeout, trackedOrigins } = options;
+
+        if (this._undoManager) {
+            this._undoManager.destroy();
+        }
+
+        this._undoManager = new UndoManager(this._storage, {
+            captureTimeout,
+            trackedOrigins: trackedOrigins
+                ? new Set<string>(trackedOrigins)
+                : undefined,
+        });
+    }
+
     public transact(
         fn: (transaction: Transaction) => void,
         origin?: any,
@@ -101,6 +147,10 @@ export class YjsDoc<T extends Record<string, AbstractType<any>> = {}> {
     public static toUint8Array(str: string): Uint8Array {
         return toUint8Array(str);
     }
+
+    public undo(): void {
+        this._undoManager?.undo();
+    }
 }
 
 export const doc = <T extends Record<string, AbstractType<any>> = {}>(

package/src/index.ts

@@ -1,5 +1,6 @@
 export type { AbstractType, Array, Map, Text } from "yjs";
 export { array } from "./array";
+export type { TrackOriginOptions } from "./doc";
 export { YjsDoc, doc } from "./doc";
 export { map } from "./map";
 export { object } from "./object";