@lark-sh/client 0.1.7 → 0.1.9

package/dist/index.d.mts

@@ -1,3 +1,9 @@
+/**
+ * Transport factory - creates appropriate transport based on availability and options.
+ */
+
+type TransportType = 'auto' | 'websocket' | 'webtransport';
+
 /**
  * OnDisconnect - registers operations to perform on the server when this client disconnects.
  */
@@ -89,6 +95,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 +122,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>;
     /**
@@ -331,11 +342,17 @@ interface TxDeleteOp {
     o: 'd';
     p: string;
 }
-interface TxConditionOp {
+interface TxConditionValueOp {
     o: 'c';
     p: string;
     v: unknown;
 }
+interface TxConditionHashOp {
+    o: 'c';
+    p: string;
+    h: string;
+}
+type TxConditionOp = TxConditionValueOp | TxConditionHashOp;
 type TxOperation = TxSetOp | TxUpdateOp | TxDeleteOp | TxConditionOp;
 
 /**
@@ -367,6 +384,13 @@ interface ConnectOptions {
     anonymous?: boolean;
     /** Coordinator URL (default: https://db.lark.dev) */
     coordinator?: string;
+    /**
+     * Transport type preference.
+     * - 'auto': Try WebTransport first, fall back to WebSocket (default)
+     * - 'websocket': Force WebSocket only
+     * - 'webtransport': Force WebTransport only (fails if unavailable)
+     */
+    transport?: TransportType;
 }
 interface AuthInfo {
     uid: string;
@@ -407,12 +431,13 @@ declare class LarkDatabase {
     private _databaseId;
     private _coordinatorUrl;
     private _volatilePaths;
+    private _transportType;
     private _connectionId;
     private _connectOptions;
     private _intentionalDisconnect;
     private _reconnectAttempt;
     private _reconnectTimer;
-    private ws;
+    private transport;
     private messageQueue;
     private subscriptionManager;
     private pendingWrites;
@@ -444,9 +469,13 @@ declare class LarkDatabase {
     /**
      * 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[];
+    /**
+     * Get the current transport type.
+     * Returns 'websocket' or 'webtransport', or null if not connected.
+     */
+    get transportType(): 'websocket' | 'webtransport' | null;
     /**
      * Check if there are any pending writes waiting for acknowledgment.
      * Useful for showing "saving..." indicators in UI.
@@ -538,6 +567,7 @@ declare class LarkDatabase {
     transaction(operations: TransactionOp[] | TransactionObject): Promise<void>;
     /**
      * Convert a public TransactionOp to wire format TxOperation.
+     * Async because condition operations may require hash computation.
      */
     private convertToTxOp;
     /**
@@ -587,6 +617,33 @@ 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.
+     *
+     * When using WebTransport, volatile writes are sent via datagrams (UDP).
+     */
+    _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,20 +783,21 @@ 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
  */
 declare function isVolatilePath(path: string, patterns: string[] | null | undefined): boolean;
 
-export { type AuthInfo, type ConnectOptions, DataSnapshot, DatabaseReference, type EventType, LarkDatabase, LarkError, OnDisconnect, type PendingWrite, PendingWriteManager, type QueryParams, type QueryState, type SnapshotCallback$1 as SnapshotCallback, type TransactionConditionOp, type TransactionDeleteOp, type TransactionObject, type TransactionOp, type TransactionResult, type TransactionSetOp, type TransactionUpdateOp, type WriteOperation, generatePushId, isVolatilePath };
+export { type AuthInfo, type ConnectOptions, DataSnapshot, DatabaseReference, type EventType, LarkDatabase, LarkError, OnDisconnect, type PendingWrite, PendingWriteManager, type QueryParams, type QueryState, type SnapshotCallback$1 as SnapshotCallback, type TransactionConditionOp, type TransactionDeleteOp, type TransactionObject, type TransactionOp, type TransactionResult, type TransactionSetOp, type TransactionUpdateOp, type TransportType, type WriteOperation, generatePushId, isVolatilePath };

package/dist/index.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Transport factory - creates appropriate transport based on availability and options.
+ */
+
+type TransportType = 'auto' | 'websocket' | 'webtransport';
+
 /**
  * OnDisconnect - registers operations to perform on the server when this client disconnects.
  */
@@ -89,6 +95,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 +122,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>;
     /**
@@ -331,11 +342,17 @@ interface TxDeleteOp {
     o: 'd';
     p: string;
 }
-interface TxConditionOp {
+interface TxConditionValueOp {
     o: 'c';
     p: string;
     v: unknown;
 }
+interface TxConditionHashOp {
+    o: 'c';
+    p: string;
+    h: string;
+}
+type TxConditionOp = TxConditionValueOp | TxConditionHashOp;
 type TxOperation = TxSetOp | TxUpdateOp | TxDeleteOp | TxConditionOp;
 
 /**
@@ -367,6 +384,13 @@ interface ConnectOptions {
     anonymous?: boolean;
     /** Coordinator URL (default: https://db.lark.dev) */
     coordinator?: string;
+    /**
+     * Transport type preference.
+     * - 'auto': Try WebTransport first, fall back to WebSocket (default)
+     * - 'websocket': Force WebSocket only
+     * - 'webtransport': Force WebTransport only (fails if unavailable)
+     */
+    transport?: TransportType;
 }
 interface AuthInfo {
     uid: string;
@@ -407,12 +431,13 @@ declare class LarkDatabase {
     private _databaseId;
     private _coordinatorUrl;
     private _volatilePaths;
+    private _transportType;
     private _connectionId;
     private _connectOptions;
     private _intentionalDisconnect;
     private _reconnectAttempt;
     private _reconnectTimer;
-    private ws;
+    private transport;
     private messageQueue;
     private subscriptionManager;
     private pendingWrites;
@@ -444,9 +469,13 @@ declare class LarkDatabase {
     /**
      * 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[];
+    /**
+     * Get the current transport type.
+     * Returns 'websocket' or 'webtransport', or null if not connected.
+     */
+    get transportType(): 'websocket' | 'webtransport' | null;
     /**
      * Check if there are any pending writes waiting for acknowledgment.
      * Useful for showing "saving..." indicators in UI.
@@ -538,6 +567,7 @@ declare class LarkDatabase {
     transaction(operations: TransactionOp[] | TransactionObject): Promise<void>;
     /**
      * Convert a public TransactionOp to wire format TxOperation.
+     * Async because condition operations may require hash computation.
      */
     private convertToTxOp;
     /**
@@ -587,6 +617,33 @@ 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.
+     *
+     * When using WebTransport, volatile writes are sent via datagrams (UDP).
+     */
+    _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,20 +783,21 @@ 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
  */
 declare function isVolatilePath(path: string, patterns: string[] | null | undefined): boolean;
 
-export { type AuthInfo, type ConnectOptions, DataSnapshot, DatabaseReference, type EventType, LarkDatabase, LarkError, OnDisconnect, type PendingWrite, PendingWriteManager, type QueryParams, type QueryState, type SnapshotCallback$1 as SnapshotCallback, type TransactionConditionOp, type TransactionDeleteOp, type TransactionObject, type TransactionOp, type TransactionResult, type TransactionSetOp, type TransactionUpdateOp, type WriteOperation, generatePushId, isVolatilePath };
+export { type AuthInfo, type ConnectOptions, DataSnapshot, DatabaseReference, type EventType, LarkDatabase, LarkError, OnDisconnect, type PendingWrite, PendingWriteManager, type QueryParams, type QueryState, type SnapshotCallback$1 as SnapshotCallback, type TransactionConditionOp, type TransactionDeleteOp, type TransactionObject, type TransactionOp, type TransactionResult, type TransactionSetOp, type TransactionUpdateOp, type TransportType, type WriteOperation, generatePushId, isVolatilePath };