@lark-sh/client 0.1.22 → 0.1.24

package/README.md

@@ -13,7 +13,7 @@ JavaScript/TypeScript client for [Lark](https://lark.sh) - a real-time database
 - **Local-first writes** - Optimistic updates appear instantly
 - **Works everywhere** - Browsers and Node.js
 - **TypeScript support** - Full type definitions included
-- **~10KB gzipped** - Lightweight bundle
+- **~20KB gzipped** - Lightweight bundle
 
 ## Installation
 
@@ -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-T5RXZAER.mjs → chunk-MTT7WQB4.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 {
@@ -4210,7 +4207,7 @@ var ServerValue = {
    */
   increment: (delta) => ({ ".sv": { increment: delta } })
 };
-var LarkDatabase = class {
+var _LarkDatabase = class _LarkDatabase {
   /**
    * Create a new LarkDatabase instance.
    *
@@ -4253,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();
@@ -4450,6 +4448,7 @@ var LarkDatabase = class {
       };
       this._state = "authenticated";
       this._reconnectAttempt = 0;
+      this.startPingInterval();
       this.fireConnectionStateChange();
       if (isReconnect) {
         await this.restoreAfterReconnect();
@@ -4539,6 +4538,7 @@ var LarkDatabase = class {
    */
   cleanupFull() {
     const wasAuthenticated = this._state === "authenticated";
+    this.stopPingInterval();
     this.transport?.close();
     this.transport = null;
     this._state = "disconnected";
@@ -4561,6 +4561,7 @@ var LarkDatabase = class {
    * Used for unexpected disconnect.
    */
   cleanupForReconnect() {
+    this.stopPingInterval();
     this.transport?.close();
     this.transport = null;
     this._auth = null;
@@ -4568,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
   // ============================================
@@ -4950,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);
@@ -5307,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.bind(globalThis);
+_LarkDatabase._realClearInterval = globalThis.clearInterval.bind(globalThis);
+var LarkDatabase = _LarkDatabase;
 
 export {
   LarkError,
@@ -5321,4 +5337,4 @@ export {
   ServerValue,
   LarkDatabase
 };
-//# sourceMappingURL=chunk-T5RXZAER.mjs.map
+//# sourceMappingURL=chunk-MTT7WQB4.mjs.map