@yorkie-js/sdk 0.7.7 → 0.7.8

package/README.md

@@ -10,7 +10,7 @@ To get started using Yorkie JavaScript SDK, see: https://yorkie.dev/docs/js-sdk
 
 ## 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-sdk.d.ts

@@ -93,20 +93,30 @@ declare interface Attachable {
 /**
  * `AttachChannelOptions` are user-settable options used when attaching channels.
  */
-declare interface AttachChannelOptions {
+export declare interface AttachChannelOptions {
     /**
-     * `isRealtime` determines whether to automatically watch channel changes
-     * and send heartbeats. If false (manual mode), the client must call sync()
-     * explicitly to refresh the TTL.
-     * Default is true for backward compatibility.
+     * `syncMode` selects how the channel keeps presence in sync with the server.
+     * Default is `SyncMode.Realtime`.
+     * - `SyncMode.Realtime`: open a watch stream and run the heartbeat. Required
+     *   to receive broadcast events.
+     * - `SyncMode.Polling`: heartbeat-only. No watch stream is opened. The
+     *   heartbeat refreshes TTL and brings the latest sessionCount. Recommended
+     *   for large channels where broadcast is not needed.
+     * - `SyncMode.Manual`: no automatic activity. Caller must invoke `sync()`.
      */
-    isRealtime?: boolean;
+    syncMode?: SyncMode;
+    /**
+     * `channelHeartbeatInterval` overrides the heartbeat interval (ms) for this
+     * attachment. If unset, mode-specific defaults apply: Polling=3000,
+     * Realtime=30000.
+     */
+    channelHeartbeatInterval?: number;
 }
 
 /**
  * `AttachOptions` are user-settable options used when attaching documents.
  */
-declare interface AttachOptions<R, P> {
+export declare interface AttachOptions<R, P> {
     /**
      * `initialRoot` is the initial root of the document. It is used to
      * initialize the document. It is used when the fields are not set in the
@@ -121,6 +131,11 @@ declare interface AttachOptions<R, P> {
      * `syncMode` defines the synchronization mode of the document.
      */
     syncMode?: SyncMode;
+    /**
+     * `documentPollInterval` (ms) — only used when `syncMode` is `Polling`.
+     * Default: 3000.
+     */
+    documentPollInterval?: number;
     /**
      * `schema` is the schema of the document. It is used to validate the
      * document.
@@ -1039,6 +1054,17 @@ export declare class Client {
      * `changeSyncMode` changes the synchronization mode of the given document.
      */
     changeSyncMode<R, P extends Indexable>(doc: Document_2<R, P>, syncMode: SyncMode): Promise<Document_2<R, P>>;
+    /**
+     * `changeSyncMode` changes the synchronization mode of the given channel.
+     */
+    changeSyncMode(channel: Channel, syncMode: SyncMode): Promise<Channel>;
+    private changeDocumentSyncMode;
+    /**
+     * `assertValidChannelSyncMode` rejects sync modes that are not valid for
+     * channels. `RealtimePushOnly` and `RealtimeSyncOff` are document-only.
+     */
+    private assertValidChannelSyncMode;
+    private changeChannelSyncMode;
     /**
      * `sync` pushes local changes of the attached documents to the server and
      * receives changes of the remote replica from the server then apply them to
@@ -1997,12 +2023,28 @@ declare class CRDTTree extends CRDTElement implements GCParent {
      * `edit` edits the tree with the given range and content.
      * If the content is undefined, the range will be removed.
      */
-    edit(range: [CRDTTreePos, CRDTTreePos], contents: Array<CRDTTreeNode> | undefined, splitLevel: number, editedAt: TimeTicket, issueTimeTicket: (() => TimeTicket) | undefined, versionVector?: VersionVector): [Array<TreeChange>, Array<GCPair>, DataSize, Array<CRDTTreeNode>, number];
+    edit(range: [CRDTTreePos, CRDTTreePos], contents: Array<CRDTTreeNode> | undefined, splitLevel: number, editedAt: TimeTicket, issueTimeTicket: (() => TimeTicket) | undefined, versionVector?: VersionVector): [
+    Array<TreeChange>,
+    Array<GCPair>,
+    DataSize,
+    Array<CRDTTreeNode>,
+    number,
+    number,
+    Set<string>
+    ];
     /**
      * `editT` edits the given range with the given value.
      * This method uses indexes instead of a pair of TreePos for testing.
      */
-    editT(range: [number, number], contents: Array<CRDTTreeNode> | undefined, splitLevel: number, editedAt: TimeTicket, issueTimeTicket: () => TimeTicket): [Array<TreeChange>, Array<GCPair>, DataSize, Array<CRDTTreeNode>, number];
+    editT(range: [number, number], contents: Array<CRDTTreeNode> | undefined, splitLevel: number, editedAt: TimeTicket, issueTimeTicket: () => TimeTicket): [
+    Array<TreeChange>,
+    Array<GCPair>,
+    DataSize,
+    Array<CRDTTreeNode>,
+    number,
+    number,
+    Set<string>
+    ];
     /**
      * `move` move the given source range to the given target range.
      */
@@ -3035,7 +3077,12 @@ declare class Document_2<R, P extends Indexable = Indexable> implements Attachab
      * `applySnapshot` applies the given snapshot into this document.
      */
     applySnapshot(serverSeq: bigint, snapshotVector: VersionVector, snapshot?: Uint8Array, clientSeq?: number): void;
-    private clearHistory;
+    /**
+     * `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(): void;
     /**
      * `applyChanges` applies the given changes into this document.
      */
@@ -6005,7 +6052,8 @@ declare interface SubscribeFn<T> {
 }
 
 /**
- * `SyncMode` defines synchronization modes for the PushPullChanges API.
+ * `SyncMode` defines synchronization modes for the PushPullChanges API
+ * (documents) and the RefreshChannel heartbeat (channels).
  */
 export declare enum SyncMode {
     /**
@@ -6024,7 +6072,15 @@ export declare enum SyncMode {
      * `RealtimeSyncOff` mode indicates that changes are not automatically pushed or pulled,
      * but the watch stream is kept active.
      */
-    RealtimeSyncOff = "realtime-syncoff"
+    RealtimeSyncOff = "realtime-syncoff",
+    /**
+     * `Polling` mode runs the sync loop without opening a watch stream.
+     * - For Channel: heartbeat refreshes TTL and brings sessionCount.
+     * - For Document: PushPullChanges runs at the polling interval. Remote
+     *   changes arrive on the next tick (latency = interval). Not suitable
+     *   for collaborative editing — use Realtime for that.
+     */
+    Polling = "polling"
 }
 
 /**

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

@@ -358,7 +358,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) {
@@ -584,7 +584,7 @@ function convertObjectValues(obj, fn) {
   }
   return ret;
 }
-const tokenZeroMessageField = Symbol();
+const tokenZeroMessageField = /* @__PURE__ */ Symbol();
 const messagePrototypes = /* @__PURE__ */ new WeakMap();
 function createZeroMessage(desc) {
   let msg;
@@ -686,7 +686,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();
@@ -4054,7 +4054,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") {
@@ -4080,7 +4080,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) {
@@ -5901,6 +5901,8 @@ class YorkieError extends Error {
     this.message = message;
     this.toString = () => `[code=${this.code}]: ${this.message}`;
   }
+  code;
+  message;
   name = "YorkieError";
   stack;
 }
@@ -12530,8 +12532,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;
@@ -12594,6 +12598,7 @@ class CRDTTree extends CRDTElement {
       tokensToBeRemoved,
       editedAt
     );
+    const mergeLevel = toBeMergedNodes.length;
     const pairs = [];
     for (const node of nodesToBeRemoved) {
       if (node.remove(editedAt)) {
@@ -12720,7 +12725,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.
@@ -13161,11 +13174,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;
@@ -13237,7 +13274,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,
@@ -13272,7 +13317,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);
     }
@@ -13310,7 +13361,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(
@@ -13329,19 +13380,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) {
@@ -20160,6 +20228,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();
@@ -20619,10 +20692,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(
@@ -20715,6 +20785,8 @@ class Attachment {
   syncMode;
   changeEventReceived;
   lastHeartbeatTime;
+  pollInterval;
+  pollIntervalPinned;
   reconnectStreamDelay;
   cancelled;
   watchStream;
@@ -20722,13 +20794,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;
   }
   /**
@@ -20748,6 +20822,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));
   }
   /**
@@ -20761,7 +20838,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.
@@ -20840,6 +20918,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.
    */
@@ -20874,7 +20962,7 @@ function createAuthInterceptor(apiKey, token) {
   };
 }
 const name = "@yorkie-js/sdk";
-const version = "0.7.7";
+const version = "0.7.8";
 const pkg = {
   name,
   version
@@ -21157,6 +21245,7 @@ var SyncMode = /* @__PURE__ */ ((SyncMode2) => {
   SyncMode2["Realtime"] = "realtime";
   SyncMode2["RealtimePushOnly"] = "realtime-pushonly";
   SyncMode2["RealtimeSyncOff"] = "realtime-syncoff";
+  SyncMode2["Polling"] = "polling";
   return SyncMode2;
 })(SyncMode || {});
 var ClientStatus = /* @__PURE__ */ ((ClientStatus2) => {
@@ -21169,6 +21258,7 @@ var ClientCondition = /* @__PURE__ */ ((ClientCondition2) => {
   ClientCondition2["WatchLoop"] = "WatchLoop";
   return ClientCondition2;
 })(ClientCondition || {});
+const DefaultPollingIntervalMs = 3e3;
 const DefaultClientOptions = {
   rpcAddr: "https://api.yorkie.dev",
   syncLoopDuration: 50,
@@ -21364,6 +21454,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(
@@ -21393,10 +21491,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()}"`);
@@ -21412,6 +21512,7 @@ class Client {
             }
           });
         }
+        doc.clearHistory();
         return doc;
       } catch (err) {
         logger.error(`[AD] c:"${this.getKey()}" err :`, err);
@@ -21522,12 +21623,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;
@@ -21603,9 +21715,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,
@@ -21623,19 +21743,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.
    */
@@ -22480,6 +22647,7 @@ class Client {
         return doc;
       }
       doc.applyChangePack(respPack);
+      attachment.updateHeartbeatTime();
       attachment.resource.publish([
         {
           type: DocEventType.SyncStatusChanged,