@lark-sh/client 0.1.8 → 0.1.10

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.
  */
@@ -336,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;
 
 /**
@@ -372,6 +384,20 @@ 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;
+    /**
+     * Timeout for WebTransport connection attempt in milliseconds.
+     * If WebTransport doesn't connect within this time, falls back to WebSocket.
+     * Only applies when transport is 'auto'.
+     * Default: 2000 (2 seconds)
+     */
+    webtransportTimeout?: number;
 }
 interface AuthInfo {
     uid: string;
@@ -412,12 +438,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;
@@ -449,9 +476,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.
@@ -543,6 +574,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;
     /**
@@ -603,6 +635,8 @@ declare class LarkDatabase {
      *
      * 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;
     /**
@@ -773,4 +807,4 @@ declare function generatePushId(): string;
  */
 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.
  */
@@ -336,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;
 
 /**
@@ -372,6 +384,20 @@ 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;
+    /**
+     * Timeout for WebTransport connection attempt in milliseconds.
+     * If WebTransport doesn't connect within this time, falls back to WebSocket.
+     * Only applies when transport is 'auto'.
+     * Default: 2000 (2 seconds)
+     */
+    webtransportTimeout?: number;
 }
 interface AuthInfo {
     uid: string;
@@ -412,12 +438,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;
@@ -449,9 +476,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.
@@ -543,6 +574,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;
     /**
@@ -603,6 +635,8 @@ declare class LarkDatabase {
      *
      * 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;
     /**
@@ -773,4 +807,4 @@ declare function generatePushId(): string;
  */
 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 };