@lark-sh/client 0.1.2 → 0.1.3

package/dist/index.d.mts

@@ -254,6 +254,9 @@ interface QueryParams {
 
 /**
  * SubscriptionManager - tracks active subscriptions and routes events to callbacks.
+ *
+ * Also manages a local data cache that is populated by subscription events.
+ * The cache only contains "live" data from active subscriptions.
  */
 
 type SnapshotCallback = (snapshot: DataSnapshot, previousChildKey?: string | null) => void;
@@ -356,6 +359,15 @@ declare class LarkDatabase {
     _sendPush(path: string, value: unknown): Promise<string>;
     /**
      * @internal Send a once (read) operation.
+     *
+     * This method first checks if the data is available in the local cache
+     * (from an active subscription). If so, it returns the cached value
+     * immediately without a server round-trip.
+     *
+     * Cache is only used when:
+     * - No query parameters are specified (queries may filter/order differently)
+     * - The path is covered by an active 'value' subscription
+     * - We have cached data available
      */
     _sendOnce(path: string, query?: QueryParams): Promise<DataSnapshot>;
     /**

package/dist/index.d.ts

@@ -254,6 +254,9 @@ interface QueryParams {
 
 /**
  * SubscriptionManager - tracks active subscriptions and routes events to callbacks.
+ *
+ * Also manages a local data cache that is populated by subscription events.
+ * The cache only contains "live" data from active subscriptions.
  */
 
 type SnapshotCallback = (snapshot: DataSnapshot, previousChildKey?: string | null) => void;
@@ -356,6 +359,15 @@ declare class LarkDatabase {
     _sendPush(path: string, value: unknown): Promise<string>;
     /**
      * @internal Send a once (read) operation.
+     *
+     * This method first checks if the data is available in the local cache
+     * (from an active subscription). If so, it returns the cached value
+     * immediately without a server round-trip.
+     *
+     * Cache is only used when:
+     * - No query parameters are specified (queries may filter/order differently)
+     * - The path is covered by an active 'value' subscription
+     * - We have cached data available
      */
     _sendOnce(path: string, query?: QueryParams): Promise<DataSnapshot>;
     /**

package/dist/index.js

@@ -247,6 +247,234 @@ var MessageQueue = class {
   }
 };
 
+// src/utils/path.ts
+function normalizePath(path) {
+  if (!path || path === "/") return "/";
+  const segments = path.split("/").filter((segment) => segment.length > 0);
+  if (segments.length === 0) return "/";
+  return "/" + segments.join("/");
+}
+function joinPath(...segments) {
+  const allParts = [];
+  for (const segment of segments) {
+    if (!segment || segment === "/") continue;
+    const parts = segment.split("/").filter((p) => p.length > 0);
+    allParts.push(...parts);
+  }
+  if (allParts.length === 0) return "/";
+  return "/" + allParts.join("/");
+}
+function getParentPath(path) {
+  const normalized = normalizePath(path);
+  if (normalized === "/") return "/";
+  const lastSlash = normalized.lastIndexOf("/");
+  if (lastSlash <= 0) return "/";
+  return normalized.substring(0, lastSlash);
+}
+function getKey(path) {
+  const normalized = normalizePath(path);
+  if (normalized === "/") return null;
+  const lastSlash = normalized.lastIndexOf("/");
+  return normalized.substring(lastSlash + 1);
+}
+function getValueAtPath(obj, path) {
+  const normalized = normalizePath(path);
+  if (normalized === "/") return obj;
+  const segments = normalized.split("/").filter((s) => s.length > 0);
+  let current = obj;
+  for (const segment of segments) {
+    if (current === null || current === void 0) {
+      return void 0;
+    }
+    if (typeof current !== "object") {
+      return void 0;
+    }
+    current = current[segment];
+  }
+  return current;
+}
+function setValueAtPath(obj, path, value) {
+  const normalized = normalizePath(path);
+  if (normalized === "/") {
+    return;
+  }
+  const segments = normalized.split("/").filter((s) => s.length > 0);
+  let current = obj;
+  for (let i = 0; i < segments.length - 1; i++) {
+    const segment = segments[i];
+    if (!(segment in current) || typeof current[segment] !== "object" || current[segment] === null) {
+      current[segment] = {};
+    }
+    current = current[segment];
+  }
+  const lastSegment = segments[segments.length - 1];
+  current[lastSegment] = value;
+}
+
+// src/cache/DataCache.ts
+var DataCache = class {
+  constructor() {
+    // path -> cached value
+    this.cache = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Store a value at a path.
+   * Called when we receive data from a subscription event.
+   */
+  set(path, value) {
+    const normalized = normalizePath(path);
+    this.cache.set(normalized, value);
+  }
+  /**
+   * Get the cached value at a path.
+   * Returns undefined if not in cache.
+   *
+   * This method handles nested lookups:
+   * - If /boxes is cached with {0: true, 1: false}
+   * - get('/boxes/0') returns true (extracted from parent)
+   */
+  get(path) {
+    const normalized = normalizePath(path);
+    if (this.cache.has(normalized)) {
+      return { value: this.cache.get(normalized), found: true };
+    }
+    const ancestorResult = this.getFromAncestor(normalized);
+    if (ancestorResult.found) {
+      return ancestorResult;
+    }
+    return { value: void 0, found: false };
+  }
+  /**
+   * Check if we have cached data that covers the given path.
+   * This includes exact matches and ancestor paths.
+   */
+  has(path) {
+    return this.get(path).found;
+  }
+  /**
+   * Try to get data from an ancestor path.
+   * E.g., if /boxes is cached and we want /boxes/5, extract it.
+   */
+  getFromAncestor(path) {
+    const segments = path.split("/").filter((s) => s.length > 0);
+    for (let i = segments.length - 1; i >= 0; i--) {
+      const ancestorPath = i === 0 ? "/" : "/" + segments.slice(0, i).join("/");
+      if (this.cache.has(ancestorPath)) {
+        const ancestorValue = this.cache.get(ancestorPath);
+        const relativePath = "/" + segments.slice(i).join("/");
+        const extractedValue = getValueAtPath(ancestorValue, relativePath);
+        return { value: extractedValue, found: true };
+      }
+    }
+    if (this.cache.has("/")) {
+      const rootValue = this.cache.get("/");
+      const extractedValue = getValueAtPath(rootValue, path);
+      return { value: extractedValue, found: true };
+    }
+    return { value: void 0, found: false };
+  }
+  /**
+   * Remove cached data at a path.
+   * Called when unsubscribing from a path that's no longer covered.
+   */
+  delete(path) {
+    const normalized = normalizePath(path);
+    this.cache.delete(normalized);
+  }
+  /**
+   * Remove cached data at a path and all descendant paths.
+   * Called when a subscription is removed and no other subscription covers it.
+   */
+  deleteTree(path) {
+    const normalized = normalizePath(path);
+    this.cache.delete(normalized);
+    const prefix = normalized === "/" ? "/" : normalized + "/";
+    for (const cachedPath of this.cache.keys()) {
+      if (cachedPath.startsWith(prefix) || normalized === "/" && cachedPath !== "/") {
+        this.cache.delete(cachedPath);
+      }
+    }
+  }
+  /**
+   * Update cache when a child value changes.
+   * This updates both the child path and any cached ancestor that contains it.
+   *
+   * E.g., if /boxes is cached and /boxes/5 changes:
+   * - Update the /boxes cache to reflect the new /boxes/5 value
+   */
+  updateChild(path, value) {
+    const normalized = normalizePath(path);
+    this.cache.set(normalized, value);
+    const segments = normalized.split("/").filter((s) => s.length > 0);
+    for (let i = segments.length - 1; i >= 1; i--) {
+      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);
+        }
+      }
+    }
+    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);
+      }
+    }
+  }
+  /**
+   * Remove a child from the cache (e.g., on child_removed event).
+   */
+  removeChild(path) {
+    const normalized = normalizePath(path);
+    this.deleteTree(normalized);
+    const segments = normalized.split("/").filter((s) => s.length > 0);
+    for (let i = segments.length - 1; i >= 1; i--) {
+      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 updatedAncestor = this.deepClone(ancestorValue);
+          const parentPath = "/" + segments.slice(i, -1).join("/");
+          const childKey = segments[segments.length - 1];
+          const parent = parentPath === "/" ? updatedAncestor : getValueAtPath(updatedAncestor, parentPath);
+          if (parent && typeof parent === "object") {
+            delete parent[childKey];
+          }
+          this.cache.set(ancestorPath, updatedAncestor);
+        }
+      }
+    }
+  }
+  /**
+   * Clear all cached data.
+   */
+  clear() {
+    this.cache.clear();
+  }
+  /**
+   * Get the number of cached paths (for testing/debugging).
+   */
+  get size() {
+    return this.cache.size;
+  }
+  /**
+   * Deep clone a value to avoid mutation issues.
+   */
+  deepClone(value) {
+    if (value === null || typeof value !== "object") {
+      return value;
+    }
+    return JSON.parse(JSON.stringify(value));
+  }
+};
+
 // src/connection/SubscriptionManager.ts
 var SubscriptionManager = class {
   constructor() {
@@ -258,6 +486,7 @@ var SubscriptionManager = class {
     this.sendUnsubscribe = null;
     // Callback to create DataSnapshot from event data
     this.createSnapshot = null;
+    this.cache = new DataCache();
   }
   /**
    * Initialize the manager with server communication callbacks.
@@ -370,6 +599,15 @@ var SubscriptionManager = class {
     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);
     } else {
       snapshotPath = path === "/" ? `/${message.k}` : `${path}/${message.k}`;
       snapshotValue = message.v;
@@ -397,6 +635,7 @@ var SubscriptionManager = class {
    */
   clear() {
     this.subscriptions.clear();
+    this.cache.clear();
   }
   /**
    * Check if there are any subscriptions at a path.
@@ -404,6 +643,65 @@ var SubscriptionManager = class {
   hasSubscriptions(path) {
     return this.subscriptions.has(path);
   }
+  /**
+   * Check if a path is "covered" by an active subscription.
+   *
+   * A path is covered if:
+   * - There's an active 'value' subscription at that exact path, OR
+   * - There's an active 'value' subscription at an ancestor path
+   *
+   * Child event subscriptions (child_added, etc.) don't provide full coverage
+   * because they only notify of changes, not the complete value.
+   */
+  isPathCovered(path) {
+    const normalized = normalizePath(path);
+    if (this.hasValueSubscription(normalized)) {
+      return true;
+    }
+    const segments = normalized.split("/").filter((s) => s.length > 0);
+    for (let i = segments.length - 1; i >= 0; i--) {
+      const ancestorPath = i === 0 ? "/" : "/" + segments.slice(0, i).join("/");
+      if (this.hasValueSubscription(ancestorPath)) {
+        return true;
+      }
+    }
+    if (normalized !== "/" && this.hasValueSubscription("/")) {
+      return true;
+    }
+    return false;
+  }
+  /**
+   * Check if there's a 'value' subscription at a path.
+   */
+  hasValueSubscription(path) {
+    const pathSubs = this.subscriptions.get(path);
+    if (!pathSubs) return false;
+    const valueSubs = pathSubs.get("value");
+    return valueSubs !== void 0 && valueSubs.length > 0;
+  }
+  /**
+   * Get a cached value if the path is covered by an active subscription.
+   *
+   * Returns { value, found: true } if we have cached data for this path
+   * (either exact match or extractable from a cached ancestor).
+   *
+   * Returns { value: undefined, found: false } if:
+   * - The path is not covered by any subscription, OR
+   * - We don't have cached data yet
+   */
+  getCachedValue(path) {
+    const normalized = normalizePath(path);
+    if (!this.isPathCovered(normalized)) {
+      return { value: void 0, found: false };
+    }
+    return this.cache.get(normalized);
+  }
+  /**
+   * Get the cache size (for testing/debugging).
+   */
+  get cacheSize() {
+    return this.cache.size;
+  }
 };
 
 // src/connection/WebSocketClient.ts
@@ -544,53 +842,6 @@ var OnDisconnect = class {
   }
 };
 
