@lark-sh/client 0.1.7 → 0.1.8

package/dist/index.d.mts

@@ -89,6 +89,9 @@ declare class DatabaseReference {
     child(path: string): DatabaseReference;
     /**
      * Set the data at this location, overwriting any existing data.
+     *
+     * For volatile paths (high-frequency updates), this is fire-and-forget
+     * and resolves immediately without waiting for server confirmation.
      */
     set(value: unknown): Promise<void>;
     /**
@@ -113,6 +116,8 @@ declare class DatabaseReference {
     update(values: Record<string, unknown>): Promise<void>;
     /**
      * Remove the data at this location.
+     *
+     * For volatile paths, this is fire-and-forget.
      */
     remove(): Promise<void>;
     /**
@@ -587,6 +592,31 @@ declare class LarkDatabase {
      * @internal Send a delete operation.
      */
     _sendDelete(path: string): Promise<void>;
+    /**
+     * @internal Send a volatile set operation (fire-and-forget).
+     *
+     * Volatile writes skip:
+     * - Recovery checks (volatile paths don't participate in recovery)
+     * - Request ID generation (no ack expected)
+     * - Pending write tracking (no retry on reconnect)
+     * - pw field (no dependency tracking)
+     *
+     * The write is applied optimistically to local cache for UI feedback,
+     * but we don't await server confirmation.
+     */
+    _sendVolatileSet(path: string, value: unknown): void;
+    /**
+     * @internal Send a volatile update operation (fire-and-forget).
+     */
+    _sendVolatileUpdate(path: string, values: Record<string, unknown>): void;
+    /**
+     * @internal Send a volatile delete operation (fire-and-forget).
+     */
+    _sendVolatileDelete(path: string): void;
+    /**
+     * Check if a path is a volatile path (high-frequency, fire-and-forget).
+     */
+    isVolatilePath(path: string): boolean;
     /**
      * @internal Send a once (read) operation.
      *
@@ -726,17 +756,18 @@ declare function generatePushId(): string;
  * 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).
+ * These paths use unreliable transport for better performance (WebTransport datagrams 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)
+ * - Wildcard matches exactly one path segment
  * - Patterns and paths are compared segment by segment
- * - Path must have the same number of segments as the pattern
+ * - If pattern is exhausted before path, it's still a match (descendant rule)
+ * - If path is exhausted before pattern, no match
  *
- * @param path - The path to check (e.g., "/players/abc/position")
+ * @param path - The path to check
  * @param patterns - Array of volatile patterns with wildcards
  * @returns true if the path matches any pattern
  */

package/dist/index.d.ts

@@ -89,6 +89,9 @@ declare class DatabaseReference {
     child(path: string): DatabaseReference;
     /**
      * Set the data at this location, overwriting any existing data.
+     *
+     * For volatile paths (high-frequency updates), this is fire-and-forget
+     * and resolves immediately without waiting for server confirmation.
      */
     set(value: unknown): Promise<void>;
     /**
@@ -113,6 +116,8 @@ declare class DatabaseReference {
     update(values: Record<string, unknown>): Promise<void>;
     /**
      * Remove the data at this location.
+     *
+     * For volatile paths, this is fire-and-forget.
      */
     remove(): Promise<void>;
     /**
@@ -587,6 +592,31 @@ declare class LarkDatabase {
      * @internal Send a delete operation.
      */
     _sendDelete(path: string): Promise<void>;
+    /**
+     * @internal Send a volatile set operation (fire-and-forget).
+     *
+     * Volatile writes skip:
+     * - Recovery checks (volatile paths don't participate in recovery)
+     * - Request ID generation (no ack expected)
+     * - Pending write tracking (no retry on reconnect)
+     * - pw field (no dependency tracking)
+     *
+     * The write is applied optimistically to local cache for UI feedback,
+     * but we don't await server confirmation.
+     */
+    _sendVolatileSet(path: string, value: unknown): void;
+    /**
+     * @internal Send a volatile update operation (fire-and-forget).
+     */
+    _sendVolatileUpdate(path: string, values: Record<string, unknown>): void;
+    /**
+     * @internal Send a volatile delete operation (fire-and-forget).
+     */
+    _sendVolatileDelete(path: string): void;
+    /**
+     * Check if a path is a volatile path (high-frequency, fire-and-forget).
+     */
+    isVolatilePath(path: string): boolean;
     /**
      * @internal Send a once (read) operation.
      *
@@ -726,17 +756,18 @@ declare function generatePushId(): string;
  * 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).
+ * These paths use unreliable transport for better performance (WebTransport datagrams 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)
+ * - Wildcard matches exactly one path segment
  * - Patterns and paths are compared segment by segment
- * - Path must have the same number of segments as the pattern
+ * - If pattern is exhausted before path, it's still a match (descendant rule)
+ * - If path is exhausted before pattern, no match
  *
- * @param path - The path to check (e.g., "/players/abc/position")
+ * @param path - The path to check
  * @param patterns - Array of volatile patterns with wildcards
  * @returns true if the path matches any pattern
  */

package/dist/index.js

@@ -1820,8 +1820,15 @@ var DatabaseReference = class _DatabaseReference {
   // ============================================
   /**
    * Set the data at this location, overwriting any existing data.
+   *
+   * For volatile paths (high-frequency updates), this is fire-and-forget
+   * and resolves immediately without waiting for server confirmation.
    */
   async set(value) {
+    if (this._db.isVolatilePath(this._path)) {
+      this._db._sendVolatileSet(this._path, value);
+      return;
+    }
     await this._db._sendSet(this._path, value);
   }
   /**
@@ -1858,13 +1865,23 @@ var DatabaseReference = class _DatabaseReference {
       }
       await this._db._sendTransaction(ops);
     } else {
+      if (this._db.isVolatilePath(this._path)) {
+        this._db._sendVolatileUpdate(this._path, values);
+        return;
+      }
       await this._db._sendUpdate(this._path, values);
     }
   }
   /**
    * Remove the data at this location.
+   *
+   * For volatile paths, this is fire-and-forget.
    */
   async remove() {
+    if (this._db.isVolatilePath(this._path)) {
+      this._db._sendVolatileDelete(this._path);
+      return;
+    }
     await this._db._sendDelete(this._path);
   }
   /**
@@ -2317,6 +2334,28 @@ function decodeJwtPayload(token) {
   return JSON.parse(decoded);
 }
 
+// src/utils/volatile.ts
+function isVolatilePath(path, patterns) {
+  if (!patterns || patterns.length === 0) {
+    return false;
+  }
+  const segments = path.replace(/^\//, "").split("/").filter((s) => s.length > 0);
+  return patterns.some((pattern) => {
+    const patternSegments = pattern.replace(/^\//, "").split("/").filter((s) => s.length > 0);
+    if (segments.length < patternSegments.length) {
+      return false;
+    }
+    for (let i = 0; i < patternSegments.length; i++) {
+      const p = patternSegments[i];
+      const s = segments[i];
+      if (p !== "*" && p !== s) {
+        return false;
+      }
+    }
+    return true;
+  });
+}
+
 // src/LarkDatabase.ts
 var RECONNECT_BASE_DELAY_MS = 1e3;
 var RECONNECT_MAX_DELAY_MS = 3e4;
@@ -2940,6 +2979,62 @@ var LarkDatabase = class {
     this.send(message);
     await this.messageQueue.registerRequest(requestId);
   }
+  // ============================================
+  // Volatile Write Operations (Fire-and-Forget)
+  // ============================================
+  /**
+   * @internal Send a volatile set operation (fire-and-forget).
+   *
+   * Volatile writes skip:
+   * - Recovery checks (volatile paths don't participate in recovery)
+   * - Request ID generation (no ack expected)
+   * - Pending write tracking (no retry on reconnect)
+   * - pw field (no dependency tracking)
+   *
+   * The write is applied optimistically to local cache for UI feedback,
+   * but we don't await server confirmation.
+   */
+  _sendVolatileSet(path, value) {
+    const normalizedPath = normalizePath(path) || "/";
+    this.subscriptionManager.applyOptimisticWrite(normalizedPath, value, "", "set");
+    const message = {
+      o: "s",
+      p: normalizedPath,
+      v: value
+    };
+    this.send(message);
+  }
+  /**
+   * @internal Send a volatile update operation (fire-and-forget).
+   */
+  _sendVolatileUpdate(path, values) {
+    const normalizedPath = normalizePath(path) || "/";
+    this.subscriptionManager.applyOptimisticWrite(normalizedPath, values, "", "update");
+    const message = {
+      o: "u",
+      p: normalizedPath,
+      v: values
+    };
+    this.send(message);
+  }
+  /**
+   * @internal Send a volatile delete operation (fire-and-forget).
+   */
+  _sendVolatileDelete(path) {
+    const normalizedPath = normalizePath(path) || "/";
+    this.subscriptionManager.applyOptimisticWrite(normalizedPath, null, "", "delete");
+    const message = {
+      o: "d",
+      p: normalizedPath
+    };
+    this.send(message);
+  }
+  /**
+   * Check if a path is a volatile path (high-frequency, fire-and-forget).
+   */
+  isVolatilePath(path) {
+    return isVolatilePath(path, this._volatilePaths);
+  }
   /**
    * @internal Send a once (read) operation.
    *
@@ -3048,21 +3143,6 @@ 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,