@lark-sh/client 0.1.7 → 0.1.9

package/dist/index.mjs

@@ -60,6 +60,331 @@ var Coordinator = class {
   }
 };
 
+// src/connection/WebSocketTransport.ts
+import WebSocketNode from "ws";
+var WebSocketImpl = typeof WebSocket !== "undefined" ? WebSocket : WebSocketNode;
+var WebSocketTransport = class {
+  constructor(options) {
+    this.ws = null;
+    this._state = "disconnected";
+    this.options = options;
+  }
+  get state() {
+    return this._state;
+  }
+  get connected() {
+    return this._state === "connected";
+  }
+  /**
+   * Connect to a WebSocket server.
+   */
+  connect(url) {
+    return new Promise((resolve, reject) => {
+      if (this._state !== "disconnected") {
+        reject(new Error("Already connected or connecting"));
+        return;
+      }
+      this._state = "connecting";
+      try {
+        this.ws = new WebSocketImpl(url);
+      } catch (err) {
+        this._state = "disconnected";
+        reject(err);
+        return;
+      }
+      const onOpen = () => {
+        cleanup();
+        this._state = "connected";
+        this.setupEventHandlers();
+        resolve();
+        this.options.onOpen();
+      };
+      const onError = (event) => {
+        cleanup();
+        this._state = "disconnected";
+        this.ws = null;
+        const error = new Error("WebSocket connection failed");
+        reject(error);
+        this.options.onError(error);
+      };
+      const onClose = (event) => {
+        cleanup();
+        this._state = "disconnected";
+        this.ws = null;
+        reject(new Error(`WebSocket closed: ${event.code} ${event.reason}`));
+      };
+      const cleanup = () => {
+        this.ws?.removeEventListener("open", onOpen);
+        this.ws?.removeEventListener("error", onError);
+        this.ws?.removeEventListener("close", onClose);
+      };
+      this.ws.addEventListener("open", onOpen);
+      this.ws.addEventListener("error", onError);
+      this.ws.addEventListener("close", onClose);
+    });
+  }
+  /**
+   * Set up persistent event handlers after connection is established.
+   */
+  setupEventHandlers() {
+    if (!this.ws) return;
+    this.ws.addEventListener("message", (event) => {
+      this.options.onMessage(event.data);
+    });
+    this.ws.addEventListener("close", (event) => {
+      this._state = "disconnected";
+      this.ws = null;
+      this.options.onClose(event.code, event.reason);
+    });
+    this.ws.addEventListener("error", () => {
+      this.options.onError(new Error("WebSocket error"));
+    });
+  }
+  /**
+   * Send a message over the WebSocket.
+   */
+  send(data) {
+    if (!this.ws || this._state !== "connected") {
+      throw new Error("WebSocket not connected");
+    }
+    this.ws.send(data);
+  }
+  /**
+   * Send a volatile message.
+   * WebSocket doesn't have a true unreliable channel, so this just calls send().
+   */
+  sendVolatile(data) {
+    this.send(data);
+  }
+  /**
+   * Close the WebSocket connection.
+   */
+  close(code = 1e3, reason = "Client disconnect") {
+    if (this.ws) {
+      this.ws.close(code, reason);
+      this.ws = null;
+    }
+    this._state = "disconnected";
+  }
+};
+
+// src/connection/WebTransportClient.ts
+var WebTransportClient = class {
+  constructor(options) {
+    this.transport = null;
+    this.writer = null;
+    this.datagramWriter = null;
+    this._state = "disconnected";
+    this.readLoopActive = false;
+    this.datagramLoopActive = false;
+    this.options = options;
+  }
+  get state() {
+    return this._state;
+  }
+  get connected() {
+    return this._state === "connected";
+  }
+  /**
+   * Connect to a WebTransport server.
+   */
+  async connect(url) {
+    if (this._state !== "disconnected") {
+      throw new Error("Already connected or connecting");
+    }
+    this._state = "connecting";
+    try {
+      this.transport = new WebTransport(url);
+      await this.transport.ready;
+      const stream = await this.transport.createBidirectionalStream();
+      this.writer = stream.writable.getWriter();
+      this.datagramWriter = this.transport.datagrams.writable.getWriter();
+      this._state = "connected";
+      this.readLoop(stream.readable.getReader());
+      this.datagramLoop(this.transport.datagrams.readable.getReader());
+      this.transport.closed.then(({ closeCode, reason }) => {
+        this.handleClose(closeCode, reason);
+      }).catch(() => {
+        this.handleClose(0, "Connection failed");
+      });
+      this.options.onOpen();
+    } catch (err) {
+      this._state = "disconnected";
+      this.transport = null;
+      this.writer = null;
+      this.datagramWriter = null;
+      throw err;
+    }
+  }
+  /**
+   * Read messages from the reliable stream.
+   * Messages are framed with 4-byte big-endian length prefix.
+   */
+  async readLoop(reader) {
+    this.readLoopActive = true;
+    let buffer = new Uint8Array(0);
+    try {
+      while (this.readLoopActive) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        const newBuffer = new Uint8Array(buffer.length + value.length);
+        newBuffer.set(buffer);
+        newBuffer.set(value, buffer.length);
+        buffer = newBuffer;
+        while (buffer.length >= 4) {
+          const view = new DataView(buffer.buffer, buffer.byteOffset);
+          const msgLength = view.getUint32(0, false);
+          if (buffer.length < 4 + msgLength) break;
+          const msgBytes = buffer.slice(4, 4 + msgLength);
+          const json = new TextDecoder().decode(msgBytes);
+          try {
+            this.options.onMessage(json);
+          } catch (err) {
+            console.error("Error handling message:", err);
+          }
+          buffer = buffer.slice(4 + msgLength);
+        }
+      }
+    } catch (err) {
+      if (this.readLoopActive) {
+        console.error("Read loop error:", err);
+      }
+    }
+  }
+  /**
+   * Read volatile events from datagrams.
+   * No framing needed - each datagram is a complete JSON message.
+   */
+  async datagramLoop(reader) {
+    this.datagramLoopActive = true;
+    try {
+      while (this.datagramLoopActive) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        const json = new TextDecoder().decode(value);
+        try {
+          this.options.onMessage(json);
+        } catch (err) {
+          console.error("Error handling datagram:", err);
+        }
+      }
+    } catch (err) {
+      if (this.datagramLoopActive) {
+        console.error("Datagram loop error:", err);
+      }
+    }
+  }
+  /**
+   * Handle connection close.
+   */
+  handleClose(code, reason) {
+    if (this._state === "disconnected") return;
+    this.readLoopActive = false;
+    this.datagramLoopActive = false;
+    this._state = "disconnected";
+    this.transport = null;
+    this.writer = null;
+    this.datagramWriter = null;
+    this.options.onClose(code, reason);
+  }
+  /**
+   * Send a message over the reliable stream.
+   * Uses 4-byte big-endian length prefix.
+   */
+  send(data) {
+    if (!this.writer || this._state !== "connected") {
+      throw new Error("WebTransport not connected");
+    }
+    const encoder = new TextEncoder();
+    const msgBytes = encoder.encode(data);
+    const lengthBuffer = new ArrayBuffer(4);
+    new DataView(lengthBuffer).setUint32(0, msgBytes.length, false);
+    this.writer.write(new Uint8Array(lengthBuffer)).catch((err) => {
+      console.error("Failed to write length prefix:", err);
+    });
+    this.writer.write(msgBytes).catch((err) => {
+      console.error("Failed to write message:", err);
+    });
+  }
+  /**
+   * Send a volatile message via datagram (unreliable).
+   * No framing needed - each datagram is a complete message.
+   */
+  sendVolatile(data) {
+    if (!this.datagramWriter || this._state !== "connected") {
+      throw new Error("WebTransport not connected");
+    }
+    const encoder = new TextEncoder();
+    const msgBytes = encoder.encode(data);
+    this.datagramWriter.write(msgBytes).catch(() => {
+    });
+  }
+  /**
+   * Close the WebTransport connection.
+   */
+  close(code = 0, reason = "Client disconnect") {
+    this.readLoopActive = false;
+    this.datagramLoopActive = false;
+    if (this.writer) {
+      this.writer.releaseLock();
+      this.writer = null;
+    }
+    if (this.datagramWriter) {
+      this.datagramWriter.releaseLock();
+      this.datagramWriter = null;
+    }
+    if (this.transport) {
+      this.transport.close({ closeCode: code, reason });
+      this.transport = null;
+    }
+    this._state = "disconnected";
+  }
+};
+function isWebTransportAvailable() {
+  return typeof globalThis !== "undefined" && "WebTransport" in globalThis;
+}
+
+// src/connection/createTransport.ts
+function wsUrlToWtUrl(wsUrl) {
+  const url = new URL(wsUrl);
+  url.protocol = url.protocol === "wss:" ? "https:" : "http:";
+  const port = 7778 + Math.floor(Math.random() * 32);
+  url.port = String(port);
+  url.pathname = "/wt";
+  return url.toString();
+}
+async function createTransport(wsUrl, transportOptions, options = {}) {
+  const preferredType = options.transport || "auto";
+  const shouldTryWebTransport = (preferredType === "auto" || preferredType === "webtransport") && isWebTransportAvailable();
+  if (preferredType === "webtransport" && !isWebTransportAvailable()) {
+    throw new Error("WebTransport is not available in this environment");
+  }
+  if (shouldTryWebTransport) {
+    const wtUrl = wsUrlToWtUrl(wsUrl);
+    const wtTransport = new WebTransportClient(transportOptions);
+    try {
+      await wtTransport.connect(wtUrl);
+      return {
+        transport: wtTransport,
+        type: "webtransport",
+        url: wtUrl
+      };
+    } catch (err) {
+      if (preferredType === "webtransport") {
+        throw err;
+      }
+      console.warn("WebTransport connection failed, falling back to WebSocket:", err);
+    }
+  }
+  const wsTransport = new WebSocketTransport(transportOptions);
+  await wsTransport.connect(wsUrl);
+  return {
+    transport: wsTransport,
+    type: "websocket",
+    url: wsUrl
+  };
+}
+
 // src/LarkError.ts
 var LarkError = class _LarkError extends Error {
   constructor(code, message) {
@@ -1025,13 +1350,15 @@ var SubscriptionManager = class {
   }
   /**
    * Handle an incoming event message from the server.
-   * Server sends 'put' or 'patch' events; we generate child_* events client-side.
+   * Server sends 'put', 'patch', or 'vb' (volatile batch) events; we generate child_* events client-side.
    */
   handleEvent(message) {
     if (message.ev === "put") {
       this.handlePutEvent(message);
     } else if (message.ev === "patch") {
       this.handlePatchEvent(message);
+    } else if (message.ev === "vb") {
+      this.handleVolatileBatchEvent(message);
     } else {
       console.warn("Unknown event type:", message.ev);
     }
@@ -1085,6 +1412,26 @@ var SubscriptionManager = class {
     }
     this.applyWriteToView(view, updates, isVolatile, serverTimestamp);
   }
+  /**
+   * Handle a 'vb' (volatile batch) event - batched volatile updates across subscriptions.
+   * Server batches volatile events in 50ms intervals to reduce message overhead.
+   * Format: { ev: 'vb', b: { subscriptionPath: { relativePath: value } }, ts: timestamp }
+   */
+  handleVolatileBatchEvent(message) {
+    const batch = message.b;
+    const serverTimestamp = message.ts;
+    if (!batch) return;
+    for (const [subscriptionPath, updates] of Object.entries(batch)) {
+      const view = this.views.get(subscriptionPath);
+      if (!view) continue;
+      if (view.recovering) continue;
+      const updatesList = [];
+      for (const [relativePath, value] of Object.entries(updates)) {
+        updatesList.push({ relativePath, value });
+      }
+      this.applyWriteToView(view, updatesList, true, serverTimestamp);
+    }
+  }
   /**
    * Detect and fire child_moved events for children that changed position.
    */
@@ -1301,6 +1648,34 @@ var SubscriptionManager = class {
   // ============================================
   // Shared Write Application (used by server events and optimistic writes)
   // ============================================
+  /**
+   * Recursively sort object keys for consistent comparison.
+   * This ensures {a:1, b:2} and {b:2, a:1} compare as equal.
+   * Uses simple alphabetical sorting (not Firebase key sorting) since we're
+   * just checking data equality, not display order.
+   */
+  sortKeysForComparison(value) {
+    if (value === null || typeof value !== "object") {
+      return value;
+    }
+    if (Array.isArray(value)) {
+      return value.map((item) => this.sortKeysForComparison(item));
+    }
+    const obj = value;
+    const sortedKeys = Object.keys(obj).sort();
+    const sorted = {};
+    for (const key of sortedKeys) {
+      sorted[key] = this.sortKeysForComparison(obj[key]);
+    }
+    return sorted;
+  }
+  /**
+   * Serialize cache with sorted keys for consistent comparison.
+   */
+  serializeCacheForComparison(cache) {
+    const sorted = this.sortKeysForComparison(cache);
+    return JSON.stringify(sorted);
+  }
   /**
    * Apply write(s) to a View's cache and fire appropriate events.
    * This is the core logic shared between server events and optimistic writes.
@@ -1313,7 +1688,11 @@ var SubscriptionManager = class {
   applyWriteToView(view, updates, isVolatile, serverTimestamp) {
     const previousOrder = view.orderedChildren;
     const previousChildSet = new Set(previousOrder);
-    const previousCacheJson = JSON.stringify(view.getCache());
+    const isFirstSnapshot = !view.hasReceivedInitialSnapshot;
+    let previousCacheJson = null;
+    if (!isVolatile) {
+      previousCacheJson = this.serializeCacheForComparison(view.getCache());
+    }
     const affectedChildren = /* @__PURE__ */ new Set();
     let isFullSnapshot = false;
     for (const { relativePath, value } of updates) {
@@ -1334,9 +1713,11 @@ var SubscriptionManager = class {
     }
     const currentOrder = view.orderedChildren;
     const currentChildSet = new Set(currentOrder);
-    const currentCacheJson = JSON.stringify(view.getCache());
-    if (previousCacheJson === currentCacheJson) {
-      return;
+    if (!isVolatile && !isFirstSnapshot && previousCacheJson !== null) {
+      const currentCacheJson = this.serializeCacheForComparison(view.getCache());
+      if (previousCacheJson === currentCacheJson) {
+        return;
+      }
     }
     const valueSubs = view.getCallbacks("value");
     if (valueSubs.length > 0) {
@@ -1546,106 +1927,6 @@ var SubscriptionManager = class {
   }
 };
 
-// src/connection/WebSocketClient.ts
-import WebSocketNode from "ws";
-var WebSocketImpl = typeof WebSocket !== "undefined" ? WebSocket : WebSocketNode;
-var WebSocketClient = class {
-  constructor(options) {
-    this.ws = null;
-    this._state = "disconnected";
-    this.options = options;
-  }
-  get state() {
-    return this._state;
-  }
-  get connected() {
-    return this._state === "connected";
-  }
-  /**
-   * Connect to a WebSocket server.
-   */
-  connect(url) {
-    return new Promise((resolve, reject) => {
-      if (this._state !== "disconnected") {
-        reject(new Error("Already connected or connecting"));
-        return;
-      }
-      this._state = "connecting";
-      try {
-        this.ws = new WebSocketImpl(url);
-      } catch (err) {
-        this._state = "disconnected";
-        reject(err);
-        return;
-      }
-      const onOpen = () => {
-        cleanup();
-        this._state = "connected";
-        this.setupEventHandlers();
-        resolve();
-        this.options.onOpen();
-      };
-      const onError = (event) => {
-        cleanup();
-        this._state = "disconnected";
-        this.ws = null;
-        reject(new Error("WebSocket connection failed"));
-        this.options.onError(event);
-      };
-      const onClose = (event) => {
-        cleanup();
-        this._state = "disconnected";
-        this.ws = null;
-        reject(new Error(`WebSocket closed: ${event.code} ${event.reason}`));
-      };
-      const cleanup = () => {
-        this.ws?.removeEventListener("open", onOpen);
-        this.ws?.removeEventListener("error", onError);
-        this.ws?.removeEventListener("close", onClose);
-      };
-      this.ws.addEventListener("open", onOpen);
-      this.ws.addEventListener("error", onError);
-      this.ws.addEventListener("close", onClose);
-    });
-  }
-  /**
-   * Set up persistent event handlers after connection is established.
-   */
-  setupEventHandlers() {
-    if (!this.ws) return;
-    this.ws.addEventListener("message", (event) => {
-      this.options.onMessage(event.data);
-    });
-    this.ws.addEventListener("close", (event) => {
-      this._state = "disconnected";
-      this.ws = null;
-      this.options.onClose(event.code, event.reason);
-    });
-    this.ws.addEventListener("error", (event) => {
-      this.options.onError(event);
-    });
-  }
-  /**
-   * Send a message over the WebSocket.
-   */
-  send(data) {
-    if (!this.ws || this._state !== "connected") {
-      throw new Error("WebSocket not connected");
-    }
-    this.ws.send(data);
-  }
-  /**
-   * Close the WebSocket connection.
-   */
-  close(code = 1e3, reason = "Client disconnect") {
-    if (this.ws) {
-      this.ws.close(code, reason);
-      this.ws = null;
-    }
-    this._state = "disconnected";
-  }
-};
-
 // src/OnDisconnect.ts
 var OnDisconnect = class {
   constructor(db, path) {
@@ -1693,6 +1974,27 @@ var OnDisconnect = class {
   }
 };
 
+// src/utils/hash.ts
+import canonicalize from "canonicalize";
+async function hashValue(value) {
+  const canonical = canonicalize(value);
+  if (canonical === void 0) {
+    return hashString("");
+  }
+  return hashString(canonical);
+}
+async function hashString(str) {
+  const encoder = new TextEncoder();
+  const data = encoder.encode(str);
+  const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+  const hashArray = new Uint8Array(hashBuffer);
+  const hashHex = Array.from(hashArray).map((b) => b.toString(16).padStart(2, "0")).join("");
+  return hashHex;
+}
+function isPrimitive(value) {
+  return value === null || typeof value !== "object";
+}
+
 // src/utils/pushid.ts
 var PUSH_CHARS = "-0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz";
 var lastPushTime = 0;
@@ -1777,8 +2079,15 @@ var DatabaseReference = class _DatabaseReference {
   // ============================================
   /**
    * Set the data at this location, overwriting any existing data.
+   *
+   * For volatile paths (high-frequency updates), this is fire-and-forget
+   * and resolves immediately without waiting for server confirmation.
    */
   async set(value) {
+    if (this._db.isVolatilePath(this._path)) {
+      this._db._sendVolatileSet(this._path, value);
+      return;
+    }
     await this._db._sendSet(this._path, value);
   }
   /**
@@ -1815,13 +2124,23 @@ var DatabaseReference = class _DatabaseReference {
       }
       await this._db._sendTransaction(ops);
     } else {
+      if (this._db.isVolatilePath(this._path)) {
+        this._db._sendVolatileUpdate(this._path, values);
+        return;
+      }
       await this._db._sendUpdate(this._path, values);
     }
   }
   /**
    * Remove the data at this location.
+   *
+   * For volatile paths, this is fire-and-forget.
    */
   async remove() {
+    if (this._db.isVolatilePath(this._path)) {
+      this._db._sendVolatileDelete(this._path);
+      return;
+    }
     await this._db._sendDelete(this._path);
   }
   /**
@@ -1906,10 +2225,14 @@ var DatabaseReference = class _DatabaseReference {
           snapshot: currentSnapshot
         };
       }
-      const ops = [
-        { o: "c", p: this._path, v: currentValue },
-        { o: "s", p: this._path, v: newValue }
-      ];
+      let condition;
+      if (isPrimitive(currentValue)) {
+        condition = { o: "c", p: this._path, v: currentValue };
+      } else {
+        const hash = await hashValue(currentValue);
+        condition = { o: "c", p: this._path, h: hash };
+      }
+      const ops = [condition, { o: "s", p: this._path, v: newValue }];
       try {
         await this._db._sendTransaction(ops);
         const finalSnapshot = await this.once();
@@ -2274,6 +2597,28 @@ function decodeJwtPayload(token) {
   return JSON.parse(decoded);
 }
 
+// src/utils/volatile.ts
+function isVolatilePath(path, patterns) {
+  if (!patterns || patterns.length === 0) {
+    return false;
+  }
+  const segments = path.replace(/^\//, "").split("/").filter((s) => s.length > 0);
+  return patterns.some((pattern) => {
+    const patternSegments = pattern.replace(/^\//, "").split("/").filter((s) => s.length > 0);
+    if (segments.length < patternSegments.length) {
+      return false;
+    }
+    for (let i = 0; i < patternSegments.length; i++) {
+      const p = patternSegments[i];
+      const s = segments[i];
+      if (p !== "*" && p !== s) {
+        return false;
+      }
+    }
+    return true;
+  });
+}
+
 // src/LarkDatabase.ts
 var RECONNECT_BASE_DELAY_MS = 1e3;
 var RECONNECT_MAX_DELAY_MS = 3e4;
@@ -2285,13 +2630,14 @@ var LarkDatabase = class {
     this._databaseId = null;
     this._coordinatorUrl = null;
     this._volatilePaths = [];
+    this._transportType = null;
     // Reconnection state
     this._connectionId = null;
     this._connectOptions = null;
     this._intentionalDisconnect = false;
     this._reconnectAttempt = 0;
     this._reconnectTimer = null;
-    this.ws = null;
+    this.transport = null;
     // Event callbacks
     this.connectCallbacks = /* @__PURE__ */ new Set();
     this.disconnectCallbacks = /* @__PURE__ */ new Set();
@@ -2340,11 +2686,17 @@ var LarkDatabase = class {
   /**
    * Get the volatile path patterns from the server.
    * These patterns indicate which paths should use unreliable transport.
-   * WebSocket always uses reliable transport, but this is stored for future UDP support.
    */
   get volatilePaths() {
     return this._volatilePaths;
   }
+  /**
+   * Get the current transport type.
+   * Returns 'websocket' or 'webtransport', or null if not connected.
+   */
+  get transportType() {
+    return this._transportType;
+  }
   /**
    * Check if there are any pending writes waiting for acknowledgment.
    * Useful for showing "saving..." indicators in UI.
@@ -2398,15 +2750,20 @@ var LarkDatabase = class {
         anonymous: options.anonymous
       });
       const wsUrl = connectResponse.ws_url;
-      this.ws = new WebSocketClient({
-        onMessage: this.handleMessage.bind(this),
-        onOpen: () => {
+      const transportResult = await createTransport(
+        wsUrl,
+        {
+          onMessage: this.handleMessage.bind(this),
+          onOpen: () => {
+          },
+          // Handled in connect flow
+          onClose: this.handleClose.bind(this),
+          onError: this.handleError.bind(this)
         },
-        // Handled in connect flow
-        onClose: this.handleClose.bind(this),
-        onError: this.handleError.bind(this)
-      });
-      await this.ws.connect(wsUrl);
+        { transport: options.transport }
+      );
+      this.transport = transportResult.transport;
+      this._transportType = transportResult.type;
       const requestId = this.messageQueue.nextRequestId();
       const joinMessage = {
         o: "j",
@@ -2450,8 +2807,9 @@ var LarkDatabase = class {
       this._databaseId = null;
       this._connectOptions = null;
       this._connectionId = null;
-      this.ws?.close();
-      this.ws = null;
+      this._transportType = null;
+      this.transport?.close();
+      this.transport = null;
       throw error;
     }
   }
@@ -2469,7 +2827,7 @@ var LarkDatabase = class {
       clearTimeout(this._reconnectTimer);
       this._reconnectTimer = null;
     }
-    if (wasConnected && this.ws) {
+    if (wasConnected && this.transport) {
       try {
         const requestId = this.messageQueue.nextRequestId();
         this.send({ o: "l", r: requestId });
@@ -2490,8 +2848,8 @@ var LarkDatabase = class {
    * Used for intentional disconnect.
    */
   cleanupFull() {
-    this.ws?.close();
-    this.ws = null;
+    this.transport?.close();
+    this.transport = null;
     this._state = "disconnected";
     this._auth = null;
     this._databaseId = null;
@@ -2499,6 +2857,7 @@ var LarkDatabase = class {
     this._coordinatorUrl = null;
     this._connectionId = null;
     this._connectOptions = null;
+    this._transportType = null;
     this._reconnectAttempt = 0;
     this.subscriptionManager.clear();
     this.messageQueue.rejectAll(new Error("Connection closed"));
@@ -2509,8 +2868,8 @@ var LarkDatabase = class {
    * Used for unexpected disconnect.
    */
   cleanupForReconnect() {
-    this.ws?.close();
-    this.ws = null;
+    this.transport?.close();
+    this.transport = null;
     this._auth = null;
     this.subscriptionManager.clearCacheOnly();
     this.messageQueue.rejectAll(new Error("Connection closed"));
@@ -2646,7 +3005,7 @@ var LarkDatabase = class {
   async transaction(operations) {
     let txOps;
     if (Array.isArray(operations)) {
-      txOps = operations.map((op) => this.convertToTxOp(op));
+      txOps = await Promise.all(operations.map((op) => this.convertToTxOp(op)));
     } else {
       txOps = this.convertObjectToTxOps(operations);
     }
@@ -2654,8 +3013,9 @@ var LarkDatabase = class {
   }
   /**
    * Convert a public TransactionOp to wire format TxOperation.
+   * Async because condition operations may require hash computation.
    */
-  convertToTxOp(op) {
+  async convertToTxOp(op) {
     const path = normalizePath(op.path) || "/";
     switch (op.op) {
       case "set":
@@ -2665,7 +3025,12 @@ var LarkDatabase = class {
       case "delete":
         return { o: "d", p: path };
       case "condition":
-        return { o: "c", p: path, v: op.value };
+        if (isPrimitive(op.value)) {
+          return { o: "c", p: path, v: op.value };
+        } else {
+          const hash = await hashValue(op.value);
+          return { o: "c", p: path, h: hash };
+        }
       default:
         throw new Error(`Unknown transaction operation: ${op.op}`);
     }
@@ -2748,7 +3113,7 @@ var LarkDatabase = class {
       return;
     }
     if (isPingMessage(message)) {
-      this.ws?.send(JSON.stringify({ o: "po" }));
+      this.transport?.send(JSON.stringify({ o: "po" }));
       return;
     }
     if (isAckMessage(message)) {
@@ -2815,18 +3180,17 @@ var LarkDatabase = class {
       }
     }
   }
-  handleError(event) {
-    const error = new Error("WebSocket error");
+  handleError(error) {
     this.errorCallbacks.forEach((cb) => cb(error));
   }
   // ============================================
   // Internal: Sending Messages
   // ============================================
   send(message) {
-    if (!this.ws || !this.ws.connected) {
+    if (!this.transport || !this.transport.connected) {
       throw new LarkError("not_connected", "Not connected to database");
     }
-    this.ws.send(JSON.stringify(message));
+    this.transport.send(JSON.stringify(message));
   }
   /**
    * @internal Send a set operation.
@@ -2897,6 +3261,73 @@ var LarkDatabase = class {
     this.send(message);
     await this.messageQueue.registerRequest(requestId);
   }
+  // ============================================
+  // Volatile Write Operations (Fire-and-Forget)
+  // ============================================
+  /**
+   * @internal Send a volatile set operation (fire-and-forget).
+   *
+   * Volatile writes skip:
+   * - Recovery checks (volatile paths don't participate in recovery)
+   * - Request ID generation (no ack expected)
+   * - Pending write tracking (no retry on reconnect)
+   * - pw field (no dependency tracking)
+   *
+   * The write is applied optimistically to local cache for UI feedback,
+   * but we don't await server confirmation.
+   *
+   * When using WebTransport, volatile writes are sent via datagrams (UDP).
+   */
+  _sendVolatileSet(path, value) {
+    const normalizedPath = normalizePath(path) || "/";
+    this.subscriptionManager.applyOptimisticWrite(normalizedPath, value, "", "set");
+    if (!this.transport || !this.transport.connected) {
+      return;
+    }
+    const message = {
+      o: "s",
+      p: normalizedPath,
+      v: value
+    };
+    this.transport.sendVolatile(JSON.stringify(message));
+  }
+  /**
+   * @internal Send a volatile update operation (fire-and-forget).
+   */
+  _sendVolatileUpdate(path, values) {
+    const normalizedPath = normalizePath(path) || "/";
+    this.subscriptionManager.applyOptimisticWrite(normalizedPath, values, "", "update");
+    if (!this.transport || !this.transport.connected) {
+      return;
+    }
+    const message = {
+      o: "u",
+      p: normalizedPath,
+      v: values
+    };
+    this.transport.sendVolatile(JSON.stringify(message));
+  }
+  /**
+   * @internal Send a volatile delete operation (fire-and-forget).
+   */
+  _sendVolatileDelete(path) {
+    const normalizedPath = normalizePath(path) || "/";
+    this.subscriptionManager.applyOptimisticWrite(normalizedPath, null, "", "delete");
+    if (!this.transport || !this.transport.connected) {
+      return;
+    }
+    const message = {
+      o: "d",
+      p: normalizedPath
+    };
+    this.transport.sendVolatile(JSON.stringify(message));
+  }
+  /**
+   * Check if a path is a volatile path (high-frequency, fire-and-forget).
+   */
+  isVolatilePath(path) {
+    return isVolatilePath(path, this._volatilePaths);
+  }
   /**
    * @internal Send a once (read) operation.
    *
@@ -3005,21 +3436,6 @@ var LarkDatabase = class {
     this.subscriptionManager.unsubscribeAll(path);
   }
 };
-
-// src/utils/volatile.ts
-function isVolatilePath(path, patterns) {
-  if (!patterns || patterns.length === 0) {
-    return false;
-  }
-  const segments = path.replace(/^\//, "").split("/");
-  return patterns.some((pattern) => {
-    const patternSegments = pattern.split("/");
-    if (segments.length !== patternSegments.length) {
-      return false;
-    }
-    return patternSegments.every((p, i) => p === "*" || p === segments[i]);
-  });
-}
 export {
   DataSnapshot,
   DatabaseReference,