@lark-sh/client 0.1.9 → 0.1.11

package/dist/index.d.mts

@@ -59,10 +59,18 @@ interface QueryState {
         value: unknown;
         key?: string;
     };
+    startAfter?: {
+        value: unknown;
+        key?: string;
+    };
     endAt?: {
         value: unknown;
         key?: string;
     };
+    endBefore?: {
+        value: unknown;
+        key?: string;
+    };
     equalTo?: {
         value: unknown;
         key?: string;
@@ -89,6 +97,38 @@ declare class DatabaseReference {
      * Get a reference to the root of the database.
      */
     get root(): DatabaseReference;
+    /**
+     * Get the LarkDatabase instance this reference belongs to.
+     */
+    get database(): LarkDatabase;
+    /**
+     * Get the underlying reference for a query.
+     * For queries (created via orderBy*, limitTo*, startAt, etc.), this returns
+     * a reference to the same path without query constraints.
+     * For non-query references, this returns the reference itself.
+     * This matches Firebase's Query.ref behavior.
+     */
+    get ref(): DatabaseReference;
+    /**
+     * Check if this reference/query is equal to another.
+     * Two references are equal if they have the same database, path, and query constraints.
+     */
+    isEqual(other: DatabaseReference | null): boolean;
+    /**
+     * Get the unique identifier for this query's parameters.
+     * Used to differentiate multiple queries on the same path.
+     *
+     * Returns "default" for non-query references (no constraints).
+     * Returns a sorted JSON string of wire-format params for queries.
+     *
+     * This matches Firebase's queryIdentifier format for wire compatibility.
+     */
+    get queryIdentifier(): string;
+    /**
+     * Get the data at this location. Alias for once('value').
+     * This is Firebase's newer API for reading data.
+     */
+    get(): Promise<DataSnapshot>;
     /**
      * Get a reference to a child path.
      */
@@ -98,6 +138,8 @@ declare class DatabaseReference {
      *
      * For volatile paths (high-frequency updates), this is fire-and-forget
      * and resolves immediately without waiting for server confirmation.
+     *
+     * @param value - The value to write
      */
     set(value: unknown): Promise<void>;
     /**
@@ -118,6 +160,8 @@ declare class DatabaseReference {
      *   '/leaderboard/alice': null  // null = delete
      * });
      * ```
+     *
+     * @param values - The values to update
      */
     update(values: Record<string, unknown>): Promise<void>;
     /**
@@ -129,16 +173,38 @@ declare class DatabaseReference {
     /**
      * Generate a new child location with a unique key and optionally set its value.
      *
-     * If value is provided, sets the value and returns a Promise that resolves
-     * to the new reference.
+     * Returns a ThenableReference - an object that is both a DatabaseReference
+     * AND a Promise. You can access reference properties immediately (like `.key`)
+     * and also await the result.
      *
-     * If no value is provided, returns a reference immediately with a client-generated
-     * push key (you can then call set() on it).
+     * If value is provided, the promise resolves after the write completes.
+     * If no value is provided, the promise resolves immediately.
+     *
+     * @example
+     * ```javascript
+     * // Without value - returns ThenableReference, resolves immediately
+     * const pushed = ref.push();
+     * console.log(pushed.key); // "-Abc123..." (available immediately)
+     * await pushed; // Resolves immediately to the same reference
+     *
+     * // With value - returns ThenableReference, resolves after write
+     * const pushed2 = ref.push({ name: 'Alice' });
+     * console.log(pushed2.key); // "-Xyz789..." (available immediately)
+     * await pushed2; // Waits for write to complete
+     * ```
      */
-    push(value?: unknown): DatabaseReference | Promise<DatabaseReference>;
+    push(): ThenableReference;
+    push(value: unknown): ThenableReference;
     /**
      * Set the data with a priority value for ordering.
-     * Priority is injected as `.priority` into the value object.
+     *
+     * For objects: injects `.priority` into the value object.
+     * For primitives: wraps as `{ '.value': primitive, '.priority': priority }`.
+     *
+     * This follows Firebase's wire format for primitives with priority.
+     *
+     * @param value - The value to write
+     * @param priority - The priority for ordering
      */
     setWithPriority(value: unknown, priority: number | string): Promise<void>;
     /**
@@ -168,9 +234,12 @@ declare class DatabaseReference {
      * @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>;
+    transaction(updateFunction: (currentValue: any) => any, maxRetries?: number): Promise<TransactionResult>;
     /**
      * Read the data at this location once.
+     *
+     * @param eventType - The event type (only 'value' is supported)
+     * @returns Promise that resolves to the DataSnapshot
      */
     once(eventType?: 'value'): Promise<DataSnapshot>;
     /**
@@ -180,8 +249,14 @@ declare class DatabaseReference {
     on(eventType: EventType, callback: SnapshotCallback$1): () => void;
     /**
      * Unsubscribe from events.
-     * If eventType is specified, removes all listeners of that type.
-     * If no eventType, removes ALL listeners at this path.
+     *
+     * - `off()` - removes ALL listeners at this path
+     * - `off('value')` - removes all 'value' listeners at this path
+     *
+     * Note: To unsubscribe a specific callback, use the unsubscribe function
+     * returned by `on()`.
+     *
+     * @param eventType - Optional event type to unsubscribe from
      */
     off(eventType?: EventType): void;
     /**
@@ -214,16 +289,52 @@ declare class DatabaseReference {
     limitToLast(limit: number): DatabaseReference;
     /**
      * Start at a specific value/key.
+     * If no value is provided, starts at the beginning (null priority).
      */
-    startAt(value: unknown, key?: string): DatabaseReference;
+    startAt(value?: unknown, key?: string): DatabaseReference;
+    /**
+     * Start after a specific value/key (exclusive).
+     * Like startAt() but excludes the starting point.
+     */
+    startAfter(value?: unknown, key?: string): DatabaseReference;
     /**
      * End at a specific value/key.
+     * If no value is provided, ends at the end (null priority).
+     */
+    endAt(value?: unknown, key?: string): DatabaseReference;
+    /**
+     * End before a specific value/key (exclusive).
+     * Like endAt() but excludes the ending point.
      */
-    endAt(value: unknown, key?: string): DatabaseReference;
+    endBefore(value?: unknown, key?: string): DatabaseReference;
     /**
      * Filter to items equal to a specific value.
      */
     equalTo(value: unknown, key?: string): DatabaseReference;
+    /**
+     * Validate that no orderBy has been set yet.
+     */
+    private _validateNoOrderBy;
+    /**
+     * Validate that no key parameter has been set on startAt/endAt/equalTo.
+     * Used when calling orderByKey() after startAt/endAt/equalTo.
+     */
+    private _validateNoKeyParameterForOrderByKey;
+    /**
+     * Validate that startAt/endAt/equalTo values are strings.
+     * Used when calling orderByKey() after startAt/endAt/equalTo.
+     */
+    private _validateStringValuesForOrderByKey;
+    /**
+     * Validate value and key types for query methods (startAt, endAt, equalTo, etc.)
+     */
+    private _validateQueryValue;
+    /**
+     * Validate that a key is a valid Firebase key format.
+     * Invalid characters: . $ # [ ] /
+     * Also cannot start or end with .
+     */
+    private _validateKeyFormat;
     /**
      * Build query parameters for wire protocol.
      */
@@ -234,6 +345,65 @@ declare class DatabaseReference {
      */
     toString(): string;
 }
+/**
+ * A reference that is also a Promise - returned by push().
+ *
+ * This allows Firebase-compatible patterns like:
+ * ```javascript
+ * const pushed = ref.push();
+ * console.log(pushed.key); // Key available immediately
+ * await pushed; // Wait for write to complete
+ * ```
+ */
+declare class ThenableReference extends DatabaseReference implements PromiseLike<DatabaseReference> {
+    private readonly _promise;
+    constructor(db: LarkDatabase, path: string, promise?: Promise<DatabaseReference>);
+    then<TResult1 = DatabaseReference, TResult2 = never>(onfulfilled?: ((value: DatabaseReference) => TResult1 | PromiseLike<TResult1>) | undefined | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | undefined | null): Promise<TResult1 | TResult2>;
+    catch<TResult = never>(onrejected?: ((reason: unknown) => TResult | PromiseLike<TResult>) | undefined | null): Promise<DatabaseReference | TResult>;
+}
+
+interface QueryParams {
+    orderBy?: 'key' | 'priority' | 'child' | 'value';
+    orderByChild?: string;
+    limitToFirst?: number;
+    limitToLast?: number;
+    startAt?: unknown;
+    startAtKey?: string;
+    startAfter?: unknown;
+    startAfterKey?: string;
+    endAt?: unknown;
+    endAtKey?: string;
+    endBefore?: unknown;
+    endBeforeKey?: 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 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;
 
 /**
  * DataSnapshot - an immutable snapshot of data at a location.
@@ -244,6 +414,11 @@ declare class DatabaseReference {
  * - 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
+ *
+ * Wrapped Primitives:
+ * - Primitives with priority are stored as `{ '.value': x, '.priority': y }`
+ * - val() automatically unwraps these to return just the primitive value
+ * - This follows Firebase's wire format for primitives with priority
  */
 
 declare class DataSnapshot {
@@ -252,9 +427,13 @@ declare class DataSnapshot {
     private readonly _db;
     private readonly _volatile;
     private readonly _serverTimestamp;
+    private readonly _queryParams;
+    private readonly _orderedKeys;
     constructor(data: unknown, path: string, db: LarkDatabase, options?: {
         volatile?: boolean;
         serverTimestamp?: number | null;
+        queryParams?: QueryParams | null;
+        orderedKeys?: string[] | null;
     });
     /**
      * Get a DatabaseReference for the location of this snapshot.
@@ -265,32 +444,59 @@ declare class DataSnapshot {
      */
     get key(): string | null;
     /**
-     * Get the data value, with `.priority` stripped if present.
-     * Priority is internal metadata and should not be visible to app code.
+     * Get the data value, with metadata stripped.
+     *
+     * - Strips `.priority` from objects (it's metadata, not user data)
+     * - Unwraps `{ '.value': x, '.priority': y }` to just `x` (wrapped primitives)
+     *
+     * @typeParam T - Optional type for the returned value. Defaults to `any`.
+     * @example
+     * ```typescript
+     * // Untyped (returns any)
+     * const data = snapshot.val();
+     *
+     * // Typed (returns User)
+     * const user = snapshot.val<User>();
+     * ```
      */
-    val(): unknown;
+    val<T = any>(): T;
     /**
      * Check if data exists at this location (is not null/undefined).
      */
     exists(): boolean;
     /**
      * Get a child snapshot at the specified path.
+     *
+     * Special handling:
+     * - `.priority` returns the priority value (Firebase compatible)
+     * - For wrapped primitives, only `.priority` returns data; other paths return null
+     * - Non-existent paths return a snapshot with val() === null (Firebase compatible)
      */
     child(path: string): DataSnapshot;
     /**
      * Check if this snapshot has any children.
+     * Excludes `.priority` metadata from consideration.
+     * Wrapped primitives have no children.
      */
     hasChildren(): boolean;
     /**
      * Check if this snapshot has a specific child.
+     * `.priority` is always accessible if it exists.
+     * Wrapped primitives have no children except `.priority`.
      */
     hasChild(path: string): boolean;
     /**
      * Get the number of children.
+     * Excludes `.priority` metadata from count.
+     * Wrapped primitives have 0 children.
      */
     numChildren(): number;
     /**
-     * Iterate over children. Return true from callback to stop iteration.
+     * Iterate over children in the correct order.
+     * Uses pre-computed orderedKeys if available (from subscription View),
+     * otherwise computes sorted keys based on query params.
+     * Excludes `.priority` metadata from iteration.
+     * Wrapped primitives have no children to iterate.
      */
     forEach(callback: (child: DataSnapshot) => boolean | void): void;
     /**
@@ -311,49 +517,21 @@ declare class DataSnapshot {
      */
     getServerTimestamp(): number | null;
     /**
-     * Export the snapshot data as JSON (alias for val()).
+     * Export the snapshot data with priority metadata intact.
+     * Unlike val(), this preserves `.value` and `.priority` wrappers.
+     * Useful for serializing data while preserving priorities.
+     *
+     * @typeParam T - Optional type for the returned value. Defaults to `any`.
      */
-    toJSON(): unknown;
-}
-
-interface QueryParams {
-    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 TxConditionValueOp {
-    o: 'c';
-    p: string;
-    v: unknown;
-}
-interface TxConditionHashOp {
-    o: 'c';
-    p: string;
-    h: string;
+    exportVal<T = any>(): T;
+    /**
+     * Export the snapshot data as JSON.
+     * Same as exportVal() - preserves priority metadata.
+     *
+     * @typeParam T - Optional type for the returned value. Defaults to `any`.
+     */
+    toJSON<T = any>(): T;
 }
-type TxConditionOp = TxConditionValueOp | TxConditionHashOp;
-type TxOperation = TxSetOp | TxUpdateOp | TxDeleteOp | TxConditionOp;
 
 /**
  * View - represents a client's subscription to a database path.
@@ -391,6 +569,13 @@ interface ConnectOptions {
      * - '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;
@@ -425,7 +610,85 @@ type TransactionOp = TransactionSetOp | TransactionUpdateOp | TransactionDeleteO
 /** Object syntax for transactions: path -> value (null = delete) */
 type TransactionObject = Record<string, unknown>;
 type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting';
+/**
+ * Server values that are resolved by the server when a write is committed.
+ * Use these with set(), update(), or push() to have the server fill in values.
+ */
+declare const ServerValue: {
+    /**
+     * A placeholder value for auto-populating the current server timestamp.
+     * The server will replace this with the actual Unix timestamp in milliseconds.
+     *
+     * @example
+     * ```javascript
+     * import { ServerValue } from '@lark-sh/client';
+     * await ref.set({ createdAt: ServerValue.TIMESTAMP });
+     * // Server stores: { createdAt: 1704067200000 }
+     * ```
+     */
+    TIMESTAMP: {
+        readonly '.sv': "timestamp";
+    };
+    /**
+     * Returns a placeholder value for atomically incrementing a numeric field.
+     * If the field doesn't exist or isn't a number, it's treated as 0.
+     *
+     * @param delta - The amount to increment by (can be negative to decrement)
+     * @returns A server value placeholder
+     *
+     * @example
+     * ```javascript
+     * import { ServerValue } from '@lark-sh/client';
+     * await ref.child('score').set(ServerValue.increment(10));
+     * // Atomically adds 10 to the current score
+     * ```
+     */
+    increment: (delta: number) => {
+        '.sv': {
+            increment: number;
+        };
+    };
+};
 declare class LarkDatabase {
+    /**
+     * Server values that are resolved by the server when a write is committed.
+     * Alias for the exported ServerValue object.
+     */
+    static ServerValue: {
+        /**
+         * A placeholder value for auto-populating the current server timestamp.
+         * The server will replace this with the actual Unix timestamp in milliseconds.
+         *
+         * @example
+         * ```javascript
+         * import { ServerValue } from '@lark-sh/client';
+         * await ref.set({ createdAt: ServerValue.TIMESTAMP });
+         * // Server stores: { createdAt: 1704067200000 }
+         * ```
+         */
+        TIMESTAMP: {
+            readonly '.sv': "timestamp";
+        };
+        /**
+         * Returns a placeholder value for atomically incrementing a numeric field.
+         * If the field doesn't exist or isn't a number, it's treated as 0.
+         *
+         * @param delta - The amount to increment by (can be negative to decrement)
+         * @returns A server value placeholder
+         *
+         * @example
+         * ```javascript
+         * import { ServerValue } from '@lark-sh/client';
+         * await ref.child('score').set(ServerValue.increment(10));
+         * // Atomically adds 10 to the current score
+         * ```
+         */
+        increment: (delta: number) => {
+            '.sv': {
+                increment: number;
+            };
+        };
+    };
     private _state;
     private _auth;
     private _databaseId;
@@ -445,6 +708,8 @@ declare class LarkDatabase {
     private disconnectCallbacks;
     private errorCallbacks;
     private reconnectingCallbacks;
+    private infoSubscriptions;
+    private _serverTimeOffset;
     constructor();
     /**
      * Whether the database is currently connected.
@@ -476,6 +741,11 @@ declare class LarkDatabase {
      * Returns 'websocket' or 'webtransport', or null if not connected.
      */
     get transportType(): 'websocket' | 'webtransport' | null;
+    /**
+     * Get the estimated server time offset in milliseconds.
+     * Add this to Date.now() to get approximate server time.
+     */
+    get serverTimeOffset(): number;
     /**
      * Check if there are any pending writes waiting for acknowledgment.
      * Useful for showing "saving..." indicators in UI.
@@ -506,6 +776,16 @@ declare class LarkDatabase {
      * This triggers onDisconnect hooks on the server.
      */
     disconnect(): Promise<void>;
+    /**
+     * Temporarily disable the connection.
+     * Disconnects from the server but preserves subscriptions for later reconnection via goOnline().
+     */
+    goOffline(): void;
+    /**
+     * Re-enable the connection after goOffline().
+     * Reconnects to the database and restores subscriptions.
+     */
+    goOnline(): void;
     /**
      * Full cleanup - clears all state including subscriptions.
      * Used for intentional disconnect.
@@ -516,6 +796,27 @@ declare class LarkDatabase {
      * Used for unexpected disconnect.
      */
     private cleanupForReconnect;
+    /**
+     * Check if a path is a .info path (handled locally).
+     */
+    private isInfoPath;
+    /**
+     * Get the current value for a .info path.
+     */
+    private getInfoValue;
+    /**
+     * Subscribe to a .info path.
+     * Returns an unsubscribe function.
+     */
+    private subscribeToInfo;
+    /**
+     * Fire events for .info path changes.
+     */
+    private fireInfoEvents;
+    /**
+     * Fire connection state change events to .info/connected subscribers.
+     */
+    private fireConnectionStateChange;
     /**
      * Schedule a reconnection attempt with exponential backoff.
      */
@@ -663,10 +964,12 @@ declare class LarkDatabase {
     _sendOnDisconnect(path: string, action: string, value?: unknown): Promise<void>;
     /**
      * @internal Send a subscribe message to server.
+     * Includes tag for non-default queries to enable proper event routing.
      */
     private sendSubscribeMessage;
     /**
      * @internal Send an unsubscribe message to server.
+     * Includes query params and tag so server can identify which specific subscription to remove.
      */
     private sendUnsubscribeMessage;
     /**
@@ -676,7 +979,7 @@ declare class LarkDatabase {
     /**
      * @internal Subscribe to events at a path.
      */
-    _subscribe(path: string, eventType: EventType, callback: SnapshotCallback, queryParams?: QueryParams): () => void;
+    _subscribe(path: string, eventType: EventType, callback: SnapshotCallback, queryParams?: QueryParams, queryIdentifier?: string): () => void;
     /**
      * @internal Unsubscribe from a specific event type at a path.
      */
@@ -800,4 +1103,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 TransportType, type WriteOperation, generatePushId, isVolatilePath };
+export { type AuthInfo, type ConnectOptions, DataSnapshot, DatabaseReference, type EventType, LarkDatabase, LarkError, OnDisconnect, type PendingWrite, PendingWriteManager, type QueryParams, type QueryState, ServerValue, type SnapshotCallback$1 as SnapshotCallback, ThenableReference, type TransactionConditionOp, type TransactionDeleteOp, type TransactionObject, type TransactionOp, type TransactionResult, type TransactionSetOp, type TransactionUpdateOp, type TransportType, type WriteOperation, generatePushId, isVolatilePath };