@lark-sh/client 0.1.19 → 0.1.21

package/dist/index.js

@@ -1581,17 +1581,14 @@ var SubscriptionManager = class {
       queryParamsChanged = view.updateQueryParams(queryParams);
       tag = this.viewKeyToTag.get(viewKey);
     }
-    const existingEventTypes = view.getEventTypes();
-    const isNewEventType = !existingEventTypes.includes(eventType);
     const unsubscribe = view.addCallback(eventType, callback);
     const wrappedUnsubscribe = () => {
       this.unsubscribeCallback(normalizedPath, eventType, callback, queryId);
     };
-    if (isNewView || isNewEventType || queryParamsChanged) {
+    if (isNewView || queryParamsChanged) {
       const hasAncestorComplete = this.hasAncestorCompleteView(normalizedPath);
       if (!hasAncestorComplete) {
-        const allEventTypes = view.getEventTypes();
-        this.sendSubscribe?.(normalizedPath, allEventTypes, view.queryParams ?? void 0, tag).catch((err) => {
+        this.sendSubscribe?.(normalizedPath, view.queryParams ?? void 0, tag).catch((err) => {
           console.error("Failed to subscribe:", err);
         });
       }
@@ -1683,11 +1680,6 @@ var SubscriptionManager = class {
         this.sendUnsubscribe?.(normalizedPath, queryParams).catch((err) => {
           console.error("Failed to unsubscribe:", err);
         });
-      } else {
-        const remainingEventTypes = view.getEventTypes();
-        this.sendSubscribe?.(normalizedPath, remainingEventTypes, queryParams).catch((err) => {
-          console.error("Failed to update subscription:", err);
-        });
       }
     }
     if (queryIds.size === 0) {
@@ -2115,10 +2107,9 @@ var SubscriptionManager = class {
    */
   async resubscribeAll() {
     for (const view of this.views.values()) {
-      const eventTypes = view.getEventTypes();
-      if (eventTypes.length > 0) {
+      if (view.hasCallbacks()) {
         try {
-          await this.sendSubscribe?.(view.path, eventTypes, view.queryParams ?? void 0);
+          await this.sendSubscribe?.(view.path, view.queryParams ?? void 0);
         } catch (err) {
           console.error(`Failed to resubscribe to ${view.path}:`, err);
         }
@@ -4288,21 +4279,33 @@ var ServerValue = {
   increment: (delta) => ({ ".sv": { increment: delta } })
 };
 var LarkDatabase = class {
-  constructor() {
+  /**
+   * Create a new LarkDatabase instance.
+   *
+   * @param databaseId - Database ID in format "project/database"
+   * @param options - Connection options (token, anonymous, domain, transport).
+   *                  Defaults to anonymous auth if not specified.
+   *
+   * @example
+   * ```typescript
+   * // Lazy connection - connects on first operation
+   * const db = new LarkDatabase('project/database', { anonymous: true });
+   * db.ref('/users').on('value', cb); // Auto-connects here
+   *
+   * // Explicit connection - for UI feedback or error handling
+   * const db = new LarkDatabase('project/database', { anonymous: true });
+   * await db.connect(); // Explicitly await connection
+   * db.ref('/users').on('value', cb);
+   * ```
+   */
+  constructor(databaseId, options = {}) {
     this._state = "disconnected";
     this._auth = null;
-    this._databaseId = null;
-    this._domain = null;
     this._volatilePaths = [];
     this._transportType = null;
-    // Auth state
-    this._currentToken = null;
-    // Token for auth (empty string = anonymous)
-    this._isAnonymous = false;
     // True if connected anonymously
     // Reconnection state
     this._connectionId = null;
-    this._connectOptions = null;
     this._intentionalDisconnect = false;
     this._reconnectAttempt = 0;
     this._reconnectTimer = null;
@@ -4315,13 +4318,26 @@ var LarkDatabase = class {
     this.authStateChangedCallbacks = /* @__PURE__ */ new Set();
     // .info path subscriptions (handled locally, not sent to server)
     this.infoSubscriptions = [];
-    // Authentication promise - resolves when auth completes, allows operations to queue
-    this.authenticationPromise = null;
-    this.authenticationResolve = null;
+    // Connection promise - shared by connect() and lazy operations
+    this._connectionPromise = null;
     this._serverTimeOffset = 0;
     this.messageQueue = new MessageQueue();
     this.subscriptionManager = new SubscriptionManager();
     this.pendingWrites = new PendingWriteManager();
+    const projectId = databaseId.split("/")[0];
+    if (!projectId) {
+      throw new Error('Invalid database ID: must be in format "projectId/databaseName"');
+    }
+    this._databaseId = databaseId;
+    this._connectOptions = options;
+    this._domain = options.domain || DEFAULT_LARK_DOMAIN;
+    this._currentToken = options.token || "";
+    this._isAnonymous = !options.token && options.anonymous !== false;
+    this.subscriptionManager.initialize({
+      sendSubscribe: this.sendSubscribeMessage.bind(this),
+      sendUnsubscribe: this.sendUnsubscribeMessage.bind(this),
+      createSnapshot: this.createSnapshot.bind(this)
+    });
   }
   // ============================================
   // Connection State
@@ -4406,21 +4422,38 @@ var LarkDatabase = class {
   // Connection Management
   // ============================================
   /**
-   * Connect to a database.
+   * Explicitly connect to the database.
    *
-   * @param databaseId - Database ID in format "project/database"
-   * @param options - Connection options (token, anonymous, domain)
+   * This is optional - operations will auto-connect if needed.
+   * Use this when you want to:
+   * - Await connection completion for UI feedback
+   * - Handle connection errors separately from operation errors
+   * - Pre-warm the connection before first operation
+   *
+   * @returns Promise that resolves when fully authenticated
    */
-  async connect(databaseId, options = {}) {
-    if (this._state !== "disconnected") {
-      throw new Error("Already connected or connecting");
+  async connect() {
+    return this.ensureConnected();
+  }
+  /**
+   * Ensure connection is established, triggering it if needed.
+   * Multiple concurrent calls share the same connection promise.
+   */
+  async ensureConnected() {
+    if (this._state === "authenticated") {
+      return;
+    }
+    if (this._connectionPromise) {
+      return this._connectionPromise;
     }
-    this._connectOptions = options;
     this._intentionalDisconnect = false;
-    this.authenticationPromise = new Promise((resolve) => {
-      this.authenticationResolve = resolve;
-    });
-    await this.performConnect(databaseId, options);
+    this._connectionPromise = this.performConnect(this._databaseId, this._connectOptions);
+    try {
+      await this._connectionPromise;
+    } catch (error) {
+      this._connectionPromise = null;
+      throw error;
+    }
   }
   /**
    * Internal connect implementation used by both initial connect and reconnect.
@@ -4430,19 +4463,9 @@ var LarkDatabase = class {
    * 3. Send auth (authenticates user - required even for anonymous)
    */
   async performConnect(databaseId, options, isReconnect = false) {
-    const previousState = this._state;
     this._state = isReconnect ? "reconnecting" : "connecting";
-    this._databaseId = databaseId;
-    this._domain = options.domain || DEFAULT_LARK_DOMAIN;
-    if (!isReconnect) {
-      this._currentToken = options.token || "";
-      this._isAnonymous = !options.token && options.anonymous !== false;
-    }
     try {
       const projectId = databaseId.split("/")[0];
-      if (!projectId) {
-        throw new Error('Invalid database ID: must be in format "projectId/databaseName"');
-      }
       const wsUrl = `wss://${projectId}.${this._domain}/ws`;
       const transportResult = await createTransport(
         wsUrl,
@@ -4495,18 +4518,7 @@ var LarkDatabase = class {
       };
       this._state = "authenticated";
       this._reconnectAttempt = 0;
-      if (this.authenticationResolve) {
-        this.authenticationResolve();
-        this.authenticationResolve = null;
-      }
       this.fireConnectionStateChange();
-      if (!isReconnect) {
-        this.subscriptionManager.initialize({
-          sendSubscribe: this.sendSubscribeMessage.bind(this),
-          sendUnsubscribe: this.sendUnsubscribeMessage.bind(this),
-          createSnapshot: this.createSnapshot.bind(this)
-        });
-      }
       if (isReconnect) {
         await this.restoreAfterReconnect();
       }
@@ -4520,12 +4532,8 @@ var LarkDatabase = class {
       }
       this._state = "disconnected";
       this._auth = null;
-      this._databaseId = null;
-      this._connectOptions = null;
       this._connectionId = null;
       this._transportType = null;
-      this._currentToken = null;
-      this._isAnonymous = false;
       this.transport?.close();
       this.transport = null;
       throw error;
@@ -4593,8 +4601,9 @@ var LarkDatabase = class {
     }
   }
   /**
-   * Full cleanup - clears all state including subscriptions.
+   * Full cleanup - clears connection state including subscriptions.
    * Used for intentional disconnect.
+   * Preserves config (databaseId, domain, token) so connect() can be called again.
    */
   cleanupFull() {
     const wasAuthenticated = this._state === "authenticated";
@@ -4602,17 +4611,11 @@ var LarkDatabase = class {
     this.transport = null;
     this._state = "disconnected";
     this._auth = null;
-    this._databaseId = null;
     this._volatilePaths = [];
-    this._domain = null;
     this._connectionId = null;
-    this._connectOptions = null;
     this._transportType = null;
-    this._currentToken = null;
-    this._isAnonymous = false;
     this._reconnectAttempt = 0;
-    this.authenticationPromise = null;
-    this.authenticationResolve = null;
+    this._connectionPromise = null;
     this.subscriptionManager.clear();
     this.messageQueue.rejectAll(new Error("Connection closed"));
     this.pendingWrites.clear();
@@ -4713,15 +4716,14 @@ var LarkDatabase = class {
    * Attempt to reconnect to the database.
    */
   async attemptReconnect() {
-    if (this._intentionalDisconnect || !this._databaseId || !this._connectOptions) {
+    if (this._intentionalDisconnect) {
       return;
     }
-    this.authenticationPromise = new Promise((resolve) => {
-      this.authenticationResolve = resolve;
-    });
+    this._connectionPromise = this.performConnect(this._databaseId, this._connectOptions, true);
     try {
-      await this.performConnect(this._databaseId, this._connectOptions, true);
+      await this._connectionPromise;
     } catch {
+      this._connectionPromise = null;
     }
   }
   /**
@@ -4885,9 +4887,7 @@ var LarkDatabase = class {
    * @internal Send a transaction to the server.
    */
   async _sendTransaction(ops) {
-    if (!this.isAuthenticatedOrThrow()) {
-      if (!this.isAuthenticatedOrThrow()) await this.waitForAuthenticated();
-    }
+    if (this._state !== "authenticated") await this.ensureConnected();
     const requestId = this.messageQueue.nextRequestId();
     this.pendingWrites.trackWrite(requestId, "transaction", "/", ops);
     const message = {
@@ -5081,41 +5081,6 @@ var LarkDatabase = class {
   // ============================================
   // Internal: Sending Messages
   // ============================================
-  /**
-   * Check if authenticated synchronously.
-   * Returns true if authenticated, false if connecting (should wait), throws if disconnected.
-   */
-  isAuthenticatedOrThrow() {
-    if (this._state === "authenticated") {
-      return true;
-    }
-    if (this._state === "connecting" || this._state === "connected" || this._state === "joined" || this._state === "reconnecting") {
-      return false;
-    }
-    throw new LarkError("not_connected", "Not connected - call connect() first");
-  }
-  /**
-   * Wait for authentication to complete before performing an operation.
-   * If already authenticated, returns immediately (synchronously).
-   * If connecting/reconnecting, waits for auth to complete.
-   * If disconnected and no connect in progress, throws.
-   *
-   * IMPORTANT: This returns a Promise only if waiting is needed.
-   * Callers should use: `if (!this.isAuthenticatedOrThrow()) if (!this.isAuthenticatedOrThrow()) await this.waitForAuthenticated();`
-   * to preserve synchronous execution when already authenticated.
-   */
-  async waitForAuthenticated() {
-    if (this._state === "authenticated") {
-      return;
-    }
-    if (this._state === "connecting" || this._state === "connected" || this._state === "joined" || this._state === "reconnecting") {
-      if (this.authenticationPromise) {
-        await this.authenticationPromise;
-        return;
-      }
-    }
-    throw new LarkError("not_connected", "Not connected - call connect() first");
-  }
   send(message) {
     if (!this.transport || !this.transport.connected) {
       throw new LarkError("not_connected", "Not connected to database");
@@ -5130,7 +5095,7 @@ var LarkDatabase = class {
    * Note: Priority is now part of the value (as .priority), not a separate field.
    */
   async _sendSet(path, value) {
-    if (!this.isAuthenticatedOrThrow()) await this.waitForAuthenticated();
+    if (this._state !== "authenticated") await this.ensureConnected();
     const normalizedPath = normalizePath(path) || "/";
     validateWriteData(value, normalizedPath);
     validateWriteSize(value, normalizedPath);
@@ -5156,7 +5121,7 @@ var LarkDatabase = class {
    * @internal Send an update operation.
    */
   async _sendUpdate(path, values) {
-    if (!this.isAuthenticatedOrThrow()) await this.waitForAuthenticated();
+    if (this._state !== "authenticated") await this.ensureConnected();
     const normalizedPath = normalizePath(path) || "/";
     for (const [key, value] of Object.entries(values)) {
       const fullPath = key.startsWith("/") ? key : `${normalizedPath}/${key}`;
@@ -5189,7 +5154,7 @@ var LarkDatabase = class {
    * @internal Send a delete operation.
    */
   async _sendDelete(path) {
-    if (!this.isAuthenticatedOrThrow()) await this.waitForAuthenticated();
+    if (this._state !== "authenticated") await this.ensureConnected();
     const normalizedPath = normalizePath(path) || "/";
     const requestId = this.messageQueue.nextRequestId();
     const pendingWriteIds = this.subscriptionManager.getPendingWriteIdsForPath(normalizedPath);
@@ -5298,7 +5263,7 @@ var LarkDatabase = class {
         return new DataSnapshot(cached.value, path, this);
       }
     }
-    if (!this.isAuthenticatedOrThrow()) await this.waitForAuthenticated();
+    if (this._state !== "authenticated") await this.ensureConnected();
     const requestId = this.messageQueue.nextRequestId();
     const message = {
       o: "o",
@@ -5315,7 +5280,7 @@ var LarkDatabase = class {
    * @internal Send an onDisconnect operation.
    */
   async _sendOnDisconnect(path, action, value) {
-    if (!this.isAuthenticatedOrThrow()) await this.waitForAuthenticated();
+    if (this._state !== "authenticated") await this.ensureConnected();
     const requestId = this.messageQueue.nextRequestId();
     const message = {
       o: "od",
@@ -5341,13 +5306,12 @@ var LarkDatabase = class {
    * @internal Send a subscribe message to server.
    * Includes tag for non-default queries to enable proper event routing.
    */
-  async sendSubscribeMessage(path, eventTypes, queryParams, tag) {
-    if (!this.isAuthenticatedOrThrow()) await this.waitForAuthenticated();
+  async sendSubscribeMessage(path, queryParams, tag) {
+    if (this._state !== "authenticated") await this.ensureConnected();
     const requestId = this.messageQueue.nextRequestId();
     const message = {
       o: "sb",
       p: normalizePath(path) || "/",
-      e: eventTypes,
       r: requestId,
       ...queryParams,
       ...tag !== void 0 ? { tag } : {}
@@ -5360,7 +5324,7 @@ var LarkDatabase = class {
    * Includes query params and tag so server can identify which specific subscription to remove.
    */
   async sendUnsubscribeMessage(path, queryParams, tag) {
-    if (!this.isAuthenticatedOrThrow()) await this.waitForAuthenticated();
+    if (this._state !== "authenticated") await this.ensureConnected();
     const requestId = this.messageQueue.nextRequestId();
     const message = {
       o: "us",