@lark-sh/client 0.1.0

package/README.md

@@ -0,0 +1,52 @@
+# @lark-sh/client
+
+JavaScript/TypeScript client for [Lark](https://lark.sh) - a real-time database with a Firebase-like API.
+
+> **Early Alpha**: This library is under active development. APIs may change.
+
+## Installation
+
+```bash
+npm install @lark-sh/client
+```
+
+## Quick Start
+
+```typescript
+import { LarkDatabase } from '@lark-sh/client';
+
+const db = new LarkDatabase();
+
+// Connect to a database
+await db.connect('my-project/my-database', {
+  token: 'your-auth-token', // or use anonymous: true
+});
+
+// Get a reference and read data
+const snapshot = await db.ref('users/alice').once();
+console.log(snapshot.val());
+
+// Write data
+await db.ref('users/alice').set({ name: 'Alice', score: 100 });
+
+// Subscribe to real-time updates
+const unsubscribe = db.ref('users').on('value', (snapshot) => {
+  console.log('Users changed:', snapshot.val());
+});
+
+// Later: unsubscribe and disconnect
+unsubscribe();
+await db.disconnect();
+```
+
+## Features
+
+- Firebase v8-style API (`ref()`, `set()`, `on()`, `once()`, etc.)
+- Real-time subscriptions with `on()` / `off()`
+- Works in browsers and Node.js
+- TypeScript support
+- `onDisconnect()` handlers for presence
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,415 @@
+/**
+ * OnDisconnect - registers operations to perform on the server when this client disconnects.
+ */
+
+declare class OnDisconnect {
+    private readonly _db;
+    private readonly _path;
+    constructor(db: LarkDatabase, path: string);
+    /**
+     * Set a value when disconnected.
+     */
+    set(value: unknown): Promise<void>;
+    /**
+     * Update values when disconnected.
+     */
+    update(values: Record<string, unknown>): Promise<void>;
+    /**
+     * Remove data when disconnected.
+     */
+    remove(): Promise<void>;
+    /**
+     * Cancel any pending onDisconnect handlers at this location.
+     */
+    cancel(): Promise<void>;
+    /**
+     * Set a value with priority when disconnected.
+     */
+    setWithPriority(value: unknown, priority: number | string): Promise<void>;
+}
+
+type EventType = 'value' | 'child_added' | 'child_changed' | 'child_removed';
+
+/**
+ * DatabaseReference - a reference to a specific path in the database.
+ * Immutable - navigation returns new references.
+ */
+
+type SnapshotCallback$1 = (snapshot: DataSnapshot, previousChildKey?: string | null) => void;
+interface QueryState {
+    orderBy?: 'key' | 'priority' | 'child' | 'value';
+    orderByChildPath?: string;
+    limitToFirst?: number;
+    limitToLast?: number;
+    startAt?: {
+        value: unknown;
+        key?: string;
+    };
+    endAt?: {
+        value: unknown;
+        key?: string;
+    };
+    equalTo?: {
+        value: unknown;
+        key?: string;
+    };
+}
+declare class DatabaseReference {
+    private readonly _db;
+    private readonly _path;
+    private readonly _query;
+    constructor(db: LarkDatabase, path: string, query?: QueryState);
+    /**
+     * The path of this reference.
+     */
+    get path(): string;
+    /**
+     * The last segment of the path (the "key"), or null for root.
+     */
+    get key(): string | null;
+    /**
+     * Get a reference to the parent node, or null if this is root.
+     */
+    get parent(): DatabaseReference | null;
+    /**
+     * Get a reference to the root of the database.
+     */
+    get root(): DatabaseReference;
+    /**
+     * Get a reference to a child path.
+     */
+    child(path: string): DatabaseReference;
+    /**
+     * Set the data at this location, overwriting any existing data.
+     */
+    set(value: unknown): Promise<void>;
+    /**
+     * Update specific children at this location without overwriting other children.
+     */
+    update(values: Record<string, unknown>): Promise<void>;
+    /**
+     * Remove the data at this location.
+     */
+    remove(): Promise<void>;
+    /**
+     * 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.
+     *
+     * If no value is provided, returns a reference immediately with a client-generated
+     * push key (you can then call set() on it).
+     */
+    push(value?: unknown): DatabaseReference | Promise<DatabaseReference>;
+    /**
+     * Set the data with a priority value for ordering.
+     */
+    setWithPriority(value: unknown, priority: number | string): Promise<void>;
+    /**
+     * Set the priority of the data at this location.
+     */
+    setPriority(priority: number | string): Promise<void>;
+    /**
+     * Read the data at this location once.
+     */
+    once(eventType?: 'value'): Promise<DataSnapshot>;
+    /**
+     * Subscribe to events at this location.
+     * Returns an unsubscribe function.
+     */
+    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(eventType?: EventType): void;
+    /**
+     * Get an OnDisconnect handler for this location.
+     */
+    onDisconnect(): OnDisconnect;
+    /**
+     * Order results by key.
+     */
+    orderByKey(): DatabaseReference;
+    /**
+     * Order results by priority.
+     */
+    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;
+    /**
+     * Limit to the first N results.
+     */
+    limitToFirst(limit: number): DatabaseReference;
+    /**
+     * Limit to the last N results.
+     */
+    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;
+    /**
+     * Build query parameters for wire protocol.
+     */
+    private _buildQueryParams;
+    /**
+     * Returns the absolute URL for this database location.
+     * Format: https://db.lark.sh/project/database/path/to/data
+     */
+    toString(): string;
+}
+
+/**
+ * DataSnapshot - an immutable snapshot of data at a location.
+ * Received in event callbacks and from once() operations.
+ */
+
+declare class DataSnapshot {
+    private readonly _data;
+    private readonly _path;
+    private readonly _db;
+    private readonly _volatile;
+    private readonly _priority;
+    constructor(data: unknown, path: string, db: LarkDatabase, options?: {
+        volatile?: boolean;
+        priority?: number | string | null;
+    });
+    /**
+     * Get a DatabaseReference for the location of this snapshot.
+     */
+    get ref(): DatabaseReference;
+    /**
+     * Get the last segment of the path (the "key"), or null for root.
+     */
+    get key(): string | null;
+    /**
+     * Get the raw data value.
+     */
+    val(): unknown;
+    /**
+     * Check if data exists at this location (is not null/undefined).
+     */
+    exists(): boolean;
+    /**
+     * Get a child snapshot at the specified path.
+     */
+    child(path: string): DataSnapshot;
+    /**
+     * Check if this snapshot has any children.
+     */
+    hasChildren(): boolean;
+    /**
+     * Check if this snapshot has a specific child.
+     */
+    hasChild(path: string): boolean;
+    /**
+     * Get the number of children.
+     */
+    numChildren(): number;
+    /**
+     * Iterate over children. Return true from callback to stop iteration.
+     */
+    forEach(callback: (child: DataSnapshot) => boolean | void): void;
+    /**
+     * Get the priority of the data at this location.
+     */
+    getPriority(): number | string | null;
+    /**
+     * Check if this snapshot was from a volatile (high-frequency) update.
+     * This is a Lark extension not present in Firebase.
+     */
+    isVolatile(): boolean;
+    /**
+     * Export the snapshot data as JSON (alias for val()).
+     */
+    toJSON(): unknown;
+}
+
+interface QueryParams {
+    ob?: 'k' | 'p';
+    lf?: number;
+    ll?: number;
+}
+
+/**
+ * SubscriptionManager - tracks active subscriptions and routes events to callbacks.
+ */
+
+type SnapshotCallback = (snapshot: DataSnapshot, previousChildKey?: string | null) => void;
+
+/**
+ * LarkDatabase - the main entry point for connecting to a Lark database.
+ */
+
+interface ConnectOptions {
+    /** User's auth token (from your auth system) */
+    token?: string;
+    /** Connect anonymously (server assigns a UID) */
+    anonymous?: boolean;
+    /** Coordinator URL (default: https://db.lark.dev) */
+    coordinator?: string;
+}
+interface AuthInfo {
+    uid: string;
+    provider: string;
+    token: Record<string, unknown>;
+}
+declare class LarkDatabase {
+    private _state;
+    private _auth;
+    private _databaseId;
+    private _coordinatorUrl;
+    private ws;
+    private messageQueue;
+    private subscriptionManager;
+    private connectCallbacks;
+    private disconnectCallbacks;
+    private errorCallbacks;
+    constructor();
+    /**
+     * Whether the database is currently connected.
+     */
+    get connected(): boolean;
+    /**
+     * Current auth info, or null if not connected.
+     */
+    get auth(): AuthInfo | null;
+    /**
+     * @internal Get the base URL for reference toString().
+     */
+    _getBaseUrl(): string;
+    /**
+     * Connect to a database.
+     *
+     * @param databaseId - Database ID in format "project/database"
+     * @param options - Connection options (token, anonymous, coordinator URL)
+     */
+    connect(databaseId: string, options?: ConnectOptions): Promise<void>;
+    /**
+     * Disconnect from the database.
+     * This triggers onDisconnect hooks on the server.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Clean up connection state.
+     */
+    private cleanup;
+    /**
+     * Get a reference to a path in the database.
+     */
+    ref(path?: string): DatabaseReference;
+    /**
+     * Register a callback for when connection is established.
+     * Returns an unsubscribe function.
+     */
+    onConnect(callback: () => void): () => void;
+    /**
+     * Register a callback for when connection is lost.
+     * Returns an unsubscribe function.
+     */
+    onDisconnect(callback: () => void): () => void;
+    /**
+     * Register a callback for connection errors.
+     * Returns an unsubscribe function.
+     */
+    onError(callback: (error: Error) => void): () => void;
+    private handleMessage;
+    private handleClose;
+    private handleError;
+    private send;
+    /**
+     * @internal Send a set operation.
+     */
+    _sendSet(path: string, value: unknown, priority?: number | string): Promise<void>;
+    /**
+     * @internal Send an update operation.
+     */
+    _sendUpdate(path: string, values: Record<string, unknown>): Promise<void>;
+    /**
+     * @internal Send a delete operation.
+     */
+    _sendDelete(path: string): Promise<void>;
+    /**
+     * @internal Send a push operation. Returns the generated key.
+     */
+    _sendPush(path: string, value: unknown): Promise<string>;
+    /**
+     * @internal Send a once (read) operation.
+     */
+    _sendOnce(path: string, query?: QueryParams): Promise<DataSnapshot>;
+    /**
+     * @internal Send an onDisconnect operation.
+     */
+    _sendOnDisconnect(path: string, action: string, value?: unknown, priority?: number | string): Promise<void>;
+    /**
+     * @internal Send a subscribe message to server.
+     */
+    private sendSubscribeMessage;
+    /**
+     * @internal Send an unsubscribe message to server.
+     */
+    private sendUnsubscribeMessage;
+    /**
+     * @internal Create a DataSnapshot from event data.
+     */
+    private createSnapshot;
+    /**
+     * @internal Subscribe to events at a path.
+     */
+    _subscribe(path: string, eventType: EventType, callback: SnapshotCallback): () => void;
+    /**
+     * @internal Unsubscribe from a specific event type at a path.
+     */
+    _unsubscribeEventType(path: string, eventType: EventType): void;
+    /**
+     * @internal Unsubscribe from all events at a path.
+     */
+    _unsubscribeAll(path: string): void;
+}
+
+/**
+ * LarkError - custom error class for Lark operations.
+ */
+declare class LarkError extends Error {
+    readonly code: string;
+    constructor(code: string, message?: string);
+}
+
+/**
+ * Push ID generation - Firebase-compatible chronologically-sortable IDs.
+ *
+ * Format: 20 characters
+ * - First 8 chars: timestamp (milliseconds since epoch, base64-encoded)
+ * - Last 12 chars: random suffix (incremented on same-millisecond calls)
+ *
+ * This ensures:
+ * - IDs created later sort after IDs created earlier
+ * - IDs created in the same millisecond are unique and still sort correctly
+ */
+/**
+ * Generate a Firebase-compatible push ID.
+ */
+declare function generatePushId(): string;
+
+export { type AuthInfo, type ConnectOptions, DataSnapshot, DatabaseReference, type EventType, LarkDatabase, LarkError, OnDisconnect, type QueryState, type SnapshotCallback$1 as SnapshotCallback, generatePushId };