@yorkie-js/react 0.7.7 → 0.7.8

package/README.md

@@ -8,7 +8,7 @@ To get started using Yorkie React SDK, see: https://yorkie.dev/docs/getting-star
 
 ## Contributing
 
-See [CONTRIBUTING](CONTRIBUTING.md) for details on submitting patches and the contribution workflow.
+See [CONTRIBUTING](../../CONTRIBUTING.md) for details on submitting patches and the contribution workflow.
 
 ## Contributors ✨
 

package/dist/yorkie-js-react.d.ts

@@ -10,6 +10,7 @@ import { Presence } from '@yorkie-js/sdk';
 import { PropsWithChildren } from 'react';
 import { RevisionSummary } from '@yorkie-js/sdk';
 import { StreamConnectionStatus } from '@yorkie-js/sdk';
+import { SyncMode } from '@yorkie-js/sdk';
 import { Text as Text_2 } from '@yorkie-js/sdk';
 import { Tree } from '@yorkie-js/sdk';
 
@@ -19,12 +20,17 @@ import { Tree } from '@yorkie-js/sdk';
  *
  * @example
  * ```tsx
+ * import { ChannelProvider, SyncMode } from '@yorkie-js/react';
+ *
  * <YorkieProvider apiKey="..." rpcAddr="...">
- *   <ChannelProvider channelKey="room-123" isRealtime={true}>
+ *   <ChannelProvider channelKey="room-123" syncMode={SyncMode.Realtime}>
  *     <ChatRoom />
  *   </ChannelProvider>
  * </YorkieProvider>
  * ```
+ *
+ * The boolean `isRealtime` prop is also accepted as a shortcut for
+ * the Realtime/Manual choice (`true` → Realtime, `false` → Manual).
  */
 export declare const ChannelProvider: React.FC<ChannelProviderProps>;
 
@@ -37,10 +43,24 @@ declare type ChannelProviderProps = PropsWithChildren<{
      */
     channelKey: string;
     /**
-     * `isRealtime` determines the synchronization mode.
-     * - true: Realtime mode (automatic updates via watch stream)
-     * - false: Manual mode (requires manual sync)
-     * @default true
+     * `syncMode` selects how the channel keeps presence in sync with the server.
+     * - `SyncMode.Realtime` (default): open a watch stream and run the
+     *   heartbeat. Required to receive broadcast events.
+     * - `SyncMode.Polling`: heartbeat-only. No watch stream is opened.
+     *   Recommended for large channels where broadcast is not needed.
+     * - `SyncMode.Manual`: no automatic activity.
+     *
+     * If `isRealtime` is also set, `syncMode` wins.
+     */
+    syncMode?: SyncMode;
+    /**
+     * `isRealtime` is a convenience prop covering only Realtime/Manual.
+     * - `true`: equivalent to `syncMode={SyncMode.Realtime}`.
+     * - `false`: equivalent to `syncMode={SyncMode.Manual}`.
+     *
+     * Use `syncMode` directly when you want `SyncMode.Polling`, which this
+     * boolean prop cannot express. When neither prop is set, the channel
+     * falls back to `SyncMode.Realtime`.
      */
     isRealtime?: boolean;
 }>;
@@ -92,6 +112,8 @@ export { RevisionSummary }
  */
 export declare function shallowEqual<T>(valueA: T, valueB: T): boolean;
 
+export { SyncMode }
+
 export { Text_2 as Text }
 
 export { Tree }

package/dist/yorkie-js-react.es.js

@@ -360,7 +360,7 @@ function isScalarZeroValue(type, value) {
   }
 }
 const IMPLICIT$3 = 2;
