@lark-sh/client 0.1.3 → 0.1.5

package/dist/index.d.mts

@@ -28,13 +28,20 @@ declare class OnDisconnect {
     setWithPriority(value: unknown, priority: number | string): Promise<void>;
 }
 
-type EventType = 'value' | 'child_added' | 'child_changed' | 'child_removed';
+type EventType = 'value' | 'child_added' | 'child_changed' | 'child_removed' | 'child_moved';
 
 /**
  * DatabaseReference - a reference to a specific path in the database.
  * Immutable - navigation returns new references.
  */
 
+/** Result of a transaction operation */
+interface TransactionResult {
+    /** Whether the transaction was committed (always true on success) */
+    committed: boolean;
+    /** Snapshot of the data after the transaction */
+    snapshot: DataSnapshot;
+}
 type SnapshotCallback$1 = (snapshot: DataSnapshot, previousChildKey?: string | null) => void;
 interface QueryState {
     orderBy?: 'key' | 'priority' | 'child' | 'value';
@@ -85,6 +92,22 @@ declare class DatabaseReference {
     set(value: unknown): Promise<void>;
     /**
      * Update specific children at this location without overwriting other children.
+     *
+     * Also supports Firebase-style multi-path updates when keys look like paths
+     * (start with '/'). In this mode, each path is written atomically as a transaction.
+     *
+     * @example
+     * ```javascript
+     * // Normal update (merge at single path)
+     * await ref.update({ score: 10, name: 'Riley' });
+     *
+     * // Multi-path update (atomic writes to multiple paths)
+     * await db.ref().update({
+     *   '/users/alice/score': 100,
+     *   '/users/bob/score': 200,
+     *   '/leaderboard/alice': null  // null = delete
+     * });
+     * ```
      */
     update(values: Record<string, unknown>): Promise<void>;
     /**
@@ -109,6 +132,29 @@ declare class DatabaseReference {
      * Set the priority of the data at this location.
      */
     setPriority(priority: number | string): Promise<void>;
+    /**
+     * Atomically modify the data at this location using optimistic concurrency.
+     *
+     * The update function receives the current value and should return the new
+     * value. If the data changed on the server before the write could be
+     * committed, the function is called again with the new value, and the
+     * process repeats until successful or the maximum retries are exceeded.
+     *
+     * @example
+     * ```javascript
+     * // Increment a counter atomically
+     * const result = await ref.transaction(currentValue => {
+     *   return (currentValue || 0) + 1;
+     * });
+     * console.log('New value:', result.snapshot.val());
+     * ```
+     *
+     * @param updateFunction - Function that receives current value and returns new value.
+     *                         Return undefined to abort the transaction.
+     * @param maxRetries - Maximum number of retries (default: 25)
+     * @returns TransactionResult with committed status and final snapshot
+     */
+    transaction(updateFunction: (currentValue: unknown) => unknown, maxRetries?: number): Promise<TransactionResult>;
     /**
      * Read the data at this location once.
      */
@@ -138,12 +184,10 @@ declare class DatabaseReference {
     orderByPriority(): DatabaseReference;
     /**
      * Order results by a child key.
-     * NOTE: Phase 2 - not yet implemented on server.
      */
     orderByChild(path: string): DatabaseReference;
     /**
      * Order results by value.
-     * NOTE: Phase 2 - not yet implemented on server.
      */
     orderByValue(): DatabaseReference;
     /**
@@ -156,17 +200,14 @@ declare class DatabaseReference {
     limitToLast(limit: number): DatabaseReference;
     /**
      * Start at a specific value/key.
-     * NOTE: Phase 2 - not yet implemented on server.
      */
     startAt(value: unknown, key?: string): DatabaseReference;
     /**
      * End at a specific value/key.
-     * NOTE: Phase 2 - not yet implemented on server.
      */
     endAt(value: unknown, key?: string): DatabaseReference;
     /**
      * Filter to items equal to a specific value.
-     * NOTE: Phase 2 - not yet implemented on server.
      */
     equalTo(value: unknown, key?: string): DatabaseReference;
     /**
@@ -191,9 +232,11 @@ declare class DataSnapshot {
     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;
     });
     /**
      * Get a DatabaseReference for the location of this snapshot.
@@ -240,6 +283,13 @@ declare class DataSnapshot {
      * This is a Lark extension not present in Firebase.
      */
     isVolatile(): boolean;
+    /**
+     * Get the server timestamp for this snapshot (milliseconds since Unix epoch).
+     * Only present on volatile value events. Use deltas between timestamps for
+     * interpolation rather than absolute times to avoid clock sync issues.
+     * This is a Lark extension not present in Firebase.
+     */
+    getServerTimestamp(): number | null;
     /**
      * Export the snapshot data as JSON (alias for val()).
      */
@@ -247,16 +297,50 @@ declare class DataSnapshot {
 }
 
 interface QueryParams {
-    ob?: 'k' | 'p';
-    lf?: number;
-    ll?: number;
+    orderBy?: 'key' | 'priority' | 'child' | 'value';
+    orderByChild?: string;
+    limitToFirst?: number;
+    limitToLast?: number;
+    startAt?: unknown;
+    startAtKey?: string;
+    endAt?: unknown;
+    endAtKey?: string;
+    equalTo?: unknown;
+    equalToKey?: string;
+}
+interface TxSetOp {
+    o: 's';
+    p: string;
+    v: unknown;
+}
+interface TxUpdateOp {
+    o: 'u';
+    p: string;
+    v: Record<string, unknown>;
+}
+interface TxDeleteOp {
+    o: 'd';
+    p: string;
+}
+interface TxConditionOp {
+    o: 'c';
+    p: string;
+    v: unknown;
+}
+type TxOperation = TxSetOp | TxUpdateOp | TxDeleteOp | TxConditionOp;
+interface MoveEntry {
+    k: string;
+    ak: string;
 }
 
 /**
  * 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.
+ * 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.
+ *
+ * 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.
  */
 
 type SnapshotCallback = (snapshot: DataSnapshot, previousChildKey?: string | null) => void;
@@ -278,14 +362,43 @@ interface AuthInfo {
     provider: string;
     token: Record<string, unknown>;
 }
+/** A set operation in a transaction */
+interface TransactionSetOp {
+    op: 'set';
+    path: string;
+    value: unknown;
+}
+/** An update (merge) operation in a transaction */
+interface TransactionUpdateOp {
+    op: 'update';
+    path: string;
+    value: Record<string, unknown>;
+}
+/** A delete operation in a transaction */
+interface TransactionDeleteOp {
+    op: 'delete';
+    path: string;
+}
+/** A condition check in a transaction (for compare-and-swap) */
+interface TransactionConditionOp {
+    op: 'condition';
+    path: string;
+    value: unknown;
+}
+/** A single operation in a transaction (array syntax) */
+type TransactionOp = TransactionSetOp | TransactionUpdateOp | TransactionDeleteOp | TransactionConditionOp;
+/** Object syntax for transactions: path -> value (null = delete) */
+type TransactionObject = Record<string, unknown>;
 declare class LarkDatabase {
     private _state;
     private _auth;
     private _databaseId;
     private _coordinatorUrl;
+    private _volatilePaths;
     private ws;
     private messageQueue;
     private subscriptionManager;
+    private pendingWrites;
     private connectCallbacks;
     private disconnectCallbacks;
     private errorCallbacks;
@@ -302,6 +415,26 @@ 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[];
+    /**
+     * Check if there are any pending writes waiting for acknowledgment.
+     * Useful for showing "saving..." indicators in UI.
+     */
+    hasPendingWrites(): boolean;
+    /**
+     * Get the number of pending writes waiting for acknowledgment.
+     */
+    getPendingWriteCount(): number;
+    /**
+     * Clear all pending writes.
+     * Call this if you don't want to retry writes on reconnect.
+     */
+    clearPendingWrites(): void;
     /**
      * Connect to a database.
      *
@@ -322,6 +455,48 @@ declare class LarkDatabase {
      * Get a reference to a path in the database.
      */
     ref(path?: string): DatabaseReference;
+    /**
+     * Execute an atomic transaction with multiple operations.
+     *
+     * Supports two syntaxes:
+     *
+     * **Object syntax** (like Firebase multi-path update):
+     * ```javascript
+     * await db.transaction({
+     *   '/users/alice/name': 'Alice',
+     *   '/users/alice/score': 100,
+     *   '/temp/data': null  // null = delete
+     * });
+     * ```
+     *
+     * **Array syntax** (explicit operations):
+     * ```javascript
+     * await db.transaction([
+     *   { op: 'set', path: '/users/alice/name', value: 'Alice' },
+     *   { op: 'update', path: '/metadata', value: { lastUpdated: '...' } },
+     *   { op: 'delete', path: '/temp/data' },
+     *   { op: 'condition', path: '/counter', value: 5 }  // CAS check
+     * ]);
+     * ```
+     *
+     * All operations are atomic: either all succeed or all fail.
+     * Conditions are checked first; if any fail, the transaction is rejected
+     * with error code 'condition_failed'.
+     */
+    transaction(operations: TransactionOp[] | TransactionObject): Promise<void>;
+    /**
+     * Convert a public TransactionOp to wire format TxOperation.
+     */
+    private convertToTxOp;
+    /**
+     * Convert object syntax to wire format TxOperations.
+     * Each path becomes a set operation, null values become deletes.
+     */
+    private convertObjectToTxOps;
+    /**
+     * @internal Send a transaction to the server.
+     */
+    _sendTransaction(ops: TxOperation[]): Promise<void>;
     /**
      * Register a callback for when connection is established.
      * Returns an unsubscribe function.
@@ -389,7 +564,7 @@ declare class LarkDatabase {
     /**
      * @internal Subscribe to events at a path.
      */
-    _subscribe(path: string, eventType: EventType, callback: SnapshotCallback): () => void;
+    _subscribe(path: string, eventType: EventType, callback: SnapshotCallback, queryParams?: QueryParams): () => void;
     /**
      * @internal Unsubscribe from a specific event type at a path.
      */
@@ -408,6 +583,67 @@ declare class LarkError extends Error {
     constructor(code: string, message?: string);
 }
 
+/**
+ * PendingWriteManager - tracks pending write operations for optimistic updates.
+ *
+ * Each write operation is assigned a unique operation ID (oid). The manager tracks
+ * 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';
+interface PendingWrite {
+    oid: string;
+    operation: WriteOperation;
+    path: string;
+    value?: unknown;
+    timestamp: number;
+}
+declare class PendingWriteManager {
+    private pending;
+    private counter;
+    /**
+     * Generate a unique operation ID.
+     * Format: op_{timestamp}_{counter}_{random}
+     */
+    generateOid(): string;
+    /**
+     * Track a new pending write operation.
+     */
+    trackWrite(oid: string, operation: WriteOperation, path: string, value?: unknown): void;
+    /**
+     * Called when a write is acknowledged by the server.
+     * Removes the write from pending tracking.
+     */
+    onAck(oid: string): boolean;
+    /**
+     * Called when a write is rejected by the server.
+     * Removes the write from pending tracking.
+     */
+    onNack(oid: string): boolean;
+    /**
+     * Get all pending writes for retry on reconnect.
+     * Returns writes in order of their timestamps (oldest first).
+     */
+    getPendingWrites(): PendingWrite[];
+    /**
+     * Check if a specific operation is still pending.
+     */
+    isPending(oid: string): boolean;
+    /**
+     * Get the number of pending writes.
+     */
+    get pendingCount(): number;
+    /**
+     * Clear all pending writes (e.g., on disconnect when not retrying).
+     */
+    clear(): void;
+    /**
+     * Remove writes older than a specified age (in milliseconds).
+     * Useful for cleaning up stale pending writes that may never be acked.
+     */
+    removeStale(maxAgeMs: number): number;
+}
+
 /**
  * Push ID generation - Firebase-compatible chronologically-sortable IDs.
  *
@@ -424,4 +660,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, 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 };