-// src/utils/path.ts
-function normalizePath(path) {
-  if (!path || path === "/") return "/";
-  const segments = path.split("/").filter((segment) => segment.length > 0);
-  if (segments.length === 0) return "/";
-  return "/" + segments.join("/");
-}
-function joinPath(...segments) {
-  const allParts = [];
-  for (const segment of segments) {
-    if (!segment || segment === "/") continue;
-    const parts = segment.split("/").filter((p) => p.length > 0);
-    allParts.push(...parts);
-  }
-  if (allParts.length === 0) return "/";
-  return "/" + allParts.join("/");
-}
-function getParentPath(path) {
-  const normalized = normalizePath(path);
-  if (normalized === "/") return "/";
-  const lastSlash = normalized.lastIndexOf("/");
-  if (lastSlash <= 0) return "/";
-  return normalized.substring(0, lastSlash);
-}
-function getKey(path) {
-  const normalized = normalizePath(path);
-  if (normalized === "/") return null;
-  const lastSlash = normalized.lastIndexOf("/");
-  return normalized.substring(lastSlash + 1);
-}
-function getValueAtPath(obj, path) {
-  const normalized = normalizePath(path);
-  if (normalized === "/") return obj;
-  const segments = normalized.split("/").filter((s) => s.length > 0);
-  let current = obj;
-  for (const segment of segments) {
-    if (current === null || current === void 0) {
-      return void 0;
-    }
-    if (typeof current !== "object") {
-      return void 0;
-    }
-    current = current[segment];
-  }
-  return current;
-}
-
 // src/utils/pushid.ts
 var PUSH_CHARS = "-0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz";
 var lastPushTime = 0;
@@ -1296,12 +1547,28 @@ var LarkDatabase = class {
   }
   /**
    * @internal Send a once (read) operation.
+   *
+   * This method first checks if the data is available in the local cache
+   * (from an active subscription). If so, it returns the cached value
+   * immediately without a server round-trip.
+   *
+   * Cache is only used when:
+   * - No query parameters are specified (queries may filter/order differently)
+   * - The path is covered by an active 'value' subscription
+   * - We have cached data available
    */
   async _sendOnce(path, query) {
+    const normalizedPath = normalizePath(path) || "/";
+    if (!query) {
+      const cached = this.subscriptionManager.getCachedValue(normalizedPath);
+      if (cached.found) {
+        return new DataSnapshot(cached.value, path, this);
+      }
+    }
     const requestId = this.messageQueue.nextRequestId();
     const message = {
       o: "o",
-      p: normalizePath(path) || "/",
+      p: normalizedPath,
       r: requestId
     };
     if (query) {