@lark-sh/client 0.1.4 → 0.1.5

package/dist/index.mjs

@@ -5,17 +5,14 @@ var OnDisconnectAction = {
   DELETE: "d",
   CANCEL: "c"
 };
-var eventTypeFromShort = {
-  v: "value",
-  ca: "child_added",
-  cc: "child_changed",
-  cr: "child_removed"
-};
-var eventTypeToShort = {
-  value: "v",
-  child_added: "ca",
-  child_changed: "cc",
-  child_removed: "cr"
+var ErrorCode = {
+  PERMISSION_DENIED: "permission_denied",
+  INVALID_DATA: "invalid_data",
+  NOT_FOUND: "not_found",
+  INVALID_PATH: "invalid_path",
+  INVALID_OPERATION: "invalid_operation",
+  INTERNAL_ERROR: "internal_error",
+  CONDITION_FAILED: "condition_failed"
 };
 var DEFAULT_COORDINATOR_URL = "https://db.lark.sh";
 
@@ -202,6 +199,91 @@ var MessageQueue = class {
   }
 };
 
+// src/connection/PendingWriteManager.ts
+var PendingWriteManager = class {
+  constructor() {
+    this.pending = /* @__PURE__ */ new Map();
+    this.counter = 0;
+  }
+  /**
+   * Generate a unique operation ID.
+   * Format: op_{timestamp}_{counter}_{random}
+   */
+  generateOid() {
+    this.counter++;
+    const random = Math.random().toString(36).slice(2, 8);
+    return `op_${Date.now()}_${this.counter}_${random}`;
+  }
+  /**
+   * Track a new pending write operation.
+   */
+  trackWrite(oid, operation, path, value) {
+    this.pending.set(oid, {
+      oid,
+      operation,
+      path,
+      value,
+      timestamp: Date.now()
+    });
+  }
+  /**
+   * Called when a write is acknowledged by the server.
+   * Removes the write from pending tracking.
+   */
+  onAck(oid) {
+    return this.pending.delete(oid);
+  }
+  /**
+   * Called when a write is rejected by the server.
+   * Removes the write from pending tracking.
+   */
+  onNack(oid) {
+    return this.pending.delete(oid);
+  }
+  /**
+   * Get all pending writes for retry on reconnect.
+   * Returns writes in order of their timestamps (oldest first).
+   */
+  getPendingWrites() {
+    const writes = Array.from(this.pending.values());
+    writes.sort((a, b) => a.timestamp - b.timestamp);
+    return writes;
+  }
+  /**
+   * Check if a specific operation is still pending.
+   */
+  isPending(oid) {
+    return this.pending.has(oid);
+  }
+  /**
+   * Get the number of pending writes.
+   */
+  get pendingCount() {
+    return this.pending.size;
+  }
+  /**
+   * Clear all pending writes (e.g., on disconnect when not retrying).
+   */
+  clear() {
+    this.pending.clear();
+  }
+  /**
+   * Remove writes older than a specified age (in milliseconds).
+   * Useful for cleaning up stale pending writes that may never be acked.
+   */
+  removeStale(maxAgeMs) {
+    const cutoff = Date.now() - maxAgeMs;
+    let removed = 0;
+    for (const [oid, write] of this.pending) {
+      if (write.timestamp < cutoff) {
+        this.pending.delete(oid);
+        removed++;
+      }
+    }
+    return removed;
+  }
+};
+
 // src/utils/path.ts
 function normalizePath(path) {
   if (!path || path === "/") return "/";
@@ -356,6 +438,8 @@ var DataCache = class {
    *
    * E.g., if /boxes is cached and /boxes/5 changes:
    * - Update the /boxes cache to reflect the new /boxes/5 value
+   *
+   * If an ancestor is null, it creates a new object to hold the child.
    */
   updateChild(path, value) {
     const normalized = normalizePath(path);
@@ -365,22 +449,17 @@ var DataCache = class {
       const ancestorPath = "/" + segments.slice(0, i).join("/");
       if (this.cache.has(ancestorPath)) {
         const ancestorValue = this.cache.get(ancestorPath);
-        if (ancestorValue !== null && typeof ancestorValue === "object") {
-          const childKey = segments[i];
-          const remainingPath = "/" + segments.slice(i).join("/");
-          const updatedAncestor = this.deepClone(ancestorValue);
-          setValueAtPath(updatedAncestor, remainingPath, value);
-          this.cache.set(ancestorPath, updatedAncestor);
-        }
+        const baseValue = ancestorValue !== null && typeof ancestorValue === "object" ? this.deepClone(ancestorValue) : {};
+        const remainingPath = "/" + segments.slice(i).join("/");
+        setValueAtPath(baseValue, remainingPath, value);
+        this.cache.set(ancestorPath, baseValue);
       }
     }
     if (this.cache.has("/") && normalized !== "/") {
       const rootValue = this.cache.get("/");
-      if (rootValue !== null && typeof rootValue === "object") {
-        const updatedRoot = this.deepClone(rootValue);
-        setValueAtPath(updatedRoot, normalized, value);
-        this.cache.set("/", updatedRoot);
-      }
+      const baseValue = rootValue !== null && typeof rootValue === "object" ? this.deepClone(rootValue) : {};
+      setValueAtPath(baseValue, normalized, value);
+      this.cache.set("/", baseValue);
     }
   }
   /**
@@ -433,10 +512,15 @@ var DataCache = class {
 // src/connection/SubscriptionManager.ts
 var SubscriptionManager = class {
   constructor() {
-    // path -> eventType -> array of subscriptions
+    // subscriptionPath -> eventType -> array of subscriptions
     this.subscriptions = /* @__PURE__ */ new Map();
+    // Ordered child keys for each subscription path (for ordered queries)
+    // subscriptionPath -> ordered array of child keys
+    this.orderedChildren = /* @__PURE__ */ new Map();
     // Callback to send subscribe message to server
     this.sendSubscribe = null;
+    // Query params for each subscription path
+    this.queryParams = /* @__PURE__ */ new Map();
     // Callback to send unsubscribe message to server
     this.sendUnsubscribe = null;
     // Callback to create DataSnapshot from event data
@@ -455,7 +539,7 @@ var SubscriptionManager = class {
    * Subscribe to events at a path.
    * Returns an unsubscribe function.
    */
-  subscribe(path, eventType, callback) {
+  subscribe(path, eventType, callback, queryParams) {
     const normalizedPath = path;
     const isFirstForPath = !this.subscriptions.has(normalizedPath);
     const existingEventTypes = this.getEventTypesForPath(normalizedPath);
@@ -468,14 +552,17 @@ var SubscriptionManager = class {
       pathSubs.set(eventType, []);
     }
     const eventSubs = pathSubs.get(eventType);
+    if (isFirstForPath && queryParams) {
+      this.queryParams.set(normalizedPath, queryParams);
+    }
     const unsubscribe = () => {
       this.unsubscribeCallback(normalizedPath, eventType, callback);
     };
     eventSubs.push({ callback, unsubscribe });
     if (isFirstForPath || isFirstForEventType) {
       const allEventTypes = this.getEventTypesForPath(normalizedPath);
-      const shortEventTypes = allEventTypes.map((et) => eventTypeToShort[et]);
-      this.sendSubscribe?.(normalizedPath, shortEventTypes).catch((err) => {
+      const storedQueryParams = this.queryParams.get(normalizedPath);
+      this.sendSubscribe?.(normalizedPath, allEventTypes, storedQueryParams).catch((err) => {
         console.error("Failed to subscribe:", err);
       });
     }
@@ -498,6 +585,9 @@ var SubscriptionManager = class {
     }
     if (pathSubs.size === 0) {
       this.subscriptions.delete(path);
+      this.orderedChildren.delete(path);
+      this.queryParams.delete(path);
+      this.cache.deleteTree(path);
       this.sendUnsubscribe?.(path).catch((err) => {
         console.error("Failed to unsubscribe:", err);
       });
@@ -513,13 +603,16 @@ var SubscriptionManager = class {
     pathSubs.delete(eventType);
     if (pathSubs.size === 0) {
       this.subscriptions.delete(normalizedPath);
+      this.orderedChildren.delete(normalizedPath);
+      this.queryParams.delete(normalizedPath);
+      this.cache.deleteTree(normalizedPath);
       this.sendUnsubscribe?.(normalizedPath).catch((err) => {
         console.error("Failed to unsubscribe:", err);
       });
     } else {
       const remainingEventTypes = this.getEventTypesForPath(normalizedPath);
-      const shortEventTypes = remainingEventTypes.map((et) => eventTypeToShort[et]);
-      this.sendSubscribe?.(normalizedPath, shortEventTypes).catch((err) => {
+      const storedQueryParams = this.queryParams.get(normalizedPath);
+      this.sendSubscribe?.(normalizedPath, remainingEventTypes, storedQueryParams).catch((err) => {
         console.error("Failed to update subscription:", err);
       });
     }
@@ -531,49 +624,347 @@ var SubscriptionManager = class {
     const normalizedPath = path;
     if (!this.subscriptions.has(normalizedPath)) return;
     this.subscriptions.delete(normalizedPath);
+    this.orderedChildren.delete(normalizedPath);
+    this.queryParams.delete(normalizedPath);
+    this.cache.deleteTree(normalizedPath);
     this.sendUnsubscribe?.(normalizedPath).catch((err) => {
       console.error("Failed to unsubscribe:", err);
     });
   }
   /**
    * Handle an incoming event message from the server.
+   * Server sends 'put' or 'patch' events; we generate child_* events client-side.
    */
   handleEvent(message) {
-    const eventType = eventTypeFromShort[message.ev];
-    if (!eventType) {
+    if (message.ev === "put") {
+      this.handlePutEvent(message);
+    } else if (message.ev === "patch") {
+      this.handlePatchEvent(message);
+    } else {
       console.warn("Unknown event type:", message.ev);
-      return;
     }
-    const path = message.p;
-    const pathSubs = this.subscriptions.get(path);
+  }
+  /**
+   * Handle a 'put' event - single path change.
+   */
+  handlePutEvent(message) {
+    const subscriptionPath = message.sp;
+    const relativePath = message.p;
+    const value = message.v;
+    const isVolatile = message.x ?? false;
+    const serverTimestamp = message.ts;
+    const afterKey = message.ak;
+    const orderedKeys = message.k;
+    const pathSubs = this.subscriptions.get(subscriptionPath);
     if (!pathSubs) return;
-    const eventSubs = pathSubs.get(eventType);
-    if (!eventSubs || eventSubs.length === 0) return;
-    let snapshotPath;
-    let snapshotValue;
-    if (eventType === "value") {
-      snapshotPath = path;
-      snapshotValue = message.v;
-      this.cache.set(path, snapshotValue);
-    } else if (eventType === "child_added" || eventType === "child_changed") {
-      snapshotPath = path === "/" ? `/${message.k}` : `${path}/${message.k}`;
-      snapshotValue = message.v;
-      this.cache.updateChild(snapshotPath, snapshotValue);
-    } else if (eventType === "child_removed") {
-      snapshotPath = path === "/" ? `/${message.k}` : `${path}/${message.k}`;
-      snapshotValue = message.v;
-      this.cache.removeChild(snapshotPath);
+    const absolutePath = relativePath === "/" ? subscriptionPath : joinPath(subscriptionPath, relativePath);
+    const previousOrder = this.orderedChildren.get(subscriptionPath) ?? [];
+    const previousChildSet = new Set(previousOrder);
+    if (value !== void 0) {
+      if (relativePath === "/") {
+        this.cache.set(subscriptionPath, value);
+      } else if (value === null) {
+        this.cache.removeChild(absolutePath);
+      } else {
+        this.cache.updateChild(absolutePath, value);
+      }
+    }
+    if (relativePath === "/") {
+      if (orderedKeys) {
+        this.orderedChildren.set(subscriptionPath, [...orderedKeys]);
+      } else if (value && typeof value === "object" && value !== null) {
+        this.orderedChildren.set(subscriptionPath, Object.keys(value));
+      } else {
+        this.orderedChildren.set(subscriptionPath, []);
+      }
     } else {
-      snapshotPath = path === "/" ? `/${message.k}` : `${path}/${message.k}`;
-      snapshotValue = message.v;
+      const segments = relativePath.split("/").filter((s) => s.length > 0);
+      if (segments.length > 0) {
+        const childKey = segments[0];
+        const currentOrder2 = this.orderedChildren.get(subscriptionPath) ?? [];
+        if (value === null) {
+          const newOrder = currentOrder2.filter((k) => k !== childKey);
+          this.orderedChildren.set(subscriptionPath, newOrder);
+        } else if (!previousChildSet.has(childKey)) {
+          const newOrder = [...currentOrder2];
+          this.insertAfterKey(newOrder, childKey, afterKey);
+          this.orderedChildren.set(subscriptionPath, newOrder);
+        }
+      }
     }
-    const snapshot = this.createSnapshot?.(snapshotPath, snapshotValue, message.x ?? false);
-    if (!snapshot) return;
-    for (const entry of eventSubs) {
-      try {
-        entry.callback(snapshot, void 0);
-      } catch (err) {
-        console.error("Error in subscription callback:", err);
+    const currentOrder = this.orderedChildren.get(subscriptionPath) ?? [];
+    const currentChildSet = new Set(currentOrder);
+    this.fireCallbacks(
+      subscriptionPath,
+      pathSubs,
+      relativePath,
+      value,
+      previousOrder,
+      currentOrder,
+      previousChildSet,
+      currentChildSet,
+      afterKey,
+      isVolatile,
+      serverTimestamp
+    );
+  }
+  /**
+   * Handle a 'patch' event - multi-path change and/or moves.
+   */
+  handlePatchEvent(message) {
+    const subscriptionPath = message.sp;
+    const basePath = message.p;
+    const patches = message.v;
+    const moves = message.mv;
+    const orderedKeys = message.k;
+    const isVolatile = message.x ?? false;
+    const serverTimestamp = message.ts;
+    const pathSubs = this.subscriptions.get(subscriptionPath);
+    if (!pathSubs) return;
+    const previousOrder = this.orderedChildren.get(subscriptionPath) ?? [];
+    const previousChildSet = new Set(previousOrder);
+    const affectedChildren = /* @__PURE__ */ new Set();
+    if (patches) {
+      for (const [relativePath, value] of Object.entries(patches)) {
+        const fullRelativePath = basePath === "/" ? "/" + relativePath : joinPath(basePath, relativePath);
+        const absolutePath = joinPath(subscriptionPath, fullRelativePath);
+        const segments = fullRelativePath.split("/").filter((s) => s.length > 0);
+        if (segments.length > 0) {
+          affectedChildren.add(segments[0]);
+        }
+        if (value === null) {
+          this.cache.removeChild(absolutePath);
+        } else {
+          this.cache.updateChild(absolutePath, value);
+        }
+      }
+    }
+    if (moves && moves.length > 0) {
+      this.handleMoves(subscriptionPath, pathSubs, moves, isVolatile, serverTimestamp);
+    }
+    if (orderedKeys) {
+      this.orderedChildren.set(subscriptionPath, [...orderedKeys]);
+    }
+    const currentOrder = this.orderedChildren.get(subscriptionPath) ?? [];
+    const currentChildSet = new Set(currentOrder);
+    const valueSubs = pathSubs.get("value");
+    if (valueSubs && valueSubs.length > 0) {
+      const fullValue = this.cache.get(subscriptionPath).value;
+      const snapshot = this.createSnapshot?.(subscriptionPath, fullValue, isVolatile, serverTimestamp);
+      if (snapshot) {
+        for (const entry of valueSubs) {
+          try {
+            entry.callback(snapshot, void 0);
+          } catch (err) {
+            console.error("Error in value subscription callback:", err);
+          }
+        }
+      }
+    }
+    if (patches && affectedChildren.size > 0) {
+      const childAddedSubs = pathSubs.get("child_added") ?? [];
+      const childChangedSubs = pathSubs.get("child_changed") ?? [];
+      const childRemovedSubs = pathSubs.get("child_removed") ?? [];
+      for (const childKey of affectedChildren) {
+        const wasPresent = previousChildSet.has(childKey);
+        const isPresent = currentChildSet.has(childKey);
+        if (!wasPresent && isPresent) {
+          const prevKey = this.getPreviousChildKey(currentOrder, childKey);
+          this.fireChildAdded(subscriptionPath, childKey, childAddedSubs, prevKey, isVolatile, serverTimestamp);
+        } else if (wasPresent && !isPresent) {
+          this.fireChildRemoved(subscriptionPath, childKey, childRemovedSubs, isVolatile, serverTimestamp);
+        } else if (wasPresent && isPresent) {
+          const prevKey = this.getPreviousChildKey(currentOrder, childKey);
+          this.fireChildChanged(subscriptionPath, childKey, childChangedSubs, prevKey, isVolatile, serverTimestamp);
+        }
+      }
+    }
+  }
+  /**
+   * Handle moves array - update order and fire child_moved events.
+   */
+  handleMoves(subscriptionPath, pathSubs, moves, isVolatile, serverTimestamp) {
+    const childMovedSubs = pathSubs.get("child_moved") ?? [];
+    const currentOrder = this.orderedChildren.get(subscriptionPath) ?? [];
+    for (const move of moves) {
+      const { k: childKey, ak: afterKey } = move;
+      const idx = currentOrder.indexOf(childKey);
+      if (idx !== -1) {
+        currentOrder.splice(idx, 1);
+      }
+      this.insertAfterKey(currentOrder, childKey, afterKey);
+      if (childMovedSubs.length > 0) {
+        const previousChildKey = afterKey === "" ? null : afterKey;
+        this.fireChildMoved(subscriptionPath, childKey, childMovedSubs, previousChildKey, isVolatile, serverTimestamp);
+      }
+    }
+    this.orderedChildren.set(subscriptionPath, currentOrder);
+  }
+  /**
+   * Insert a key into an ordered array after a specific key.
+   * If afterKey is empty string or undefined, insert at beginning.
+   * If afterKey is not found, append at end.
+   */
+  insertAfterKey(order, key, afterKey) {
+    if (afterKey === "" || afterKey === void 0) {
+      order.unshift(key);
+    } else {
+      const afterIdx = order.indexOf(afterKey);
+      if (afterIdx === -1) {
+        order.push(key);
+      } else {
+        order.splice(afterIdx + 1, 0, key);
+      }
+    }
+  }
+  /**
+   * Get the previous sibling key for a given key in the ordered array.
+   */
+  getPreviousChildKey(order, key) {
+    const idx = order.indexOf(key);
+    if (idx <= 0) return null;
+    return order[idx - 1];
+  }
+  /**
+   * Fire callbacks for subscribed event types.
+   */
+  fireCallbacks(subscriptionPath, pathSubs, relativePath, value, previousOrder, currentOrder, previousChildSet, currentChildSet, afterKey, isVolatile, serverTimestamp) {
+    const valueSubs = pathSubs.get("value");
+    if (valueSubs && valueSubs.length > 0) {
+      const fullValue = this.cache.get(subscriptionPath).value;
+      const snapshot = this.createSnapshot?.(subscriptionPath, fullValue, isVolatile, serverTimestamp);
+      if (snapshot) {
+        for (const entry of valueSubs) {
+          try {
+            entry.callback(snapshot, void 0);
+          } catch (err) {
+            console.error("Error in value subscription callback:", err);
+          }
+        }
+      }
+    }
+    this.fireChildEvents(
+      subscriptionPath,
+      pathSubs,
+      relativePath,
+      value,
+      previousOrder,
+      currentOrder,
+      previousChildSet,
+      currentChildSet,
+      afterKey,
+      isVolatile,
+      serverTimestamp
+    );
+  }
+  /**
+   * Generate and fire child_added, child_changed, child_removed events.
+   * child_moved is handled separately via handleMoves().
+   */
+  fireChildEvents(subscriptionPath, pathSubs, relativePath, value, previousOrder, currentOrder, previousChildSet, currentChildSet, afterKey, isVolatile, serverTimestamp) {
+    const childAddedSubs = pathSubs.get("child_added") ?? [];
+    const childChangedSubs = pathSubs.get("child_changed") ?? [];
+    const childRemovedSubs = pathSubs.get("child_removed") ?? [];
+    if (childAddedSubs.length === 0 && childChangedSubs.length === 0 && childRemovedSubs.length === 0) {
+      return;
+    }
+    if (relativePath === "/") {
+      for (const key of currentOrder) {
+        if (!previousChildSet.has(key)) {
+          const prevKey = this.getPreviousChildKey(currentOrder, key);
+          this.fireChildAdded(subscriptionPath, key, childAddedSubs, prevKey, isVolatile, serverTimestamp);
+        }
+      }
+      for (const key of previousOrder) {
+        if (!currentChildSet.has(key)) {
+          this.fireChildRemoved(subscriptionPath, key, childRemovedSubs, isVolatile, serverTimestamp);
+        }
+      }
+    } else {
+      const segments = relativePath.split("/").filter((s) => s.length > 0);
+      if (segments.length === 0) return;
+      const childKey = segments[0];
+      if (value === null) {
+        if (previousChildSet.has(childKey) && !currentChildSet.has(childKey)) {
+          this.fireChildRemoved(subscriptionPath, childKey, childRemovedSubs, isVolatile, serverTimestamp);
+        }
+      } else if (!previousChildSet.has(childKey)) {
+        const prevKey = afterKey !== void 0 ? afterKey === "" ? null : afterKey : this.getPreviousChildKey(currentOrder, childKey);
+        this.fireChildAdded(subscriptionPath, childKey, childAddedSubs, prevKey, isVolatile, serverTimestamp);
+      } else {
+        const prevKey = this.getPreviousChildKey(currentOrder, childKey);
+        this.fireChildChanged(subscriptionPath, childKey, childChangedSubs, prevKey, isVolatile, serverTimestamp);
+      }
+    }
+  }
+  /**
+   * Fire child_added callbacks for a child key.
+   */
+  fireChildAdded(subscriptionPath, childKey, subs, previousChildKey, isVolatile, serverTimestamp) {
+    if (subs.length === 0) return;
+    const childPath = joinPath(subscriptionPath, childKey);
+    const childValue = this.cache.get(childPath).value;
+    const snapshot = this.createSnapshot?.(childPath, childValue, isVolatile, serverTimestamp);
+    if (snapshot) {
+      for (const entry of subs) {
+        try {
+          entry.callback(snapshot, previousChildKey);
+        } catch (err) {
+          console.error("Error in child_added subscription callback:", err);
+        }
+      }
+    }
+  }
+  /**
+   * Fire child_changed callbacks for a child key.
+   */
+  fireChildChanged(subscriptionPath, childKey, subs, previousChildKey, isVolatile, serverTimestamp) {
+    if (subs.length === 0) return;
+    const childPath = joinPath(subscriptionPath, childKey);
+    const childValue = this.cache.get(childPath).value;
+    const snapshot = this.createSnapshot?.(childPath, childValue, isVolatile, serverTimestamp);
+    if (snapshot) {
+      for (const entry of subs) {
+        try {
+          entry.callback(snapshot, previousChildKey);
+        } catch (err) {
+          console.error("Error in child_changed subscription callback:", err);
+        }
+      }
+    }
+  }
+  /**
+   * Fire child_removed callbacks for a child key.
+   */
+  fireChildRemoved(subscriptionPath, childKey, subs, isVolatile, serverTimestamp) {
+    if (subs.length === 0) return;
+    const childPath = joinPath(subscriptionPath, childKey);
+    const snapshot = this.createSnapshot?.(childPath, null, isVolatile, serverTimestamp);
+    if (snapshot) {
+      for (const entry of subs) {
+        try {
+          entry.callback(snapshot, void 0);
+        } catch (err) {
+          console.error("Error in child_removed subscription callback:", err);
+        }
+      }
+    }
+  }
+  /**
+   * Fire child_moved callbacks for a child key.
+   */
+  fireChildMoved(subscriptionPath, childKey, subs, previousChildKey, isVolatile, serverTimestamp) {
+    if (subs.length === 0) return;
+    const childPath = joinPath(subscriptionPath, childKey);
+    const childValue = this.cache.get(childPath).value;
+    const snapshot = this.createSnapshot?.(childPath, childValue, isVolatile, serverTimestamp);
+    if (snapshot) {
+      for (const entry of subs) {
+        try {
+          entry.callback(snapshot, previousChildKey);
+        } catch (err) {
+          console.error("Error in child_moved subscription callback:", err);
+        }
       }
     }
   }
@@ -590,6 +981,8 @@ var SubscriptionManager = class {
    */
   clear() {
     this.subscriptions.clear();
+    this.orderedChildren.clear();
+    this.queryParams.clear();
     this.cache.clear();
   }
   /**
@@ -833,6 +1226,7 @@ function generatePushId() {
 }
 
 // src/DatabaseReference.ts
+var DEFAULT_MAX_RETRIES = 25;
 var DatabaseReference = class _DatabaseReference {
   constructor(db, path, query = {}) {
     this._db = db;
@@ -886,9 +1280,40 @@ var DatabaseReference = class _DatabaseReference {
   }
   /**
    * Update specific children at this location without overwriting other children.
+   *
+   * Also supports Firebase-style multi-path updates when keys look like paths
+   * (start with '/'). In this mode, each path is written atomically as a transaction.
+   *
+   * @example
+   * ```javascript
+   * // Normal update (merge at single path)
+   * await ref.update({ score: 10, name: 'Riley' });
+   *
+   * // Multi-path update (atomic writes to multiple paths)
+   * await db.ref().update({
+   *   '/users/alice/score': 100,
+   *   '/users/bob/score': 200,
+   *   '/leaderboard/alice': null  // null = delete
+   * });
+   * ```
    */
   async update(values) {
-    await this._db._sendUpdate(this._path, values);
+    const hasPathKeys = Object.keys(values).some((key) => key.startsWith("/"));
+    if (hasPathKeys) {
+      const ops = [];
+      for (const [key, value] of Object.entries(values)) {
+        const fullPath = key.startsWith("/") ? joinPath(this._path, key) : joinPath(this._path, key);
+        const normalizedPath = normalizePath(fullPath) || "/";
+        if (value === null) {
+          ops.push({ o: "d", p: normalizedPath });
+        } else {
+          ops.push({ o: "s", p: normalizedPath, v: value });
+        }
+      }
+      await this._db._sendTransaction(ops);
+    } else {
+      await this._db._sendUpdate(this._path, values);
+    }
   }
   /**
    * Remove the data at this location.
@@ -928,6 +1353,64 @@ var DatabaseReference = class _DatabaseReference {
     const snapshot = await this.once();
     await this.setWithPriority(snapshot.val(), priority);
   }
+  /**
+   * Atomically modify the data at this location using optimistic concurrency.
+   *
+   * The update function receives the current value and should return the new
+   * value. If the data changed on the server before the write could be
+   * committed, the function is called again with the new value, and the
+   * process repeats until successful or the maximum retries are exceeded.
+   *
+   * @example
+   * ```javascript
+   * // Increment a counter atomically
+   * const result = await ref.transaction(currentValue => {
+   *   return (currentValue || 0) + 1;
+   * });
+   * console.log('New value:', result.snapshot.val());
+   * ```
+   *
+   * @param updateFunction - Function that receives current value and returns new value.
+   *                         Return undefined to abort the transaction.
+   * @param maxRetries - Maximum number of retries (default: 25)
+   * @returns TransactionResult with committed status and final snapshot
+   */
+  async transaction(updateFunction, maxRetries = DEFAULT_MAX_RETRIES) {
+    let retries = 0;
+    while (retries < maxRetries) {
+      const currentSnapshot = await this.once();
+      const currentValue = currentSnapshot.val();
+      const newValue = updateFunction(currentValue);
+      if (newValue === void 0) {
+        return {
+          committed: false,
+          snapshot: currentSnapshot
+        };
+      }
+      const ops = [
+        { o: "c", p: this._path, v: currentValue },
+        { o: "s", p: this._path, v: newValue }
+      ];
+      try {
+        await this._db._sendTransaction(ops);
+        const finalSnapshot = await this.once();
+        return {
+          committed: true,
+          snapshot: finalSnapshot
+        };
+      } catch (error) {
+        if (error instanceof LarkError && error.code === ErrorCode.CONDITION_FAILED) {
+          retries++;
+          continue;
+        }
+        throw error;
+      }
+    }
+    throw new LarkError(
+      "max_retries_exceeded",
+      `Transaction failed after ${maxRetries} retries`
+    );
+  }
   // ============================================
   // Read Operations
   // ============================================
@@ -948,7 +1431,7 @@ var DatabaseReference = class _DatabaseReference {
    * Returns an unsubscribe function.
    */
   on(eventType, callback) {
-    return this._db._subscribe(this._path, eventType, callback);
+    return this._db._subscribe(this._path, eventType, callback, this._buildQueryParams());
   }
   /**
    * Unsubscribe from events.
@@ -994,10 +1477,8 @@ var DatabaseReference = class _DatabaseReference {
   }
   /**
    * Order results by a child key.
-   * NOTE: Phase 2 - not yet implemented on server.
    */
   orderByChild(path) {
-    console.warn("orderByChild() is not yet implemented");
     return new _DatabaseReference(this._db, this._path, {
       ...this._query,
       orderBy: "child",
@@ -1006,10 +1487,8 @@ var DatabaseReference = class _DatabaseReference {
   }
   /**
    * Order results by value.
-   * NOTE: Phase 2 - not yet implemented on server.
    */
   orderByValue() {
-    console.warn("orderByValue() is not yet implemented");
     return new _DatabaseReference(this._db, this._path, {
       ...this._query,
       orderBy: "value"
@@ -1035,10 +1514,8 @@ var DatabaseReference = class _DatabaseReference {
   }
   /**
    * Start at a specific value/key.
-   * NOTE: Phase 2 - not yet implemented on server.
    */
   startAt(value, key) {
-    console.warn("startAt() is not yet implemented");
     return new _DatabaseReference(this._db, this._path, {
       ...this._query,
       startAt: { value, key }
@@ -1046,10 +1523,8 @@ var DatabaseReference = class _DatabaseReference {
   }
   /**
    * End at a specific value/key.
-   * NOTE: Phase 2 - not yet implemented on server.
    */
   endAt(value, key) {
-    console.warn("endAt() is not yet implemented");
     return new _DatabaseReference(this._db, this._path, {
       ...this._query,
       endAt: { value, key }
@@ -1057,10 +1532,8 @@ var DatabaseReference = class _DatabaseReference {
   }
   /**
    * Filter to items equal to a specific value.
-   * NOTE: Phase 2 - not yet implemented on server.
    */
   equalTo(value, key) {
-    console.warn("equalTo() is not yet implemented");
     return new _DatabaseReference(this._db, this._path, {
       ...this._query,
       equalTo: { value, key }
@@ -1076,18 +1549,48 @@ var DatabaseReference = class _DatabaseReference {
     const params = {};
     let hasParams = false;
     if (this._query.orderBy === "key") {
-      params.ob = "k";
+      params.orderBy = "key";
       hasParams = true;
     } else if (this._query.orderBy === "priority") {
-      params.ob = "p";
+      params.orderBy = "priority";
+      hasParams = true;
+    } else if (this._query.orderBy === "child") {
+      params.orderBy = "child";
+      if (this._query.orderByChildPath) {
+        params.orderByChild = this._query.orderByChildPath;
+      }
+      hasParams = true;
+    } else if (this._query.orderBy === "value") {
+      params.orderBy = "value";
       hasParams = true;
     }
     if (this._query.limitToFirst !== void 0) {
-      params.lf = this._query.limitToFirst;
+      params.limitToFirst = this._query.limitToFirst;
       hasParams = true;
     }
     if (this._query.limitToLast !== void 0) {
-      params.ll = this._query.limitToLast;
+      params.limitToLast = this._query.limitToLast;
+      hasParams = true;
+    }
+    if (this._query.startAt !== void 0) {
+      params.startAt = this._query.startAt.value;
+      if (this._query.startAt.key !== void 0) {
+        params.startAtKey = this._query.startAt.key;
+      }
+      hasParams = true;
+    }
+    if (this._query.endAt !== void 0) {
+      params.endAt = this._query.endAt.value;
+      if (this._query.endAt.key !== void 0) {
+        params.endAtKey = this._query.endAt.key;
+      }
+      hasParams = true;
+    }
+    if (this._query.equalTo !== void 0) {
+      params.equalTo = this._query.equalTo.value;
+      if (this._query.equalTo.key !== void 0) {
+        params.equalToKey = this._query.equalTo.key;
+      }
       hasParams = true;
     }
     return hasParams ? params : void 0;
@@ -1113,6 +1616,7 @@ var DataSnapshot = class _DataSnapshot {
     this._db = db;
     this._volatile = options.volatile ?? false;
     this._priority = options.priority ?? null;
+    this._serverTimestamp = options.serverTimestamp ?? null;
   }
   /**
    * Get a DatabaseReference for the location of this snapshot.
@@ -1145,7 +1649,8 @@ var DataSnapshot = class _DataSnapshot {
     const childPath = joinPath(this._path, path);
     const childData = getValueAtPath(this._data, path);
     return new _DataSnapshot(childData, childPath, this._db, {
-      volatile: this._volatile
+      volatile: this._volatile,
+      serverTimestamp: this._serverTimestamp
     });
   }
   /**
@@ -1201,6 +1706,15 @@ var DataSnapshot = class _DataSnapshot {
   isVolatile() {
     return this._volatile;
   }
+  /**
+   * Get the server timestamp for this snapshot (milliseconds since Unix epoch).
+   * Only present on volatile value events. Use deltas between timestamps for
+   * interpolation rather than absolute times to avoid clock sync issues.
+   * This is a Lark extension not present in Firebase.
+   */
+  getServerTimestamp() {
+    return this._serverTimestamp;
+  }
   /**
    * Export the snapshot data as JSON (alias for val()).
    */
@@ -1242,6 +1756,7 @@ var LarkDatabase = class {
     this.errorCallbacks = /* @__PURE__ */ new Set();
     this.messageQueue = new MessageQueue();
     this.subscriptionManager = new SubscriptionManager();
+    this.pendingWrites = new PendingWriteManager();
   }
   // ============================================
   // Connection State
@@ -1275,6 +1790,26 @@ var LarkDatabase = class {
   get volatilePaths() {
     return this._volatilePaths;
   }
+  /**
+   * Check if there are any pending writes waiting for acknowledgment.
+   * Useful for showing "saving..." indicators in UI.
+   */
+  hasPendingWrites() {
+    return this.pendingWrites.pendingCount > 0;
+  }
+  /**
+   * Get the number of pending writes waiting for acknowledgment.
+   */
+  getPendingWriteCount() {
+    return this.pendingWrites.pendingCount;
+  }
+  /**
+   * Clear all pending writes.
+   * Call this if you don't want to retry writes on reconnect.
+   */
+  clearPendingWrites() {
+    this.pendingWrites.clear();
+  }
   // ============================================
   // Connection Management
   // ============================================
@@ -1384,6 +1919,96 @@ var LarkDatabase = class {
     return new DatabaseReference(this, path);
   }
   // ============================================
+  // Transactions
+  // ============================================
+  /**
+   * Execute an atomic transaction with multiple operations.
+   *
+   * Supports two syntaxes:
+   *
+   * **Object syntax** (like Firebase multi-path update):
+   * ```javascript
+   * await db.transaction({
+   *   '/users/alice/name': 'Alice',
+   *   '/users/alice/score': 100,
+   *   '/temp/data': null  // null = delete
+   * });
+   * ```
+   *
+   * **Array syntax** (explicit operations):
+   * ```javascript
+   * await db.transaction([
+   *   { op: 'set', path: '/users/alice/name', value: 'Alice' },
+   *   { op: 'update', path: '/metadata', value: { lastUpdated: '...' } },
+   *   { op: 'delete', path: '/temp/data' },
+   *   { op: 'condition', path: '/counter', value: 5 }  // CAS check
+   * ]);
+   * ```
+   *
+   * All operations are atomic: either all succeed or all fail.
+   * Conditions are checked first; if any fail, the transaction is rejected
+   * with error code 'condition_failed'.
+   */
+  async transaction(operations) {
+    let txOps;
+    if (Array.isArray(operations)) {
+      txOps = operations.map((op) => this.convertToTxOp(op));
+    } else {
+      txOps = this.convertObjectToTxOps(operations);
+    }
+    await this._sendTransaction(txOps);
+  }
+  /**
+   * Convert a public TransactionOp to wire format TxOperation.
+   */
+  convertToTxOp(op) {
+    const path = normalizePath(op.path) || "/";
+    switch (op.op) {
+      case "set":
+        return { o: "s", p: path, v: op.value };
+      case "update":
+        return { o: "u", p: path, v: op.value };
+      case "delete":
+        return { o: "d", p: path };
+      case "condition":
+        return { o: "c", p: path, v: op.value };
+      default:
+        throw new Error(`Unknown transaction operation: ${op.op}`);
+    }
+  }
+  /**
+   * Convert object syntax to wire format TxOperations.
+   * Each path becomes a set operation, null values become deletes.
+   */
+  convertObjectToTxOps(obj) {
+    const ops = [];
+    for (const [path, value] of Object.entries(obj)) {
+      const normalizedPath = normalizePath(path) || "/";
+      if (value === null) {
+        ops.push({ o: "d", p: normalizedPath });
+      } else {
+        ops.push({ o: "s", p: normalizedPath, v: value });
+      }
+    }
+    return ops;
+  }
+  /**
+   * @internal Send a transaction to the server.
+   */
+  async _sendTransaction(ops) {
+    const requestId = this.messageQueue.nextRequestId();
+    const oid = this.pendingWrites.generateOid();
+    this.pendingWrites.trackWrite(oid, "transaction", "/", ops);
+    const message = {
+      o: "tx",
+      ops,
+      r: requestId,
+      oid
+    };
+    this.send(message);
+    await this.messageQueue.registerRequest(requestId);
+  }
+  // ============================================
   // Connection Events
   // ============================================
   /**
@@ -1425,6 +2050,11 @@ var LarkDatabase = class {
       this.ws?.send(JSON.stringify({ o: "po" }));
       return;
     }
+    if (isAckMessage(message) && message.oid) {
+      this.pendingWrites.onAck(message.oid);
+    } else if (isNackMessage(message) && message.oid) {
+      this.pendingWrites.onNack(message.oid);
+    }
     if (this.messageQueue.handleMessage(message)) {
       return;
     }
@@ -1457,11 +2087,15 @@ var LarkDatabase = class {
    */
   async _sendSet(path, value, priority) {
     const requestId = this.messageQueue.nextRequestId();
+    const oid = this.pendingWrites.generateOid();
+    const normalizedPath = normalizePath(path) || "/";
+    this.pendingWrites.trackWrite(oid, "set", normalizedPath, value);
     const message = {
       o: "s",
-      p: normalizePath(path) || "/",
+      p: normalizedPath,
       v: value,
-      r: requestId
+      r: requestId,
+      oid
     };
     if (priority !== void 0) {
       message.y = priority;
@@ -1474,11 +2108,15 @@ var LarkDatabase = class {
    */
   async _sendUpdate(path, values) {
     const requestId = this.messageQueue.nextRequestId();
+    const oid = this.pendingWrites.generateOid();
+    const normalizedPath = normalizePath(path) || "/";
+    this.pendingWrites.trackWrite(oid, "update", normalizedPath, values);
     const message = {
       o: "u",
-      p: normalizePath(path) || "/",
+      p: normalizedPath,
       v: values,
-      r: requestId
+      r: requestId,
+      oid
     };
     this.send(message);
     await this.messageQueue.registerRequest(requestId);
@@ -1488,10 +2126,14 @@ var LarkDatabase = class {
    */
   async _sendDelete(path) {
     const requestId = this.messageQueue.nextRequestId();
+    const oid = this.pendingWrites.generateOid();
+    const normalizedPath = normalizePath(path) || "/";
+    this.pendingWrites.trackWrite(oid, "delete", normalizedPath);
     const message = {
       o: "d",
-      p: normalizePath(path) || "/",
-      r: requestId
+      p: normalizedPath,
+      r: requestId,
+      oid
     };
     this.send(message);
     await this.messageQueue.registerRequest(requestId);
@@ -1501,11 +2143,15 @@ var LarkDatabase = class {
    */
   async _sendPush(path, value) {
     const requestId = this.messageQueue.nextRequestId();
+    const oid = this.pendingWrites.generateOid();
+    const normalizedPath = normalizePath(path) || "/";
+    this.pendingWrites.trackWrite(oid, "push", normalizedPath, value);
     const message = {
       o: "p",
-      p: normalizePath(path) || "/",
+      p: normalizedPath,
       v: value,
-      r: requestId
+      r: requestId,
+      oid
     };
     this.send(message);
     const key = await this.messageQueue.registerRequest(requestId);
@@ -1535,11 +2181,10 @@ var LarkDatabase = class {
     const message = {
       o: "o",
       p: normalizedPath,
-      r: requestId
+      r: requestId,
+      // Spread query params at top level (not nested in 'q')
+      ...query
     };
-    if (query) {
-      message.q = query;
-    }
     this.send(message);
     const value = await this.messageQueue.registerRequest(requestId);
     return new DataSnapshot(value, path, this);
@@ -1567,13 +2212,14 @@ var LarkDatabase = class {
   /**
    * @internal Send a subscribe message to server.
    */
-  async sendSubscribeMessage(path, eventTypes) {
+  async sendSubscribeMessage(path, eventTypes, queryParams) {
     const requestId = this.messageQueue.nextRequestId();
     const message = {
       o: "sb",
       p: normalizePath(path) || "/",
       e: eventTypes,
-      r: requestId
+      r: requestId,
+      ...queryParams
     };
     this.send(message);
     await this.messageQueue.registerRequest(requestId);
@@ -1594,8 +2240,11 @@ var LarkDatabase = class {
   /**
    * @internal Create a DataSnapshot from event data.
    */
-  createSnapshot(path, value, volatile) {
-    return new DataSnapshot(value, path, this, { volatile });
+  createSnapshot(path, value, volatile, serverTimestamp) {
+    return new DataSnapshot(value, path, this, {
+      volatile,
+      serverTimestamp: serverTimestamp ?? null
+    });
   }
   // ============================================
   // Internal: Subscription Management
@@ -1603,8 +2252,8 @@ var LarkDatabase = class {
   /**
    * @internal Subscribe to events at a path.
    */
-  _subscribe(path, eventType, callback) {
-    return this.subscriptionManager.subscribe(path, eventType, callback);
+  _subscribe(path, eventType, callback, queryParams) {
+    return this.subscriptionManager.subscribe(path, eventType, callback, queryParams);
   }
   /**
    * @internal Unsubscribe from a specific event type at a path.
@@ -1640,6 +2289,7 @@ export {
   LarkDatabase,
   LarkError,
   OnDisconnect,
+  PendingWriteManager,
   generatePushId,
   isVolatilePath
 };