@lark-sh/client 0.1.12 → 0.1.14

package/dist/fb-v8/index.d.mts

@@ -0,0 +1,195 @@
+import { EventType, SnapshotCallback, AuthInfo, ConnectOptions, TransactionOp, TransactionObject, DatabaseReference as DatabaseReference$1, ThenableReference as ThenableReference$1, TransactionResult, DataSnapshot, OnDisconnect } from '../index.mjs';
+export { LarkError, PendingWriteManager, QueryParams, QueryState, ServerValue, TransactionConditionOp, TransactionDeleteOp, TransactionSetOp, TransactionUpdateOp, TransportType, generatePushId, isVolatilePath } from '../index.mjs';
+
+/**
+ * Firebase v8 Compatibility Layer
+ *
+ * This module provides Firebase v8-style behavior for users migrating from Firebase.
+ *
+ * Key differences from modern API:
+ * 1. on() returns the callback (not an unsubscribe function)
+ * 2. off(eventType, callback, context?) removes specific listener by callback reference
+ * 3. once(eventType, successCallback, cancelCallback, context?) supports callback style
+ * 4. Context parameter binds `this` inside callbacks
+ *
+ * @example
+ * ```typescript
+ * import { LarkDatabase, DatabaseReference } from '@lark-sh/client/fb-v8';
+ *
+ * const db = new LarkDatabase();
+ * await db.connect('project/database', { anonymous: true });
+ *
+ * const ref = db.ref('players');
+ * const callback = ref.on('value', (snap) => console.log(snap.val()));
+ * // callback === the function you passed in
+ *
+ * // Later: remove by callback reference (works from any ref at same path)
+ * ref.off('value', callback);
+ *
+ * // With context (binds `this`):
+ * ref.on('value', this.handleValue, this);
+ * ref.off('value', this.handleValue, this);
+ * ```
+ */
+
+/**
+ * Firebase v8 compatible DatabaseReference.
+ * Wraps the modern DatabaseReference with v8-style on/off behavior.
+ */
+declare class DatabaseReference {
+    private readonly _modernRef;
+    private readonly _db;
+    constructor(db: LarkDatabase, modernRef: DatabaseReference$1);
+    get path(): string;
+    get key(): string | null;
+    get parent(): DatabaseReference | null;
+    get root(): DatabaseReference;
+    get database(): LarkDatabase;
+    /**
+     * Get the underlying reference for a query.
+     * For queries, returns a reference without query constraints.
+     */
+    get ref(): DatabaseReference;
+    get queryIdentifier(): string;
+    child(path: string): DatabaseReference;
+    set(value: unknown): Promise<void>;
+    update(values: Record<string, unknown>): Promise<void>;
+    remove(): Promise<void>;
+    push(): ThenableReference;
+    push(value: unknown): ThenableReference;
+    setWithPriority(value: unknown, priority: number | string): Promise<void>;
+    setPriority(priority: number | string | null): Promise<void>;
+    transaction(updateFunction: (currentValue: unknown) => unknown, maxRetries?: number): Promise<TransactionResult>;
+    get(): Promise<DataSnapshot>;
+    /**
+     * Read data once.
+     *
+     * Supports both promise style and Firebase v8 callback style:
+     * - `once('value')` - returns Promise<DataSnapshot>
+     * - `once('value', callback)` - calls callback with snapshot, returns Promise
+     * - `once('value', callback, cancelCallback)` - also handles errors
+     * - `once('value', callback, cancelCallback, context)` - binds `this` to context
+     */
+    once(eventType?: EventType): Promise<DataSnapshot>;
+    once(eventType: EventType, successCallback: SnapshotCallback, cancelCallback?: (error: Error) => void, context?: unknown): Promise<DataSnapshot>;
+    /**
+     * Subscribe to events at this location.
+     *
+     * **Firebase v8 behavior**: Returns the callback function (not an unsubscribe function).
+     * Use `off(eventType, callback, context?)` to remove the listener.
+     *
+     * Note: Callbacks are tracked globally by path, so off() on any ref at the same
+     * path can remove this callback by reference.
+     *
+     * @param eventType - The event type to listen for
+     * @param callback - The callback to invoke
+     * @param cancelCallbackOrContext - Optional cancel callback or context
+     * @param context - Optional context to bind `this` in callback
+     * @returns The callback function (for use with off())
+     */
+    on(eventType: EventType, callback: SnapshotCallback, cancelCallbackOrContext?: ((error: Error) => void) | unknown, context?: unknown): SnapshotCallback;
+    /**
+     * Unsubscribe from events.
+     *
+     * **Firebase v8 behavior**: Can remove specific listeners by callback reference.
+     *
+     * - `off()` - removes all listeners on this specific query (or all queries if base ref)
+     * - `off('value')` - removes all 'value' listeners on this specific query
+     * - `off('value', callback)` - removes callback (any context) from ANY query at this path
+     * - `off('value', callback, context)` - removes specific callback+context combo
+     */
+    off(eventType?: EventType, callback?: SnapshotCallback, context?: unknown): void;
+    onDisconnect(): OnDisconnect;
+    orderByKey(): DatabaseReference;
+    orderByPriority(): DatabaseReference;
+    orderByChild(path: string): DatabaseReference;
+    orderByValue(): DatabaseReference;
+    limitToFirst(limit: number): DatabaseReference;
+    limitToLast(limit: number): DatabaseReference;
+    startAt(value?: unknown, key?: string): DatabaseReference;
+    startAfter(value?: unknown, key?: string): DatabaseReference;
+    endAt(value?: unknown, key?: string): DatabaseReference;
+    endBefore(value?: unknown, key?: string): DatabaseReference;
+    equalTo(value: unknown, key?: string): DatabaseReference;
+    isEqual(other: DatabaseReference | null): boolean;
+    toString(): string;
+    toJSON(): string;
+}
+/**
+ * Firebase v8 compatible ThenableReference.
+ */
+declare class ThenableReference extends DatabaseReference implements PromiseLike<DatabaseReference> {
+    private readonly _modernThenable;
+    constructor(db: LarkDatabase, modernThenable: ThenableReference$1);
+    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>;
+}
+/**
+ * Firebase v8 compatible LarkDatabase.
+ * Returns Firebase v8 compatible references.
+ */
+declare class LarkDatabase {
+    private readonly _modernDb;
+    /**
+     * Global callback registry for Firebase v8 compatibility.
+     * Structure: path -> eventType -> callback -> unsubscribe function
+     */
+    private readonly _callbackRegistry;
+    static ServerValue: {
+        TIMESTAMP: {
+            readonly '.sv': "timestamp";
+        };
+        increment: (delta: number) => {
+            '.sv': {
+                increment: number;
+            };
+        };
+    };
+    constructor();
+    /**
+     * @internal Register a callback in the global registry.
+     */
+    _registerCallback(path: string, queryId: string, eventType: EventType, callback: SnapshotCallback, context: unknown, unsubscribe: () => void): void;
+    /**
+     * @internal Unregister callbacks from the global registry.
+     *
+     * Behavior:
+     * - With callback+context: Finds and removes that specific callback+context combo from ANY query
+     * - With callback only: Removes ALL registrations of that callback (any context) from ANY query
+     * - Without callback: Removes all callbacks from the specified query only
+     *   - If queryId is 'default' (base ref), removes from ALL queries at the path
+     */
+    _unregisterCallback(path: string, queryId: string, eventType?: EventType, callback?: SnapshotCallback, context?: unknown): void;
+    /**
+     * @internal Clean up empty nested maps in the registry.
+     */
+    private _cleanupEmptyMaps;
+    get connected(): boolean;
+    get reconnecting(): boolean;
+    get state(): string;
+    get auth(): AuthInfo | null;
+    get volatilePaths(): string[];
+    get transportType(): 'websocket' | 'webtransport' | null;
+    get serverTimeOffset(): number;
+    hasPendingWrites(): boolean;
+    getPendingWriteCount(): number;
+    clearPendingWrites(): void;
+    connect(databaseId: string, options?: ConnectOptions): Promise<void>;
+    disconnect(): Promise<void>;
+    goOffline(): void;
+    goOnline(): void;
+    /**
+     * Get a Firebase v8 compatible reference to a path.
+     */
+    ref(path?: string): DatabaseReference;
+    transaction(operations: TransactionOp[] | TransactionObject): Promise<void>;
+    onConnect(callback: () => void): () => void;
+    onDisconnect(callback: () => void): () => void;
+    onError(callback: (error: Error) => void): () => void;
+    onReconnecting(callback: () => void): () => void;
+    onAuthStateChanged(callback: (auth: AuthInfo | null) => void): () => void;
+    signIn(token: string): Promise<void>;
+    signOut(): Promise<void>;
+}
+
+export { AuthInfo, ConnectOptions, DataSnapshot, DatabaseReference, EventType, LarkDatabase, OnDisconnect, SnapshotCallback, ThenableReference, TransactionObject, TransactionOp, TransactionResult };

