@lark-sh/client 0.1.2 → 0.1.4

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;
@@ -280,6 +283,7 @@ declare class LarkDatabase {
     private _auth;
     private _databaseId;
     private _coordinatorUrl;
+    private _volatilePaths;
     private ws;
     private messageQueue;
     private subscriptionManager;
@@ -299,6 +303,12 @@ declare class LarkDatabase {
      * @internal Get the base URL for reference toString().
      */
     _getBaseUrl(): string;
+    /**
+     * 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(): string[];
     /**
      * Connect to a database.
      *
@@ -356,6 +366,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>;
     /**
@@ -412,4 +431,24 @@ declare class LarkError extends Error {
  */
 declare function generatePushId(): string;
 
-export { type AuthInfo, type ConnectOptions, DataSnapshot, DatabaseReference, type EventType, LarkDatabase, LarkError, OnDisconnect, type QueryState, type SnapshotCallback$1 as SnapshotCallback, generatePushId };
+/**
+ * Volatile path matching utilities.
+ *
+ * Volatile paths are patterns where a wildcard matches exactly one path segment.
+ * These paths use unreliable transport for better performance (UDP when available).
+ */
+/**
+ * Check if a path matches any of the volatile path patterns.
+ *
+ * Pattern matching rules:
+ * - Wildcard matches exactly one path segment (not zero, not multiple)
+ * - Patterns and paths are compared segment by segment
+ * - Path must have the same number of segments as the pattern
+ *
+ * @param path - The path to check (e.g., "/players/abc/position")
+ * @param patterns - Array of volatile patterns with wildcards
+ * @returns true if the path matches any pattern
+ */
+declare function isVolatilePath(path: string, patterns: string[] | null | undefined): boolean;
+
+export { type AuthInfo, type ConnectOptions, DataSnapshot, DatabaseReference, type EventType, LarkDatabase, LarkError, OnDisconnect, type QueryState, type SnapshotCallback$1 as SnapshotCallback, generatePushId, isVolatilePath };

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;
@@ -280,6 +283,7 @@ declare class LarkDatabase {
     private _auth;
     private _databaseId;
     private _coordinatorUrl;
+    private _volatilePaths;
     private ws;
     private messageQueue;
     private subscriptionManager;
@@ -299,6 +303,12 @@ declare class LarkDatabase {
      * @internal Get the base URL for reference toString().
      */
     _getBaseUrl(): string;
+    /**
+     * 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(): string[];
     /**
      * Connect to a database.
      *
@@ -356,6 +366,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>;
     /**
@@ -412,4 +431,24 @@ declare class LarkError extends Error {
  */
 declare function generatePushId(): string;
 
-export { type AuthInfo, type ConnectOptions, DataSnapshot, DatabaseReference, type EventType, LarkDatabase, LarkError, OnDisconnect, type QueryState, type SnapshotCallback$1 as SnapshotCallback, generatePushId };
+/**
+ * Volatile path matching utilities.
+ *
+ * Volatile paths are patterns where a wildcard matches exactly one path segment.
+ * These paths use unreliable transport for better performance (UDP when available).
+ */
+/**
+ * Check if a path matches any of the volatile path patterns.
+ *
+ * Pattern matching rules:
+ * - Wildcard matches exactly one path segment (not zero, not multiple)
+ * - Patterns and paths are compared segment by segment
+ * - Path must have the same number of segments as the pattern
+ *
+ * @param path - The path to check (e.g., "/players/abc/position")
+ * @param patterns - Array of volatile patterns with wildcards
+ * @returns true if the path matches any pattern
+ */
+declare function isVolatilePath(path: string, patterns: string[] | null | undefined): boolean;
+
+export { type AuthInfo, type ConnectOptions, DataSnapshot, DatabaseReference, type EventType, LarkDatabase, LarkError, OnDisconnect, type QueryState, type SnapshotCallback$1 as SnapshotCallback, generatePushId, isVolatilePath };

package/dist/index.js

@@ -35,7 +35,8 @@ __export(index_exports, {
   LarkDatabase: () => LarkDatabase,
   LarkError: () => LarkError,
   OnDisconnect: () => OnDisconnect,
-  generatePushId: () => generatePushId
+  generatePushId: () => generatePushId,
+  isVolatilePath: () => isVolatilePath
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -119,10 +120,10 @@ var LarkError = class _LarkError extends Error {
 
 // src/protocol/messages.ts
 function isAckMessage(msg) {
-  return "a" in msg && !("uid" in msg);
+  return "a" in msg;
 }
-function isJoinAckMessage(msg) {
-  return "a" in msg && "uid" in msg;
+function isJoinCompleteMessage(msg) {
+  return "jc" in msg;
 }
 function isNackMessage(msg) {
   return "n" in msg;
@@ -178,16 +179,12 @@ var MessageQueue = class {
    * @returns true if the message was handled (was a response), false otherwise
    */
   handleMessage(message) {
-    if (isJoinAckMessage(message)) {
-      const pending = this.pending.get(message.a);
+    if (isJoinCompleteMessage(message)) {
+      const pending = this.pending.get(message.jc);
       if (pending) {
         clearTimeout(pending.timeout);
-        this.pending.delete(message.a);
-        pending.resolve({
-          uid: message.uid,
-          provider: message.provider,
-          token: message.token
-        });
+        this.pending.delete(message.jc);
+        pending.resolve(message.vp || []);
         return true;
       }
     }
@@ -247,6 +244,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 +483,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 +596,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 +632,7 @@ var SubscriptionManager = class {
    */
   clear() {
     this.subscriptions.clear();
+    this.cache.clear();
   }
   /**
    * Check if there are any subscriptions at a path.
@@ -404,6 +640,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 +839,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;
@@ -1028,6 +1276,7 @@ var LarkDatabase = class {
     this._auth = null;
     this._databaseId = null;
     this._coordinatorUrl = null;
+    this._volatilePaths = [];
     this.ws = null;
     // Event callbacks
     this.connectCallbacks = /* @__PURE__ */ new Set();
@@ -1060,6 +1309,14 @@ var LarkDatabase = class {
     }
     return "lark://";
   }
+  /**
+   * 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;
+  }
   // ============================================
   // Connection Management
   // ============================================
@@ -1100,7 +1357,8 @@ var LarkDatabase = class {
         r: requestId
       };
       this.send(joinMessage);
-      await this.messageQueue.registerRequest(requestId);
+      const volatilePaths = await this.messageQueue.registerRequest(requestId);
+      this._volatilePaths = volatilePaths || [];
       const jwtPayload = decodeJwtPayload(connectResponse.token);
       this._auth = {
         uid: jwtPayload.sub,
@@ -1153,6 +1411,7 @@ var LarkDatabase = class {
     this._state = "disconnected";
     this._auth = null;
     this._databaseId = null;
+    this._volatilePaths = [];
     this._coordinatorUrl = null;
     this.subscriptionManager.clear();
     this.messageQueue.rejectAll(new Error("Connection closed"));
@@ -1296,12 +1555,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) {
@@ -1386,6 +1661,21 @@ 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]);
+  });
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DataSnapshot,
@@ -1393,6 +1683,7 @@ var LarkDatabase = class {
   LarkDatabase,
   LarkError,
   OnDisconnect,
-  generatePushId
+  generatePushId,
+  isVolatilePath
 });
 //# sourceMappingURL=index.js.map