-const unsafeLocal = Symbol.for("reflect unsafe local");
+const unsafeLocal = /* @__PURE__ */ Symbol.for("reflect unsafe local");
 function unsafeOneofCase(target, oneof) {
   const c = target[oneof.localName].case;
   if (c === void 0) {
@@ -586,7 +586,7 @@ function convertObjectValues(obj, fn) {
   }
   return ret;
 }
-const tokenZeroMessageField = Symbol();
+const tokenZeroMessageField = /* @__PURE__ */ Symbol();
 const messagePrototypes = /* @__PURE__ */ new WeakMap();
 function createZeroMessage(desc) {
   let msg;
@@ -688,7 +688,7 @@ class FieldError extends Error {
 function isFieldError(arg) {
   return arg instanceof Error && errorNames.includes(arg.name) && "field" in arg && typeof arg.field == "function";
 }
-const symbol = Symbol.for("@bufbuild/protobuf/text-encoding");
+const symbol = /* @__PURE__ */ Symbol.for("@bufbuild/protobuf/text-encoding");
 function getTextEncoding() {
   if (globalThis[symbol] == void 0) {
     const te = new globalThis.TextEncoder();
@@ -4056,7 +4056,7 @@ function readScalarField(msg, field, json) {
     msg.set(field, scalarValue);
   }
 }
-const tokenIgnoredUnknownEnum = Symbol();
+const tokenIgnoredUnknownEnum = /* @__PURE__ */ Symbol();
 function readEnum(desc, json, ignoreUnknownFields, nullAsZeroValue) {
   if (json === null) {
     if (desc.typeName == "google.protobuf.NullValue") {
@@ -4082,7 +4082,7 @@ function readEnum(desc, json, ignoreUnknownFields, nullAsZeroValue) {
   }
   throw new Error(`cannot decode ${desc} from JSON: ${formatVal(json)}`);
 }
-const tokenNull = Symbol();
+const tokenNull = /* @__PURE__ */ Symbol();
 function scalarFromJson(field, json, nullAsZeroValue) {
   if (json === null) {
     if (nullAsZeroValue) {
@@ -5903,6 +5903,8 @@ class YorkieError extends Error {
     this.message = message;
     this.toString = () => `[code=${this.code}]: ${this.message}`;
   }
+  code;
+  message;
   name = "YorkieError";
   stack;
 }
@@ -12532,8 +12534,10 @@ class CRDTTree extends CRDTElement {
           break;
         }
         if (next.parent && next.parent === toParent) {
-          collectFromLeft = next;
-          collectFromParent = toParent;
+          if (toLeft !== toParent) {
+            collectFromLeft = next;
+            collectFromParent = toParent;
+          }
           break;
         }
         current = next;
@@ -12596,6 +12600,7 @@ class CRDTTree extends CRDTElement {
       tokensToBeRemoved,
       editedAt
     );
+    const mergeLevel = toBeMergedNodes.length;
     const pairs = [];
     for (const node of nodesToBeRemoved) {
       if (node.remove(editedAt)) {
@@ -12722,7 +12727,15 @@ class CRDTTree extends CRDTElement {
         }
       }
     }
-    return [changes, pairs, diff, nodesToBeRemoved, fromIdx];
+    return [
+      changes,
+      pairs,
+      diff,
+      nodesToBeRemoved,
+      fromIdx,
+      mergeLevel,
+      preTombstoned
+    ];
   }
   /**
    * `editT` edits the given range with the given value.
@@ -13163,11 +13176,35 @@ class CRDTTree extends CRDTElement {
     return [prev, prev.isText ? TokenType.Text : TokenType.End];
   }
 }
-function clearRemovedAt(node) {
-  traverseAll(node, (n) => {
+function cloneAndDropPreTombstoned(node, preTombstoned) {
+  const clone = node.deepcopy();
+  filterChildren(clone, preTombstoned);
+  traverseAll(clone, (n) => {
     n.removedAt = void 0;
-    n.visibleSize = n.totalSize;
+    if (n.isText) {
+      n.visibleSize = n.value.length;
+      n.totalSize = n.value.length;
+      return;
+    }
+    let size = 0;
+    for (const child of n._children) size += child.paddedSize();
+    n.visibleSize = size;
+    n.totalSize = size;
   });
+  return clone;
+}
+function filterChildren(node, preTombstoned) {
+  const all = node._children;
+  if (!all) return;
+  const kept = [];
+  for (const child of all) {
+    if (preTombstoned.has(child.id.toIDString())) {
+      continue;
+    }
+    filterChildren(child, preTombstoned);
+    kept.push(child);
+  }
+  node._children = kept;
 }
 class TreeEditOperation extends Operation {
   fromPos;
@@ -13239,7 +13276,15 @@ class TreeEditOperation extends Operation {
         this.toPos = tree.findPos(this.toIdx);
       }
     }
-    const [changes, pairs, diff, removedNodes, preEditFromIdx] = tree.edit(
+    const [
+      changes,
+      pairs,
+      diff,
+      removedNodes,
+      preEditFromIdx,
+      mergeLevel,
+      preTombstoned
+    ] = tree.edit(
       [this.fromPos, this.toPos],
       this.contents?.map((content) => content.deepcopy()),
       this.splitLevel,
@@ -13274,7 +13319,13 @@ class TreeEditOperation extends Operation {
     let reverseOp;
     const isPureSplit = this.splitLevel > 0 && !this.contents?.length && removedNodes.length === 0;
     if (this.splitLevel === 0) {
-      reverseOp = this.toReverseOperation(tree, removedNodes, preEditFromIdx);
+      reverseOp = this.toReverseOperation(
+        tree,
+        removedNodes,
+        preEditFromIdx,
+        preTombstoned,
+        mergeLevel
+      );
     } else if (isPureSplit) {
       reverseOp = this.toSplitReverseOperation(tree, preEditFromIdx);
     }
@@ -13312,7 +13363,7 @@ class TreeEditOperation extends Operation {
    * @param removedNodes - Nodes that were removed by this edit
    * @param preEditFromIdx - The from index captured BEFORE the edit
    */
-  toReverseOperation(tree, removedNodes, preEditFromIdx) {
+  toReverseOperation(tree, removedNodes, preEditFromIdx, preTombstoned, mergeLevel) {
     if (this.redoSplitLevel !== void 0 && this.redoSplitLevel > 0) {
       const splitRedoFromPos = tree.findPos(preEditFromIdx);
       const splitRedoOp = TreeEditOperation.create(
@@ -13331,19 +13382,36 @@ class TreeEditOperation extends Operation {
       );
       return splitRedoOp;
     }
+    if (mergeLevel && mergeLevel > 0) {
+      const splitFromPos = tree.findPos(preEditFromIdx);
+      const splitUndoOp = TreeEditOperation.create(
+        this.getParentCreatedAt(),
+        splitFromPos,
+        splitFromPos,
+        void 0,
+        // no inserted content — split creates boundaries
+        mergeLevel,
+        // splitLevel = number of merged boundaries
+        void 0,
+        // executedAt assigned at undo time
+        true,
+        // isUndoOp
+        preEditFromIdx,
+        preEditFromIdx
+      );
+      return splitUndoOp;
+    }
     const insertedContentSize = this.contents ? this.contents.reduce((sum, node) => sum + node.paddedSize(), 0) : 0;
     const maxNeededIdx = preEditFromIdx + insertedContentSize;
     if (maxNeededIdx > tree.getSize()) {
       return void 0;
     }
     const topLevelRemoved = removedNodes.filter(
-      (node) => !node.parent || !removedNodes.includes(node.parent)
+      (node) => !preTombstoned.has(node.id.toIDString()) && (!node.parent || !removedNodes.includes(node.parent))
     );
-    const reverseContents = topLevelRemoved.length > 0 ? topLevelRemoved.map((n) => {
-      const clone = n.deepcopy();
-      clearRemovedAt(clone);
-      return clone;
-    }) : void 0;
+    const reverseContents = topLevelRemoved.length > 0 ? topLevelRemoved.map(
+      (n) => cloneAndDropPreTombstoned(n, preTombstoned)
+    ) : void 0;
     const reverseFromPos = tree.findPos(preEditFromIdx);
     let reverseToPos;
     if (insertedContentSize > 0) {
@@ -20157,6 +20225,11 @@ class Document {
       }
     ]);
   }
+  /**
+   * `clearHistory` flushes both undo and redo stacks. This is used
+   * after applying a snapshot or initialRoot so that setup operations
+   * are not reachable via undo.
+   */
   clearHistory() {
     this.internalHistory.clearRedo();
     this.internalHistory.clearUndo();
@@ -20616,10 +20689,7 @@ class Document {
     }
     const ops = isUndo ? this.internalHistory.popUndo() : this.internalHistory.popRedo();
     if (!ops) {
-      throw new YorkieError(
-        Code.ErrRefused,
-        `There is no operation to be ${isUndo ? "undone" : "redone"}`
-      );
+      return;
     }
     this.ensureClone();
     const ctx = ChangeContext.create(
@@ -20712,6 +20782,8 @@ class Attachment {
   syncMode;
   changeEventReceived;
   lastHeartbeatTime;
+  pollInterval;
+  pollIntervalPinned;
   reconnectStreamDelay;
   cancelled;
   watchStream;
@@ -20719,13 +20791,15 @@ class Attachment {
   watchAbortController;
   syncPromise;
   _detaching = false;
-  constructor(reconnectStreamDelay, resource, resourceID, syncMode) {
+  constructor(reconnectStreamDelay, resource, resourceID, syncMode, pollInterval = 0, pollIntervalPinned = false) {
     this.reconnectStreamDelay = reconnectStreamDelay;
     this.resource = resource;
     this.resourceID = resourceID;
     this.syncMode = syncMode;
     this.changeEventReceived = syncMode !== void 0 ? false : void 0;
     this.lastHeartbeatTime = Date.now();
+    this.pollInterval = pollInterval;
+    this.pollIntervalPinned = pollIntervalPinned;
     this.cancelled = false;
   }
   /**
@@ -20745,6 +20819,9 @@ class Attachment {
     if (this.syncMode === SyncMode.RealtimePushOnly) {
       return this.resource.hasLocalChanges();
     }
+    if (this.syncMode === SyncMode.Polling) {
+      return Date.now() - this.lastHeartbeatTime >= this.pollInterval;
+    }
     return this.syncMode !== SyncMode.Manual && (this.resource.hasLocalChanges() || (this.changeEventReceived ?? false));
   }
   /**
@@ -20758,7 +20835,8 @@ class Attachment {
     if (this.syncMode === SyncMode.Manual) {
       return false;
     }
-    return Date.now() - this.lastHeartbeatTime >= heartbeatInterval;
+    const interval = this.pollInterval > 0 ? this.pollInterval : heartbeatInterval;
+    return Date.now() - this.lastHeartbeatTime >= interval;
   }
   /**
    * `updateHeartbeatTime` updates the last heartbeat time.
@@ -20837,6 +20915,16 @@ class Attachment {
       }
     }
   }
+  /**
+   * `resetCancelled` clears the cancelled flag so the watch loop can run again
+   * after a previous cancellation (e.g., after changeSyncMode back to Realtime).
+   * Caller must invoke `runWatchLoop` immediately after to claim the stream slot;
+   * `doLoop`'s `if (this.watchStream)` guard prevents double-stream creation if a
+   * delayed `onDisconnect` callback from the previously-cancelled stream races.
+   */
+  resetCancelled() {
+    this.cancelled = false;
+  }
   /**
    * `cancelWatchStream` cancels the watch stream.
    */
@@ -20871,7 +20959,7 @@ function createAuthInterceptor(apiKey, token) {
   };
 }
 const name$1 = "@yorkie-js/sdk";
-const version$1 = "0.7.7";
+const version$1 = "0.7.8";
 const pkg$1 = {
   name: name$1,
   version: version$1
@@ -21154,8 +21242,10 @@ var SyncMode = /* @__PURE__ */ ((SyncMode2) => {
   SyncMode2["Realtime"] = "realtime";
   SyncMode2["RealtimePushOnly"] = "realtime-pushonly";
   SyncMode2["RealtimeSyncOff"] = "realtime-syncoff";
+  SyncMode2["Polling"] = "polling";
   return SyncMode2;
 })(SyncMode || {});
+const DefaultPollingIntervalMs = 3e3;
 const DefaultClientOptions = {
   rpcAddr: "https://api.yorkie.dev",
   syncLoopDuration: 50,
@@ -21351,6 +21441,14 @@ class Client {
     doc.setActor(this.id);
     doc.update((_, p) => p.set(opts.initialPresence || {}));
     const syncMode = opts.syncMode ?? "realtime";
+    if (opts.documentPollInterval !== void 0 && opts.documentPollInterval <= 0) {
+      throw new YorkieError(
+        Code.ErrInvalidArgument,
+        "documentPollInterval must be greater than 0"
+      );
+    }
+    const pollIntervalPinned = opts.documentPollInterval !== void 0;
+    const pollInterval = pollIntervalPinned ? opts.documentPollInterval : syncMode === "polling" ? DefaultPollingIntervalMs : 0;
     return this.enqueueTask(async () => {
       try {
         const res = await this.rpcClient.attachDocument(
@@ -21380,10 +21478,12 @@ class Client {
             this.reconnectStreamDelay,
             doc,
             res.documentId,
-            syncMode
+            syncMode,
+            pollInterval,
+            pollIntervalPinned
           )
         );
-        if (syncMode !== "manual") {
+        if (syncMode !== "manual" && syncMode !== "polling") {
           await this.runWatchLoop(doc.getKey());
         }
         logger.info(`[AD] c:"${this.getKey()}" attaches d:"${doc.getKey()}"`);
@@ -21399,6 +21499,7 @@ class Client {
             }
           });
         }
+        doc.clearHistory();
         return doc;
       } catch (err) {
         logger.error(`[AD] c:"${this.getKey()}" err :`, err);
@@ -21509,12 +21610,23 @@ class Client {
         channel.setSessionID(res.sessionId);
         channel.updateSessionCount(Number(res.sessionCount), 0);
         channel.applyStatus(ChannelStatus.Attached);
-        const syncMode = opts.isRealtime !== false ? "realtime" : "manual";
+        const syncMode = opts.syncMode ?? "realtime";
+        this.assertValidChannelSyncMode(syncMode);
+        if (opts.channelHeartbeatInterval !== void 0 && opts.channelHeartbeatInterval <= 0) {
+          throw new YorkieError(
+            Code.ErrInvalidArgument,
+            "channelHeartbeatInterval must be greater than 0"
+          );
+        }
+        const pollIntervalPinned = opts.channelHeartbeatInterval !== void 0;
+        const pollInterval = pollIntervalPinned ? opts.channelHeartbeatInterval : syncMode === "polling" ? DefaultPollingIntervalMs : this.channelHeartbeatInterval;
         const attachment = new Attachment(
           this.reconnectStreamDelay,
           channel,
           res.sessionId,
-          syncMode
+          syncMode,
+          pollInterval,
+          pollIntervalPinned
         );
         channel.subscribe("local-broadcast", (event) => {
           const { topic, payload, options } = event;
@@ -21590,9 +21702,17 @@ class Client {
     return this.enqueueTask(task);
   }
   /**
-   * `changeSyncMode` changes the synchronization mode of the given document.
+   * `changeSyncMode` changes the synchronization mode of the given resource.
    */
-  async changeSyncMode(doc, syncMode) {
+  async changeSyncMode(resource, syncMode) {
+    return this.enqueueTask(async () => {
+      if (resource instanceof Channel2) {
+        return this.changeChannelSyncMode(resource, syncMode);
+      }
+      return this.changeDocumentSyncMode(resource, syncMode);
+    });
+  }
+  async changeDocumentSyncMode(doc, syncMode) {
     if (!this.isActive()) {
       throw new YorkieError(
         Code.ErrClientNotActivated,
@@ -21610,19 +21730,66 @@ class Client {
     if (prevSyncMode === syncMode) {
       return doc;
     }
-    attachment.changeSyncMode(syncMode);
-    if (syncMode === "manual") {
+    if (syncMode === "manual" || syncMode === "polling") {
       attachment.cancelWatchStream();
-      return doc;
     }
+    attachment.changeSyncMode(syncMode);
     if (syncMode === "realtime") {
       attachment.changeEventReceived = true;
     }
-    if (prevSyncMode === "manual") {
+    if (!attachment.pollIntervalPinned) {
+      attachment.pollInterval = syncMode === "polling" ? DefaultPollingIntervalMs : 0;
+    }
+    if ((prevSyncMode === "manual" || prevSyncMode === "polling") && syncMode !== "manual" && syncMode !== "polling") {
+      attachment.resetCancelled();
       await this.runWatchLoop(doc.getKey());
     }
     return doc;
   }
+  /**
+   * `assertValidChannelSyncMode` rejects sync modes that are not valid for
+   * channels. `RealtimePushOnly` and `RealtimeSyncOff` are document-only.
+   */
+  assertValidChannelSyncMode(syncMode) {
+    if (syncMode !== "manual" && syncMode !== "realtime" && syncMode !== "polling") {
+      throw new YorkieError(
+        Code.ErrInvalidArgument,
+        `invalid channel sync mode: ${syncMode}`
+      );
+    }
+  }
+  async changeChannelSyncMode(channel, syncMode) {
+    if (!this.isActive()) {
+      throw new YorkieError(
+        Code.ErrClientNotActivated,
+        `${this.key} is not active`
+      );
+    }
+    const attachment = this.attachmentMap.get(channel.getKey());
+    if (!attachment) {
+      throw new YorkieError(
+        Code.ErrNotAttached,
+        `${channel.getKey()} is not attached`
+      );
+    }
+    const prevSyncMode = attachment.syncMode;
+    if (prevSyncMode === syncMode) {
+      return channel;
+    }
+    this.assertValidChannelSyncMode(syncMode);
+    if (prevSyncMode === "realtime") {
+      attachment.cancelWatchStream();
+    }
+    attachment.changeSyncMode(syncMode);
+    if (!attachment.pollIntervalPinned) {
+      attachment.pollInterval = syncMode === "polling" ? DefaultPollingIntervalMs : syncMode === "realtime" ? this.channelHeartbeatInterval : 0;
+    }
+    if (syncMode === "realtime") {
+      attachment.resetCancelled();
+      await this.runWatchLoop(channel.getKey());
+    }
+    return channel;
+  }
   /**
    * `sync` implementation that handles both Document and Channel.
    */
@@ -22467,6 +22634,7 @@ class Client {
         return doc;
       }
       doc.applyChangePack(respPack);
+      attachment.updateHeartbeatTime();
       attachment.resource.publish([
         {
           type: DocEventType.SyncStatusChanged,
@@ -22792,7 +22960,7 @@ if (typeof globalThis !== "undefined") {
   };
 }
 const name = "@yorkie-js/react";
-const version = "0.7.7";
+const version = "0.7.8";
 const pkg = {
   name,
   version
@@ -23248,7 +23416,7 @@ function createChannelStore(initialState) {
 const ChannelContext = createContext(
   void 0
 );
-function useYorkieChannel(client, clientLoading, clientError, channelKey, isRealtime, channelStore) {
+function useYorkieChannel(client, clientLoading, clientError, channelKey, syncMode, channelStore) {
   const channelRef = useRef(void 0);
   const [didMount, setDidMount] = useState(false);
   useEffect(() => {
@@ -23277,7 +23445,7 @@ function useYorkieChannel(client, clientLoading, clientError, channelKey, isReal
       }));
       try {
         const newChannel = new Channel2(channelKey);
-        await client.attach(newChannel, { isRealtime });
+        await client.attach(newChannel, { syncMode });
         channelRef.current = newChannel;
         unsubscribe = newChannel.subscribe(() => {
           channelStore.setState((state) => ({
@@ -23315,12 +23483,13 @@ function useYorkieChannel(client, clientLoading, clientError, channelKey, isReal
       }
       detachChannel();
     };
-  }, [client, clientLoading, clientError, channelKey, isRealtime, didMount]);
+  }, [client, clientLoading, clientError, channelKey, syncMode, didMount]);
 }
 const ChannelProvider = ({
   children,
   channelKey,
-  isRealtime = true
+  syncMode,
+  isRealtime
 }) => {
   const { client, loading: clientLoading, error: clientError } = useYorkie();
   const channelStoreRef = useRef(
@@ -23335,12 +23504,13 @@ const ChannelProvider = ({
     });
   }
   const channelStore = channelStoreRef.current;
+  const resolvedSyncMode = syncMode ?? (isRealtime === false ? SyncMode.Manual : SyncMode.Realtime);
   useYorkieChannel(
     client,
     clientLoading,
     clientError,
     channelKey,
-    isRealtime,
+    resolvedSyncMode,
     channelStore
   );
   return /* @__PURE__ */ jsx(ChannelContext.Provider, { value: channelStore, children });
@@ -23367,6 +23537,7 @@ export {
   ChannelProvider,
   Counter,
   DocumentProvider,
+  SyncMode,
   Text,
   Tree,
   YorkieProvider,