@lark-sh/client 0.1.6 → 0.1.8

package/dist/index.d.mts

@@ -24,6 +24,7 @@ declare class OnDisconnect {
     cancel(): Promise<void>;
     /**
      * Set a value with priority when disconnected.
+     * Priority is injected as `.priority` into the value object.
      */
     setWithPriority(value: unknown, priority: number | string): Promise<void>;
 }
@@ -88,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>;
     /**
@@ -112,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>;
     /**
@@ -126,10 +132,12 @@ declare class DatabaseReference {
     push(value?: unknown): DatabaseReference | Promise<DatabaseReference>;
     /**
      * Set the data with a priority value for ordering.
+     * Priority is injected as `.priority` into the value object.
      */
     setWithPriority(value: unknown, priority: number | string): Promise<void>;
     /**
      * Set the priority of the data at this location.
+     * Fetches current value and sets it with the new priority.
      */
     setPriority(priority: number | string): Promise<void>;
     /**
@@ -224,6 +232,12 @@ declare class DatabaseReference {
 /**
  * DataSnapshot - an immutable snapshot of data at a location.
  * Received in event callbacks and from once() operations.
+ *
+ * Priority Handling:
+ * - Priority is stored as a regular child value `.priority` in the data
+ * - val() strips `.priority` from returned objects (so app code doesn't see it)
+ * - getPriority() reads from the data's `.priority` field
+ * - This matches Firebase behavior where priority is metadata, not user data
  */
 
 declare class DataSnapshot {
@@ -231,11 +245,9 @@ declare class DataSnapshot {
     private readonly _path;
     private readonly _db;
     private readonly _volatile;
-    private readonly _priority;
     private readonly _serverTimestamp;
     constructor(data: unknown, path: string, db: LarkDatabase, options?: {
         volatile?: boolean;
-        priority?: number | string | null;
         serverTimestamp?: number | null;
     });
     /**
@@ -247,7 +259,8 @@ declare class DataSnapshot {
      */
     get key(): string | null;
     /**
-     * Get the raw data value.
+     * Get the data value, with `.priority` stripped if present.
+     * Priority is internal metadata and should not be visible to app code.
      */
     val(): unknown;
     /**
@@ -276,6 +289,7 @@ declare class DataSnapshot {
     forEach(callback: (child: DataSnapshot) => boolean | void): void;
     /**
      * Get the priority of the data at this location.
+     * Priority is stored as `.priority` in the data object.
      */
     getPriority(): number | string | null;
     /**
@@ -328,19 +342,21 @@ interface TxConditionOp {
     v: unknown;
 }
 type TxOperation = TxSetOp | TxUpdateOp | TxDeleteOp | TxConditionOp;
-interface MoveEntry {
-    k: string;
-    ak: string;
-}
 
 /**
- * SubscriptionManager - tracks active subscriptions and routes events to callbacks.
+ * View - represents a client's subscription to a database path.
  *
- * Handles the new delta-based protocol where server sends 'put' and 'patch' events.
- * Client generates child_added, child_changed, child_removed, child_moved events locally.
+ * Each View encapsulates all state for a single subscription:
+ * - Path and query parameters
+ * - Event callbacks by type
+ * - Ordered children (keys in sorted order, sorted by client)
+ * - Local cache of visible data
  *
- * Supports ordered queries: tracks child order from server's `k` (orderedKeys) and `ak` (afterKey)
- * fields, and fires child_moved when positions change via `mv` (moves) array.
+ * This mirrors the server's View concept, enabling:
+ * - Per-View caching (no shared global cache)
+ * - Client-side sorting (ignores server's ak/mv hints)
+ * - Local-first writes (future)
+ * - Independent reconnection per View
  */
 
 type SnapshotCallback = (snapshot: DataSnapshot, previousChildKey?: string | null) => void;
@@ -389,12 +405,18 @@ interface TransactionConditionOp {
 type TransactionOp = TransactionSetOp | TransactionUpdateOp | TransactionDeleteOp | TransactionConditionOp;
 /** Object syntax for transactions: path -> value (null = delete) */
 type TransactionObject = Record<string, unknown>;
+type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting';
 declare class LarkDatabase {
     private _state;
     private _auth;
     private _databaseId;
     private _coordinatorUrl;
     private _volatilePaths;
+    private _connectionId;
+    private _connectOptions;
+    private _intentionalDisconnect;
+    private _reconnectAttempt;
+    private _reconnectTimer;
     private ws;
     private messageQueue;
     private subscriptionManager;
@@ -402,11 +424,20 @@ declare class LarkDatabase {
     private connectCallbacks;
     private disconnectCallbacks;
     private errorCallbacks;
+    private reconnectingCallbacks;
     constructor();
     /**
      * Whether the database is currently connected.
      */
     get connected(): boolean;
+    /**
+     * Whether the database is currently attempting to reconnect.
+     */
+    get reconnecting(): boolean;
+    /**
+     * Current connection state.
+     */
+    get state(): ConnectionState;
     /**
      * Current auth info, or null if not connected.
      */
@@ -442,15 +473,41 @@ declare class LarkDatabase {
      * @param options - Connection options (token, anonymous, coordinator URL)
      */
     connect(databaseId: string, options?: ConnectOptions): Promise<void>;
+    /**
+     * Internal connect implementation used by both initial connect and reconnect.
+     */
+    private performConnect;
     /**
      * Disconnect from the database.
      * This triggers onDisconnect hooks on the server.
      */
     disconnect(): Promise<void>;
     /**
-     * Clean up connection state.
+     * Full cleanup - clears all state including subscriptions.
+     * Used for intentional disconnect.
+     */
+    private cleanupFull;
+    /**
+     * Partial cleanup - preserves state needed for reconnect.
+     * Used for unexpected disconnect.
+     */
+    private cleanupForReconnect;
+    /**
+     * Schedule a reconnection attempt with exponential backoff.
+     */
+    private scheduleReconnect;
+    /**
+     * Attempt to reconnect to the database.
      */
-    private cleanup;
+    private attemptReconnect;
+    /**
+     * Restore subscriptions and retry pending writes after reconnect.
+     */
+    private restoreAfterReconnect;
+    /**
+     * Retry all pending writes after reconnect.
+     */
+    private retryPendingWrites;
     /**
      * Get a reference to a path in the database.
      */
@@ -512,14 +569,21 @@ declare class LarkDatabase {
      * Returns an unsubscribe function.
      */
     onError(callback: (error: Error) => void): () => void;
+    /**
+     * Register a callback for when reconnection attempts begin.
+     * This fires when an unexpected disconnect occurs and auto-reconnect starts.
+     * Returns an unsubscribe function.
+     */
+    onReconnecting(callback: () => void): () => void;
     private handleMessage;
     private handleClose;
     private handleError;
     private send;
     /**
      * @internal Send a set operation.
+     * Note: Priority is now part of the value (as .priority), not a separate field.
      */
-    _sendSet(path: string, value: unknown, priority?: number | string): Promise<void>;
+    _sendSet(path: string, value: unknown): Promise<void>;
     /**
      * @internal Send an update operation.
      */
@@ -529,9 +593,30 @@ declare class LarkDatabase {
      */
     _sendDelete(path: string): Promise<void>;
     /**
-     * @internal Send a push operation. Returns the generated key.
+     * @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).
      */
-    _sendPush(path: string, value: unknown): Promise<string>;
+    isVolatilePath(path: string): boolean;
     /**
      * @internal Send a once (read) operation.
      *
@@ -548,7 +633,7 @@ declare class LarkDatabase {
     /**
      * @internal Send an onDisconnect operation.
      */
-    _sendOnDisconnect(path: string, action: string, value?: unknown, priority?: number | string): Promise<void>;
+    _sendOnDisconnect(path: string, action: string, value?: unknown): Promise<void>;
     /**
      * @internal Send a subscribe message to server.
      */
@@ -577,6 +662,18 @@ declare class LarkDatabase {
 
 /**
  * LarkError - custom error class for Lark operations.
+ *
+ * Standard error codes:
+ * - `permission_denied` - Security rules rejected operation
+ * - `invalid_data` - Malformed data
+ * - `not_found` - Path doesn't exist
+ * - `invalid_path` - Invalid path format
+ * - `timeout` - Request timed out
+ * - `not_connected` - Operation attempted while disconnected
+ * - `condition_failed` - Transaction condition check failed (CAS mismatch)
+ * - `max_retries_exceeded` - Optimistic transaction exceeded retry limit
+ * - `write_tainted` - Write rejected locally because it depended on a failed write
+ * - `view_recovering` - Write rejected because View is recovering from failed write
  */
 declare class LarkError extends Error {
     readonly code: string;
@@ -590,7 +687,7 @@ declare class LarkError extends Error {
  * pending writes until they are acknowledged by the server. On reconnect, pending
  * writes can be retried to ensure data consistency.
  */
-type WriteOperation = 'set' | 'update' | 'delete' | 'push' | 'transaction';
+type WriteOperation = 'set' | 'update' | 'delete' | 'transaction';
 interface PendingWrite {
     oid: string;
     operation: WriteOperation;
@@ -659,20 +756,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, type MoveEntry, 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 WriteOperation, generatePushId, isVolatilePath };

package/dist/index.d.ts

@@ -24,6 +24,7 @@ declare class OnDisconnect {
     cancel(): Promise<void>;
     /**
      * Set a value with priority when disconnected.
+     * Priority is injected as `.priority` into the value object.
      */
     setWithPriority(value: unknown, priority: number | string): Promise<void>;
 }
@@ -88,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>;
     /**
@@ -112,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>;
     /**
@@ -126,10 +132,12 @@ declare class DatabaseReference {
     push(value?: unknown): DatabaseReference | Promise<DatabaseReference>;
     /**
      * Set the data with a priority value for ordering.
+     * Priority is injected as `.priority` into the value object.
      */
     setWithPriority(value: unknown, priority: number | string): Promise<void>;
     /**
      * Set the priority of the data at this location.
+     * Fetches current value and sets it with the new priority.
      */
     setPriority(priority: number | string): Promise<void>;
     /**
@@ -224,6 +232,12 @@ declare class DatabaseReference {
 /**
  * DataSnapshot - an immutable snapshot of data at a location.
  * Received in event callbacks and from once() operations.
+ *
+ * Priority Handling:
+ * - Priority is stored as a regular child value `.priority` in the data
+ * - val() strips `.priority` from returned objects (so app code doesn't see it)
+ * - getPriority() reads from the data's `.priority` field
+ * - This matches Firebase behavior where priority is metadata, not user data
  */
 
 declare class DataSnapshot {
@@ -231,11 +245,9 @@ declare class DataSnapshot {
     private readonly _path;
     private readonly _db;
     private readonly _volatile;
-    private readonly _priority;
     private readonly _serverTimestamp;
     constructor(data: unknown, path: string, db: LarkDatabase, options?: {
         volatile?: boolean;
-        priority?: number | string | null;
         serverTimestamp?: number | null;
     });
     /**
@@ -247,7 +259,8 @@ declare class DataSnapshot {
      */
     get key(): string | null;
     /**
-     * Get the raw data value.
+     * Get the data value, with `.priority` stripped if present.
+     * Priority is internal metadata and should not be visible to app code.
      */
     val(): unknown;
     /**
@@ -276,6 +289,7 @@ declare class DataSnapshot {
     forEach(callback: (child: DataSnapshot) => boolean | void): void;
     /**
      * Get the priority of the data at this location.
+     * Priority is stored as `.priority` in the data object.
      */
     getPriority(): number | string | null;
     /**
@@ -328,19 +342,21 @@ interface TxConditionOp {
     v: unknown;
 }
 type TxOperation = TxSetOp | TxUpdateOp | TxDeleteOp | TxConditionOp;
-interface MoveEntry {
-    k: string;
-    ak: string;
-}
 
 /**
- * SubscriptionManager - tracks active subscriptions and routes events to callbacks.
+ * View - represents a client's subscription to a database path.
  *
- * Handles the new delta-based protocol where server sends 'put' and 'patch' events.
- * Client generates child_added, child_changed, child_removed, child_moved events locally.
+ * Each View encapsulates all state for a single subscription:
+ * - Path and query parameters
+ * - Event callbacks by type
+ * - Ordered children (keys in sorted order, sorted by client)
+ * - Local cache of visible data
  *
- * Supports ordered queries: tracks child order from server's `k` (orderedKeys) and `ak` (afterKey)
- * fields, and fires child_moved when positions change via `mv` (moves) array.
+ * This mirrors the server's View concept, enabling:
+ * - Per-View caching (no shared global cache)
+ * - Client-side sorting (ignores server's ak/mv hints)
+ * - Local-first writes (future)
+ * - Independent reconnection per View
  */
 
 type SnapshotCallback = (snapshot: DataSnapshot, previousChildKey?: string | null) => void;
@@ -389,12 +405,18 @@ interface TransactionConditionOp {
 type TransactionOp = TransactionSetOp | TransactionUpdateOp | TransactionDeleteOp | TransactionConditionOp;
 /** Object syntax for transactions: path -> value (null = delete) */
 type TransactionObject = Record<string, unknown>;
+type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting';
 declare class LarkDatabase {
     private _state;
     private _auth;
     private _databaseId;
     private _coordinatorUrl;
     private _volatilePaths;
+    private _connectionId;
+    private _connectOptions;
+    private _intentionalDisconnect;
+    private _reconnectAttempt;
+    private _reconnectTimer;
     private ws;
     private messageQueue;
     private subscriptionManager;
@@ -402,11 +424,20 @@ declare class LarkDatabase {
     private connectCallbacks;
     private disconnectCallbacks;
     private errorCallbacks;
+    private reconnectingCallbacks;
     constructor();
     /**
      * Whether the database is currently connected.
      */
     get connected(): boolean;
+    /**
+     * Whether the database is currently attempting to reconnect.
+     */
+    get reconnecting(): boolean;
+    /**
+     * Current connection state.
+     */
+    get state(): ConnectionState;
     /**
      * Current auth info, or null if not connected.
      */
@@ -442,15 +473,41 @@ declare class LarkDatabase {
      * @param options - Connection options (token, anonymous, coordinator URL)
      */
     connect(databaseId: string, options?: ConnectOptions): Promise<void>;
+    /**
+     * Internal connect implementation used by both initial connect and reconnect.
+     */
+    private performConnect;
     /**
      * Disconnect from the database.
      * This triggers onDisconnect hooks on the server.
      */
     disconnect(): Promise<void>;
     /**
-     * Clean up connection state.
+     * Full cleanup - clears all state including subscriptions.
+     * Used for intentional disconnect.
+     */
+    private cleanupFull;
+    /**
+     * Partial cleanup - preserves state needed for reconnect.
+     * Used for unexpected disconnect.
+     */
+    private cleanupForReconnect;
+    /**
+     * Schedule a reconnection attempt with exponential backoff.
+     */
+    private scheduleReconnect;
+    /**
+     * Attempt to reconnect to the database.
      */
-    private cleanup;
+    private attemptReconnect;
+    /**
+     * Restore subscriptions and retry pending writes after reconnect.
+     */
+    private restoreAfterReconnect;
+    /**
+     * Retry all pending writes after reconnect.
+     */
+    private retryPendingWrites;
     /**
      * Get a reference to a path in the database.
      */
@@ -512,14 +569,21 @@ declare class LarkDatabase {
      * Returns an unsubscribe function.
      */
     onError(callback: (error: Error) => void): () => void;
+    /**
+     * Register a callback for when reconnection attempts begin.
+     * This fires when an unexpected disconnect occurs and auto-reconnect starts.
+     * Returns an unsubscribe function.
+     */
+    onReconnecting(callback: () => void): () => void;
     private handleMessage;
     private handleClose;
     private handleError;
     private send;
     /**
      * @internal Send a set operation.
+     * Note: Priority is now part of the value (as .priority), not a separate field.
      */
-    _sendSet(path: string, value: unknown, priority?: number | string): Promise<void>;
+    _sendSet(path: string, value: unknown): Promise<void>;
     /**
      * @internal Send an update operation.
      */
@@ -529,9 +593,30 @@ declare class LarkDatabase {
      */
     _sendDelete(path: string): Promise<void>;
     /**
-     * @internal Send a push operation. Returns the generated key.
+     * @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).
      */
-    _sendPush(path: string, value: unknown): Promise<string>;
+    isVolatilePath(path: string): boolean;
     /**
      * @internal Send a once (read) operation.
      *
@@ -548,7 +633,7 @@ declare class LarkDatabase {
     /**
      * @internal Send an onDisconnect operation.
      */
-    _sendOnDisconnect(path: string, action: string, value?: unknown, priority?: number | string): Promise<void>;
+    _sendOnDisconnect(path: string, action: string, value?: unknown): Promise<void>;
     /**
      * @internal Send a subscribe message to server.
      */
@@ -577,6 +662,18 @@ declare class LarkDatabase {
 
 /**
  * LarkError - custom error class for Lark operations.
+ *
+ * Standard error codes:
+ * - `permission_denied` - Security rules rejected operation
+ * - `invalid_data` - Malformed data
+ * - `not_found` - Path doesn't exist
+ * - `invalid_path` - Invalid path format
+ * - `timeout` - Request timed out
+ * - `not_connected` - Operation attempted while disconnected
+ * - `condition_failed` - Transaction condition check failed (CAS mismatch)
+ * - `max_retries_exceeded` - Optimistic transaction exceeded retry limit
+ * - `write_tainted` - Write rejected locally because it depended on a failed write
+ * - `view_recovering` - Write rejected because View is recovering from failed write
  */
 declare class LarkError extends Error {
     readonly code: string;
@@ -590,7 +687,7 @@ declare class LarkError extends Error {
  * pending writes until they are acknowledged by the server. On reconnect, pending
  * writes can be retried to ensure data consistency.
  */
-type WriteOperation = 'set' | 'update' | 'delete' | 'push' | 'transaction';
+type WriteOperation = 'set' | 'update' | 'delete' | 'transaction';
 interface PendingWrite {
     oid: string;
     operation: WriteOperation;
@@ -659,20 +756,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, type MoveEntry, 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 WriteOperation, generatePushId, isVolatilePath };