package/dist/fb-v8/index.d.ts

@@ -0,0 +1,195 @@
+import { EventType, SnapshotCallback, AuthInfo, ConnectOptions, TransactionOp, TransactionObject, DatabaseReference as DatabaseReference$1, ThenableReference as ThenableReference$1, TransactionResult, DataSnapshot, OnDisconnect } from '../index.js';
+export { LarkError, PendingWriteManager, QueryParams, QueryState, ServerValue, TransactionConditionOp, TransactionDeleteOp, TransactionSetOp, TransactionUpdateOp, TransportType, generatePushId, isVolatilePath } from '../index.js';
+
+/**
+ * Firebase v8 Compatibility Layer
+ *
+ * This module provides Firebase v8-style behavior for users migrating from Firebase.
+ *
+ * Key differences from modern API:
+ * 1. on() returns the callback (not an unsubscribe function)
+ * 2. off(eventType, callback, context?) removes specific listener by callback reference
+ * 3. once(eventType, successCallback, cancelCallback, context?) supports callback style
+ * 4. Context parameter binds `this` inside callbacks
+ *
+ * @example
+ * ```typescript
+ * import { LarkDatabase, DatabaseReference } from '@lark-sh/client/fb-v8';
+ *
+ * const db = new LarkDatabase();
+ * await db.connect('project/database', { anonymous: true });
+ *
+ * const ref = db.ref('players');
+ * const callback = ref.on('value', (snap) => console.log(snap.val()));
+ * // callback === the function you passed in
+ *
+ * // Later: remove by callback reference (works from any ref at same path)
+ * ref.off('value', callback);
+ *
+ * // With context (binds `this`):
+ * ref.on('value', this.handleValue, this);
+ * ref.off('value', this.handleValue, this);
+ * ```
+ */
+
+/**
+ * Firebase v8 compatible DatabaseReference.
+ * Wraps the modern DatabaseReference with v8-style on/off behavior.
+ */
+declare class DatabaseReference {
+    private readonly _modernRef;
+    private readonly _db;
+    constructor(db: LarkDatabase, modernRef: DatabaseReference$1);
+    get path(): string;
+    get key(): string | null;
+    get parent(): DatabaseReference | null;
+    get root(): DatabaseReference;
+    get database(): LarkDatabase;
+    /**
+     * Get the underlying reference for a query.
+     * For queries, returns a reference without query constraints.
+     */
+    get ref(): DatabaseReference;
+    get queryIdentifier(): string;
+    child(path: string): DatabaseReference;
+    set(value: unknown): Promise<void>;
+    update(values: Record<string, unknown>): Promise<void>;
+    remove(): Promise<void>;
+    push(): ThenableReference;
+    push(value: unknown): ThenableReference;
+    setWithPriority(value: unknown, priority: number | string): Promise<void>;
+    setPriority(priority: number | string | null): Promise<void>;
+    transaction(updateFunction: (currentValue: unknown) => unknown, maxRetries?: number): Promise<TransactionResult>;
+    get(): Promise<DataSnapshot>;
+    /**
+     * Read data once.
+     *
+     * Supports both promise style and Firebase v8 callback style:
+     * - `once('value')` - returns Promise<DataSnapshot>
+     * - `once('value', callback)` - calls callback with snapshot, returns Promise
+     * - `once('value', callback, cancelCallback)` - also handles errors
+     * - `once('value', callback, cancelCallback, context)` - binds `this` to context
+     */
+    once(eventType?: EventType): Promise<DataSnapshot>;
+    once(eventType: EventType, successCallback: SnapshotCallback, cancelCallback?: (error: Error) => void, context?: unknown): Promise<DataSnapshot>;
+    /**
+     * Subscribe to events at this location.
+     *
+     * **Firebase v8 behavior**: Returns the callback function (not an unsubscribe function).
+     * Use `off(eventType, callback, context?)` to remove the listener.
+     *
+     * Note: Callbacks are tracked globally by path, so off() on any ref at the same
+     * path can remove this callback by reference.
+     *
+     * @param eventType - The event type to listen for
+     * @param callback - The callback to invoke
+     * @param cancelCallbackOrContext - Optional cancel callback or context
+     * @param context - Optional context to bind `this` in callback
+     * @returns The callback function (for use with off())
+     */
+    on(eventType: EventType, callback: SnapshotCallback, cancelCallbackOrContext?: ((error: Error) => void) | unknown, context?: unknown): SnapshotCallback;
+    /**
+     * Unsubscribe from events.
+     *
+     * **Firebase v8 behavior**: Can remove specific listeners by callback reference.
+     *
+     * - `off()` - removes all listeners on this specific query (or all queries if base ref)
+     * - `off('value')` - removes all 'value' listeners on this specific query
+     * - `off('value', callback)` - removes callback (any context) from ANY query at this path
+     * - `off('value', callback, context)` - removes specific callback+context combo
+     */
+    off(eventType?: EventType, callback?: SnapshotCallback, context?: unknown): void;
+    onDisconnect(): OnDisconnect;
+    orderByKey(): DatabaseReference;
+    orderByPriority(): DatabaseReference;
+    orderByChild(path: string): DatabaseReference;
+    orderByValue(): DatabaseReference;
+    limitToFirst(limit: number): DatabaseReference;
+    limitToLast(limit: number): DatabaseReference;
+    startAt(value?: unknown, key?: string): DatabaseReference;
+    startAfter(value?: unknown, key?: string): DatabaseReference;
+    endAt(value?: unknown, key?: string): DatabaseReference;
+    endBefore(value?: unknown, key?: string): DatabaseReference;
+    equalTo(value: unknown, key?: string): DatabaseReference;
+    isEqual(other: DatabaseReference | null): boolean;
+    toString(): string;
+    toJSON(): string;
+}
+/**
+ * Firebase v8 compatible ThenableReference.
+ */
+declare class ThenableReference extends DatabaseReference implements PromiseLike<DatabaseReference> {
+    private readonly _modernThenable;
+    constructor(db: LarkDatabase, modernThenable: ThenableReference$1);
+    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>;
+}
+/**
+ * Firebase v8 compatible LarkDatabase.
+ * Returns Firebase v8 compatible references.
+ */
+declare class LarkDatabase {
+    private readonly _modernDb;
+    /**
+     * Global callback registry for Firebase v8 compatibility.
+     * Structure: path -> eventType -> callback -> unsubscribe function
+     */
+    private readonly _callbackRegistry;
+    static ServerValue: {
+        TIMESTAMP: {
+            readonly '.sv': "timestamp";
+        };
+        increment: (delta: number) => {
+            '.sv': {
+                increment: number;
+            };
+        };
+    };
+    constructor();
+    /**
+     * @internal Register a callback in the global registry.
+     */
+    _registerCallback(path: string, queryId: string, eventType: EventType, callback: SnapshotCallback, context: unknown, unsubscribe: () => void): void;
+    /**
+     * @internal Unregister callbacks from the global registry.
+     *
+     * Behavior:
+     * - With callback+context: Finds and removes that specific callback+context combo from ANY query
+     * - With callback only: Removes ALL registrations of that callback (any context) from ANY query
+     * - Without callback: Removes all callbacks from the specified query only
+     *   - If queryId is 'default' (base ref), removes from ALL queries at the path
+     */
+    _unregisterCallback(path: string, queryId: string, eventType?: EventType, callback?: SnapshotCallback, context?: unknown): void;
+    /**
+     * @internal Clean up empty nested maps in the registry.
+     */
+    private _cleanupEmptyMaps;
+    get connected(): boolean;
+    get reconnecting(): boolean;
+    get state(): string;
+    get auth(): AuthInfo | null;
+    get volatilePaths(): string[];
+    get transportType(): 'websocket' | 'webtransport' | null;
+    get serverTimeOffset(): number;
+    hasPendingWrites(): boolean;
+    getPendingWriteCount(): number;
+    clearPendingWrites(): void;
+    connect(databaseId: string, options?: ConnectOptions): Promise<void>;
+    disconnect(): Promise<void>;
+    goOffline(): void;
+    goOnline(): void;
+    /**
+     * Get a Firebase v8 compatible reference to a path.
+     */
+    ref(path?: string): DatabaseReference;
+    transaction(operations: TransactionOp[] | TransactionObject): Promise<void>;
+    onConnect(callback: () => void): () => void;
+    onDisconnect(callback: () => void): () => void;
+    onError(callback: (error: Error) => void): () => void;
+    onReconnecting(callback: () => void): () => void;
+    onAuthStateChanged(callback: (auth: AuthInfo | null) => void): () => void;
+    signIn(token: string): Promise<void>;
+    signOut(): Promise<void>;
+}
+
+export { AuthInfo, ConnectOptions, DataSnapshot, DatabaseReference, EventType, LarkDatabase, OnDisconnect, SnapshotCallback, ThenableReference, TransactionObject, TransactionOp, TransactionResult };