@lark-sh/client 0.1.18 → 0.1.20

package/dist/{chunk-UVJBN3NR.mjs → chunk-ELNTJSEE.mjs}

@@ -1536,17 +1536,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);
         });
       }
@@ -1638,11 +1635,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) {
@@ -2070,10 +2062,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);
         }
@@ -2829,6 +2820,8 @@ function generatePushId() {
 // src/utils/validation.ts
 var MAX_KEY_BYTES = 768;
 var MAX_STRING_VALUE_BYTES = 10 * 1024 * 1024;
+var MAX_WRITE_BYTES = 16 * 1024 * 1024;
+var MAX_VOLATILE_WRITE_BYTES = 2 * 1024;
 var INVALID_KEY_CHARS = /[.#$\[\]\/]/;
 var CONTROL_CHARS = /[\x00-\x1f\x7f]/;
 function hasControlChars(str) {
@@ -2946,6 +2939,30 @@ function validateValue(value, context, path = "") {
 function validateWriteData(value, context) {
   validateValue(value, context);
 }
+function getJsonByteSize(value) {
+  const json = JSON.stringify(value);
+  return getByteLength(json);
+}
+function validateWriteSize(value, context) {
+  const byteSize = getJsonByteSize(value);
+  if (byteSize > MAX_WRITE_BYTES) {
+    const sizeMB = Math.round(byteSize / 1024 / 1024 * 100) / 100;
+    throw new LarkError(
+      ErrorCode.INVALID_DATA,
+      `${context ? `${context}: ` : ""}write exceeds 16 MB limit (got ${sizeMB} MB)`
+    );
+  }
+}
+function validateVolatileWriteSize(value, context) {
+  const byteSize = getJsonByteSize(value);
+  if (byteSize > MAX_VOLATILE_WRITE_BYTES) {
+    const sizeKB = Math.round(byteSize / 1024 * 100) / 100;
+    throw new LarkError(
+      ErrorCode.INVALID_DATA,
+      `${context ? `${context}: ` : ""}volatile write exceeds 2 KB limit (got ${sizeKB} KB)`
+    );
+  }
+}
 
 // src/DatabaseReference.ts
 function isInfoPath(path) {
@@ -4217,21 +4234,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;
@@ -4244,13 +4273,21 @@ 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;
   }
   // ============================================
   // Connection State
@@ -4335,21 +4372,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.
@@ -4359,19 +4413,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,
@@ -4424,10 +4468,6 @@ var LarkDatabase = class {
       };
       this._state = "authenticated";
       this._reconnectAttempt = 0;
-      if (this.authenticationResolve) {
-        this.authenticationResolve();
-        this.authenticationResolve = null;
-      }
       this.fireConnectionStateChange();
       if (!isReconnect) {
         this.subscriptionManager.initialize({
@@ -4449,12 +4489,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;
@@ -4522,8 +4558,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";
@@ -4531,17 +4568,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();
@@ -4642,15 +4673,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;
     }
   }
   /**
@@ -4814,9 +4844,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 = {
@@ -5010,41 +5038,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");
@@ -5059,9 +5052,10 @@ 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);
     const requestId = this.messageQueue.nextRequestId();
     const pendingWriteIds = this.subscriptionManager.getPendingWriteIdsForPath(normalizedPath);
     this.pendingWrites.trackWrite(requestId, "set", normalizedPath, value);
@@ -5084,12 +5078,13 @@ 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}`;
       validateWriteData(value, fullPath);
     }
+    validateWriteSize(values, normalizedPath);
     const requestId = this.messageQueue.nextRequestId();
     const pendingWriteIds = this.subscriptionManager.getPendingWriteIdsForPath(normalizedPath);
     this.pendingWrites.trackWrite(requestId, "update", normalizedPath, values);
@@ -5116,7 +5111,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);
@@ -5151,6 +5146,7 @@ var LarkDatabase = class {
    */
   _sendVolatileSet(path, value) {
     const normalizedPath = normalizePath(path) || "/";
+    validateVolatileWriteSize(value, normalizedPath);
     this.subscriptionManager.applyOptimisticWrite(normalizedPath, value, "", "set");
     if (this._state !== "authenticated" || !this.transport || !this.transport.connected) {
       return;
@@ -5167,6 +5163,7 @@ var LarkDatabase = class {
    */
   _sendVolatileUpdate(path, values) {
     const normalizedPath = normalizePath(path) || "/";
+    validateVolatileWriteSize(values, normalizedPath);
     this.subscriptionManager.applyOptimisticWrite(normalizedPath, values, "", "update");
     if (this._state !== "authenticated" || !this.transport || !this.transport.connected) {
       return;
@@ -5223,7 +5220,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",
@@ -5240,7 +5237,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",
@@ -5266,13 +5263,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 } : {}
@@ -5285,7 +5281,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",
@@ -5350,4 +5346,4 @@ export {
   ServerValue,
   LarkDatabase
 };
-//# sourceMappingURL=chunk-UVJBN3NR.mjs.map
+//# sourceMappingURL=chunk-ELNTJSEE.mjs.map