@lark-sh/client 0.1.21 → 0.1.23

package/README.md

@@ -210,6 +210,46 @@ db.onAuthStateChanged((auth) => {
 });
 ```
 
+### Lazy Connect
+
+You don't need to wait for `connect()` to finish before using the database. Operations called during connection are automatically queued and execute once authenticated:
+
+```typescript
+const db = new LarkDatabase();
+
+// Start connecting (don't await)
+const connectPromise = db.connect('project/db', { anonymous: true });
+
+// These queue and run after auth completes
+db.ref('users').on('value', callback);
+const writePromise = db.ref('data').set({ hello: 'world' });
+
+await connectPromise;
+await writePromise;
+```
+
+### Volatile Paths
+
+Lark supports volatile paths for high-frequency data like player positions or cursors. Volatile paths are defined in your server rules with `.volatile: true` and use fire-and-forget writes for lower latency:
+
+```typescript
+// Check which paths are volatile (set by server rules)
+db.volatilePaths; // e.g. ['players/*/position', 'cursors']
+
+// Writes to volatile paths resolve immediately (no server ack)
+await db.ref('players/abc/position').set({ x: 10, y: 20 });
+
+// Volatile events include a server timestamp for interpolation
+db.ref('players').on('value', (snapshot) => {
+  if (snapshot.isVolatile()) {
+    const ts = snapshot.getServerTimestamp(); // Unix epoch ms
+    // Use deltas between timestamps for smooth interpolation
+  }
+});
+```
+
+When using WebTransport, volatile writes are sent via UDP datagrams for even lower latency. The server batches volatile events at 20Hz over WebTransport vs 7Hz over WebSocket.
+
 ## Firebase v8 Compatibility
 
 For users migrating from Firebase who need exact v8 API behavior, use the `fb-v8` sub-package:

package/dist/{chunk-HHBHX2EM.mjs → chunk-3MBKCYWV.mjs}

@@ -368,9 +368,6 @@ function isEventMessage(msg) {
 function isOnceResponseMessage(msg) {
   return "oc" in msg;
 }
-function isPingMessage(msg) {
-  return "o" in msg && msg.o === "pi";
-}
 
 // src/connection/MessageQueue.ts
 var MessageQueue = class {
@@ -1665,15 +1662,14 @@ var SubscriptionManager = class {
   }
   /**
    * Handle an incoming event message from the server.
-   * Server sends 'put', 'patch', or 'vb' (volatile batch) events; we generate child_* events client-side.
+   * Server sends 'put' or 'patch' events; we generate child_* events client-side.
+   * Volatile events use `x: true` flag on patch events.
    */
   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);
     }
@@ -1746,28 +1742,6 @@ var SubscriptionManager = class {
       this.applyServerUpdateToView(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 }
-   * Dispatches to ALL Views at each subscription path.
-   */
-  handleVolatileBatchEvent(message) {
-    const batch = message.b;
-    const serverTimestamp = message.ts;
-    if (!batch) return;
-    for (const [subscriptionPath, updates] of Object.entries(batch)) {
-      const views = this.getViewsAtPath(subscriptionPath);
-      if (views.length === 0) continue;
-      const updatesList = [];
-      for (const [relativePath, value] of Object.entries(updates)) {
-        updatesList.push({ relativePath, value });
-      }
-      for (const view of views) {
-        this.applyServerUpdateToView(view, updatesList, true, serverTimestamp);
-      }
-    }
-  }
   /**
    * Detect and fire child_moved events for children that changed position OR sort value.
    *
@@ -4233,7 +4207,7 @@ var ServerValue = {
    */
   increment: (delta) => ({ ".sv": { increment: delta } })
 };
-var LarkDatabase = class {
+var _LarkDatabase = class _LarkDatabase {
   /**
    * Create a new LarkDatabase instance.
    *
@@ -4276,6 +4250,7 @@ var LarkDatabase = class {
     // Connection promise - shared by connect() and lazy operations
     this._connectionPromise = null;
     this._serverTimeOffset = 0;
+    this._pingInterval = null;
     this.messageQueue = new MessageQueue();
     this.subscriptionManager = new SubscriptionManager();
     this.pendingWrites = new PendingWriteManager();
@@ -4473,6 +4448,7 @@ var LarkDatabase = class {
       };
       this._state = "authenticated";
       this._reconnectAttempt = 0;
+      this.startPingInterval();
       this.fireConnectionStateChange();
       if (isReconnect) {
         await this.restoreAfterReconnect();
@@ -4562,6 +4538,7 @@ var LarkDatabase = class {
    */
   cleanupFull() {
     const wasAuthenticated = this._state === "authenticated";
+    this.stopPingInterval();
     this.transport?.close();
     this.transport = null;
     this._state = "disconnected";
@@ -4584,6 +4561,7 @@ var LarkDatabase = class {
    * Used for unexpected disconnect.
    */
   cleanupForReconnect() {
+    this.stopPingInterval();
     this.transport?.close();
     this.transport = null;
     this._auth = null;
@@ -4591,6 +4569,21 @@ var LarkDatabase = class {
     this.messageQueue.rejectAll(new Error("Connection closed"));
     this.fireConnectionStateChange();
   }
+  startPingInterval() {
+    this.stopPingInterval();
+    this._pingInterval = _LarkDatabase._realSetInterval(() => {
+      this.transport?.send(JSON.stringify({ o: "pi" }));
+    }, 1e4);
+    if (typeof this._pingInterval === "object" && "unref" in this._pingInterval) {
+      this._pingInterval.unref();
+    }
+  }
+  stopPingInterval() {
+    if (this._pingInterval) {
+      _LarkDatabase._realClearInterval(this._pingInterval);
+      this._pingInterval = null;
+    }
+  }
   // ============================================
   // .info Path Handling
   // ============================================
@@ -4973,10 +4966,6 @@ var LarkDatabase = class {
     if (process.env.LARK_DEBUG) {
       console.log("[LARK] <<< SERVER:", JSON.stringify(message, null, 2));
     }
-    if (isPingMessage(message)) {
-      this.transport?.send(JSON.stringify({ o: "po" }));
-      return;
-    }
     if (isAckMessage(message)) {
       this.pendingWrites.onAck(message.a);
       this.subscriptionManager.clearPendingWrite(message.a);
@@ -5330,7 +5319,11 @@ var LarkDatabase = class {
  * Server values that are resolved by the server when a write is committed.
  * Alias for the exported ServerValue object.
  */
-LarkDatabase.ServerValue = ServerValue;
+_LarkDatabase.ServerValue = ServerValue;
+// Use real timers for ping so fake timers in tests don't cause infinite loops
+_LarkDatabase._realSetInterval = globalThis.setInterval;
+_LarkDatabase._realClearInterval = globalThis.clearInterval;
+var LarkDatabase = _LarkDatabase;
 
 export {
   LarkError,
@@ -5344,4 +5337,4 @@ export {
   ServerValue,
   LarkDatabase
 };
-//# sourceMappingURL=chunk-HHBHX2EM.mjs.map
+//# sourceMappingURL=chunk-3MBKCYWV.mjs.map