@schematichq/schematic-js 1.2.9 → 1.2.11

package/dist/schematic.cjs.js

@@ -800,7 +800,7 @@ function contextString(context) {
 }
 
 // src/version.ts
-var version = "1.2.9";
+var version = "1.2.11";
 
 // src/index.ts
 var anonymousIdKey = "schematicId";
@@ -832,6 +832,8 @@ var Schematic = class {
   wsReconnectAttempts = 0;
   wsReconnectTimer = null;
   wsIntentionalDisconnect = false;
+  currentWebSocket = null;
+  isConnecting = false;
   maxEventQueueSize = 100;
   // Prevent memory issues with very long network outages
   maxEventRetries = 5;
@@ -1109,6 +1111,49 @@ var Schematic = class {
       console.log(`[Schematic] ${message}`, ...args);
     }
   }
+  /**
+   * Create a persistent message handler for websocket flag updates
+   */
+  createPersistentMessageHandler(context) {
+    return (event) => {
+      const message = JSON.parse(event.data);
+      this.debug(`WebSocket persistent message received:`, message);
+      if (!(contextString(context) in this.checks)) {
+        this.checks[contextString(context)] = {};
+      }
+      (message.flags ?? []).forEach((flag) => {
+        const flagCheck = CheckFlagReturnFromJSON(flag);
+        const contextStr = contextString(context);
+        if (this.checks[contextStr] === void 0) {
+          this.checks[contextStr] = {};
+        }
+        this.checks[contextStr][flagCheck.flag] = flagCheck;
+        this.debug(`WebSocket flag update:`, {
+          flag: flagCheck.flag,
+          value: flagCheck.value,
+          flagCheck
+        });
+        if (typeof flagCheck.featureUsageEvent === "string") {
+          this.updateFeatureUsageEventMap(flagCheck);
+        }
+        if ((this.flagCheckListeners[flag.flag]?.size ?? 0) > 0 || (this.flagValueListeners[flag.flag]?.size ?? 0) > 0) {
+          this.submitFlagCheckEvent(flagCheck.flag, flagCheck, context);
+        }
+        this.debug(`About to notify listeners for flag ${flag.flag}`, {
+          flag: flag.flag,
+          value: flagCheck.value
+        });
+        this.notifyFlagCheckListeners(flag.flag, flagCheck);
+        this.notifyFlagValueListeners(flag.flag, flagCheck.value);
+        this.debug(`Finished notifying listeners for flag ${flag.flag}`, {
+          flag: flag.flag,
+          value: flagCheck.value
+        });
+      });
+      this.flushContextDependentEventQueue();
+      this.setIsPending(false);
+    };
+  }
   /**
    * Helper function to check if client is in offline mode
    */
@@ -1260,6 +1305,19 @@ var Schematic = class {
     try {
       this.setIsPending(true);
       if (!this.conn) {
+        if (this.isConnecting) {
+          this.debug(
+            `Connection already in progress, waiting for it to complete`
+          );
+          while (this.isConnecting && this.conn === null) {
+            await new Promise((resolve) => setTimeout(resolve, 10));
+          }
+          if (this.conn !== null) {
+            const socket2 = await this.conn;
+            await this.wsSendMessage(socket2, context);
+            return;
+          }
+        }
         if (this.wsReconnectTimer !== null) {
           this.debug(
             `Cancelling scheduled reconnection, connecting immediately`
@@ -1267,7 +1325,17 @@ var Schematic = class {
           clearTimeout(this.wsReconnectTimer);
           this.wsReconnectTimer = null;
         }
-        this.conn = this.wsConnect();
+        this.isConnecting = true;
+        try {
+          this.conn = this.wsConnect();
+          const socket2 = await this.conn;
+          this.isConnecting = false;
+          await this.wsSendMessage(socket2, context);
+          return;
+        } catch (error) {
+          this.isConnecting = false;
+          throw error;
+        }
       }
       const socket = await this.conn;
       await this.wsSendMessage(socket, context);
@@ -1432,10 +1500,14 @@ var Schematic = class {
       }
     }
     if (readyEvents.length === 0) {
-      this.debug(`No events ready for retry yet (${notReadyEvents.length} still in backoff)`);
+      this.debug(
+        `No events ready for retry yet (${notReadyEvents.length} still in backoff)`
+      );
       return;
     }
-    this.debug(`Flushing event queue: ${readyEvents.length} ready, ${notReadyEvents.length} waiting`);
+    this.debug(
+      `Flushing event queue: ${readyEvents.length} ready, ${notReadyEvents.length} waiting`
+    );
     this.eventQueue = notReadyEvents;
     for (const event of readyEvents) {
       try {
@@ -1500,7 +1572,10 @@ var Schematic = class {
     } catch (error) {
       const retryCount = (event.retry_count ?? 0) + 1;
       if (retryCount <= this.maxEventRetries) {
-        this.debug(`Event failed to send (attempt ${retryCount}/${this.maxEventRetries}), queueing for retry:`, error);
+        this.debug(
+          `Event failed to send (attempt ${retryCount}/${this.maxEventRetries}), queueing for retry:`,
+          error
+        );
         const baseDelay = this.eventRetryInitialDelay * Math.pow(2, retryCount - 1);
         const jitterDelay = Math.min(baseDelay, this.eventRetryMaxDelay);
         const nextRetryAt = Date.now() + jitterDelay;
@@ -1511,15 +1586,22 @@ var Schematic = class {
         };
         if (this.eventQueue.length < this.maxEventQueueSize) {
           this.eventQueue.push(retryEvent);
-          this.debug(`Event queued for retry in ${jitterDelay}ms (${this.eventQueue.length}/${this.maxEventQueueSize})`);
+          this.debug(
+            `Event queued for retry in ${jitterDelay}ms (${this.eventQueue.length}/${this.maxEventQueueSize})`
+          );
         } else {
-          this.debug(`Event queue full (${this.maxEventQueueSize}), dropping oldest event`);
+          this.debug(
+            `Event queue full (${this.maxEventQueueSize}), dropping oldest event`
+          );
           this.eventQueue.shift();
           this.eventQueue.push(retryEvent);
         }
         this.startRetryTimer();
       } else {
-        this.debug(`Event failed permanently after ${this.maxEventRetries} attempts, dropping:`, error);
+        this.debug(
+          `Event failed permanently after ${this.maxEventRetries} attempts, dropping:`,
+          error
+        );
       }
     }
     return Promise.resolve();
@@ -1549,12 +1631,95 @@ var Schematic = class {
     if (this.conn) {
       try {
         const socket = await this.conn;
+        if (this.currentWebSocket === socket) {
+          this.debug(`Cleaning up current websocket tracking`);
+          this.currentWebSocket = null;
+        }
         socket.close();
       } catch (error) {
         console.error("Error during cleanup:", error);
       } finally {
         this.conn = null;
+        this.currentWebSocket = null;
+        this.isConnecting = false;
+      }
+    }
+  };
+  /**
+   * Force an immediate WebSocket reconnection.
+   * This is useful when the application returns from a background state (e.g., mobile app
+   * coming back to foreground) and wants to immediately re-establish the connection
+   * rather than waiting for the exponential backoff timer.
+   *
+   * This method will:
+   * - Cancel any pending reconnection timer
+   * - Reset the reconnection attempt counter
+   * - Immediately attempt to reconnect
+   * - Re-send the current context to get fresh flag values
+   *
+   * If a connection is already active and healthy, this will close it and create a new one.
+   * If you just want to ensure a connection exists, check the connection state first.
+   *
+   * @example
+   * ```typescript
+   * // React Native example: reconnect when app comes to foreground
+   * useEffect(() => {
+   *   const subscription = AppState.addEventListener("change", (state) => {
+   *     if (state === "active") {
+   *       client.forceReconnect();
+   *     }
+   *   });
+   *   return () => subscription.remove();
+   * }, [client]);
+   * ```
+   */
+  forceReconnect = async () => {
+    if (this.isOffline()) {
+      this.debug("forceReconnect: skipped (offline mode)");
+      return Promise.resolve();
+    }
+    this.debug("forceReconnect: forcing immediate reconnection");
+    this.wsIntentionalDisconnect = false;
+    if (this.wsReconnectTimer !== null) {
+      this.debug("forceReconnect: cancelling pending reconnection timer");
+      clearTimeout(this.wsReconnectTimer);
+      this.wsReconnectTimer = null;
+    }
+    this.wsReconnectAttempts = 0;
+    if (this.conn !== null) {
+      this.debug("forceReconnect: closing existing connection");
+      try {
+        const existingSocket = await this.conn;
+        if (this.currentWebSocket === existingSocket) {
+          this.currentWebSocket = null;
+        }
+        if (existingSocket.readyState === WebSocket.OPEN || existingSocket.readyState === WebSocket.CONNECTING) {
+          existingSocket.close();
+        }
+      } catch (error) {
+        this.debug("forceReconnect: error closing existing connection:", error);
+      }
+      this.conn = null;
+      this.isConnecting = false;
+    }
+    if (this.context.company !== void 0 || this.context.user !== void 0) {
+      this.debug("forceReconnect: reconnecting with existing context");
+      try {
+        this.isConnecting = true;
+        this.conn = this.wsConnect();
+        const socket = await this.conn;
+        this.isConnecting = false;
+        await this.wsSendMessage(socket, this.context, true);
+        this.debug("forceReconnect: reconnection successful");
+      } catch (error) {
+        this.isConnecting = false;
+        this.debug("forceReconnect: reconnection failed:", error);
+        this.attemptReconnect();
       }
+    } else {
+      this.debug(
+        "forceReconnect: no context available, websocket will connect when context is set"
+      );
     }
   };
   /**
@@ -1578,7 +1743,9 @@ var Schematic = class {
     if (this.conn !== null) {
       try {
         const socket = await this.conn;
-        socket.close();
+        if (socket.readyState === WebSocket.OPEN || socket.readyState === WebSocket.CONNECTING) {
+          socket.close();
+        }
       } catch (error) {
         this.debug("Error closing connection on offline:", error);
       }
@@ -1593,7 +1760,9 @@ var Schematic = class {
    * Handle browser coming back online
    */
   handleNetworkOnline = () => {
-    this.debug("Network online, attempting reconnection and flushing queued events");
+    this.debug(
+      "Network online, attempting reconnection and flushing queued events"
+    );
     this.wsReconnectAttempts = 0;
     if (this.wsReconnectTimer !== null) {
       clearTimeout(this.wsReconnectTimer);
@@ -1616,7 +1785,10 @@ var Schematic = class {
       return;
     }
     if (this.wsReconnectTimer !== null) {
-      clearTimeout(this.wsReconnectTimer);
+      this.debug(
+        `Reconnection attempt already scheduled, ignoring duplicate request`
+      );
+      return;
     }
     const delay = this.calculateReconnectDelay();
     this.debug(
@@ -1629,23 +1801,57 @@ var Schematic = class {
         `Attempting to reconnect (attempt ${this.wsReconnectAttempts}/${this.webSocketMaxReconnectAttempts})`
       );
       try {
-        this.conn = this.wsConnect();
-        const socket = await this.conn;
-        this.debug(`Reconnection context check:`, {
-          hasCompany: this.context.company !== void 0,
-          hasUser: this.context.user !== void 0,
-          context: this.context
-        });
-        if (this.context.company !== void 0 || this.context.user !== void 0) {
-          this.debug(`Reconnected, force re-sending context`);
-          await this.wsSendContextAfterReconnection(socket, this.context);
-        } else {
-          this.debug(`No context to re-send after reconnection - websocket ready for new context`);
+        if (this.conn !== null) {
+          this.debug(`Cleaning up existing connection before reconnection`);
+          try {
+            const existingSocket = await this.conn;
+            if (this.currentWebSocket === existingSocket) {
+              this.debug(`Existing websocket is current, will be replaced`);
+              this.currentWebSocket = null;
+            }
+            if (existingSocket.readyState === WebSocket.OPEN || existingSocket.readyState === WebSocket.CONNECTING) {
+              existingSocket.close();
+            }
+          } catch (error) {
+            this.debug(`Error cleaning up existing connection:`, error);
+          }
+          this.conn = null;
+          this.currentWebSocket = null;
+          this.isConnecting = false;
+        }
+        this.isConnecting = true;
+        try {
+          this.conn = this.wsConnect();
+          const socket = await this.conn;
+          this.isConnecting = false;
+          this.debug(`Reconnection context check:`, {
+            hasCompany: this.context.company !== void 0,
+            hasUser: this.context.user !== void 0,
+            context: this.context
+          });
+          if (this.context.company !== void 0 || this.context.user !== void 0) {
+            this.debug(`Reconnected, force re-sending context`);
+            await this.wsSendMessage(socket, this.context, true);
+          } else {
+            this.debug(
+              `No context to re-send after reconnection - websocket ready for new context`
+            );
+            this.debug(
+              `Setting up tracking for reconnected websocket (no context to send)`
+            );
+            this.currentWebSocket = socket;
+          }
+          this.flushEventQueue().catch((error) => {
+            this.debug(
+              "Error flushing event queue after websocket reconnection:",
+              error
+            );
+          });
+          this.debug(`Reconnection successful`);
+        } catch (error) {
+          this.isConnecting = false;
+          throw error;
         }
-        this.flushEventQueue().catch((error) => {
-          this.debug("Error flushing event queue after websocket reconnection:", error);
-        });
-        this.debug(`Reconnection successful`);
       } catch (error) {
         this.debug(`Reconnection attempt failed:`, error);
       }
@@ -1663,6 +1869,8 @@ var Schematic = class {
       const wsUrl = `${this.webSocketUrl}/flags/bootstrap?apiKey=${this.apiKey}`;
       this.debug(`connecting to WebSocket:`, wsUrl);
       const webSocket = new WebSocket(wsUrl);
+      const connectionId = Math.random().toString(36).substring(7);
+      this.debug(`Creating WebSocket connection ${connectionId} to ${wsUrl}`);
       let timeoutId = null;
       let isResolved = false;
       timeoutId = setTimeout(() => {
@@ -1681,7 +1889,7 @@ var Schematic = class {
         }
         this.wsReconnectAttempts = 0;
         this.wsIntentionalDisconnect = false;
-        this.debug(`WebSocket connection opened`);
+        this.debug(`WebSocket connection ${connectionId} opened successfully`);
         resolve(webSocket);
       };
       webSocket.onerror = (error) => {
@@ -1689,7 +1897,7 @@ var Schematic = class {
         if (timeoutId !== null) {
           clearTimeout(timeoutId);
         }
-        this.debug(`WebSocket connection error:`, error);
+        this.debug(`WebSocket connection ${connectionId} error:`, error);
         reject(error);
       };
       webSocket.onclose = () => {
@@ -1697,121 +1905,48 @@ var Schematic = class {
         if (timeoutId !== null) {
           clearTimeout(timeoutId);
         }
-        this.debug(`WebSocket connection closed`);
+        this.debug(`WebSocket connection ${connectionId} closed`);
         this.conn = null;
+        if (this.currentWebSocket === webSocket) {
+          this.currentWebSocket = null;
+          this.isConnecting = false;
+        }
         if (!this.wsIntentionalDisconnect && this.webSocketReconnect) {
           this.attemptReconnect();
         }
       };
     });
   };
-  // Send a message on the websocket after reconnection, forcing the send even if context appears unchanged
-  // because the server has lost all state and needs the initial context
-  wsSendContextAfterReconnection = (socket, context) => {
-    if (this.isOffline()) {
-      this.debug("wsSendContextAfterReconnection: skipped (offline mode)");
-      this.setIsPending(false);
-      return Promise.resolve();
-    }
-    return new Promise((resolve) => {
-      this.debug(`WebSocket force sending context after reconnection:`, context);
-      this.context = context;
-      const sendMessage = () => {
-        let resolved = false;
-        const messageHandler = (event) => {
-          const message = JSON.parse(event.data);
-          this.debug(`WebSocket message received after reconnection:`, message);
-          if (!(contextString(context) in this.checks)) {
-            this.checks[contextString(context)] = {};
-          }
-          (message.flags ?? []).forEach((flag) => {
-            const flagCheck = CheckFlagReturnFromJSON(flag);
-            const contextStr = contextString(context);
-            if (this.checks[contextStr] === void 0) {
-              this.checks[contextStr] = {};
-            }
-            this.checks[contextStr][flagCheck.flag] = flagCheck;
-          });
-          this.useWebSocket = true;
-          socket.removeEventListener("message", messageHandler);
-          if (!resolved) {
-            resolved = true;
-            resolve(this.setIsPending(false));
-          }
-        };
-        socket.addEventListener("message", messageHandler);
-        const clientVersion = this.additionalHeaders["X-Schematic-Client-Version"] ?? `schematic-js@${version}`;
-        const messagePayload = {
-          apiKey: this.apiKey,
-          clientVersion,
-          data: context
-        };
-        this.debug(`WebSocket sending forced message after reconnection:`, messagePayload);
-        socket.send(JSON.stringify(messagePayload));
-      };
-      if (socket.readyState === WebSocket.OPEN) {
-        this.debug(`WebSocket already open, sending forced message after reconnection`);
-        sendMessage();
-      } else {
-        socket.addEventListener("open", () => {
-          this.debug(`WebSocket opened, sending forced message after reconnection`);
-          sendMessage();
-        });
-      }
-    });
-  };
   // Send a message on the websocket indicating interest in a particular evaluation context
   // and wait for the initial set of flag values to be returned
-  wsSendMessage = (socket, context) => {
+  wsSendMessage = (socket, context, forceContextSend = false) => {
     if (this.isOffline()) {
       this.debug("wsSendMessage: skipped (offline mode)");
       this.setIsPending(false);
       return Promise.resolve();
     }
     return new Promise((resolve, reject) => {
-      if (contextString(context) == contextString(this.context)) {
+      if (!forceContextSend && contextString(context) == contextString(this.context)) {
         this.debug(`WebSocket context unchanged, skipping update`);
         return resolve(this.setIsPending(false));
       }
-      this.debug(`WebSocket context updated:`, context);
+      this.debug(
+        forceContextSend ? `WebSocket force sending context (reconnection):` : `WebSocket context updated:`,
+        context
+      );
       this.context = context;
       const sendMessage = () => {
         let resolved = false;
+        const persistentMessageHandler = this.createPersistentMessageHandler(context);
         const messageHandler = (event) => {
-          const message = JSON.parse(event.data);
-          this.debug(`WebSocket message received:`, message);
-          if (!(contextString(context) in this.checks)) {
-            this.checks[contextString(context)] = {};
-          }
-          (message.flags ?? []).forEach((flag) => {
-            const flagCheck = CheckFlagReturnFromJSON(flag);
-            const contextStr = contextString(context);
-            if (this.checks[contextStr] === void 0) {
-              this.checks[contextStr] = {};
-            }
-            this.checks[contextStr][flagCheck.flag] = flagCheck;
-            this.debug(`WebSocket flag update:`, {
-              flag: flagCheck.flag,
-              value: flagCheck.value,
-              flagCheck
-            });
-            if (typeof flagCheck.featureUsageEvent === "string") {
-              this.updateFeatureUsageEventMap(flagCheck);
-            }
-            if (this.flagCheckListeners[flag.flag]?.size > 0 || this.flagValueListeners[flag.flag]?.size > 0) {
-              this.submitFlagCheckEvent(flagCheck.flag, flagCheck, context);
-            }
-            this.notifyFlagCheckListeners(flag.flag, flagCheck);
-            this.notifyFlagValueListeners(flag.flag, flagCheck.value);
-          });
-          this.flushContextDependentEventQueue();
-          this.setIsPending(false);
+          persistentMessageHandler(event);
           if (!resolved) {
             resolved = true;
             resolve();
           }
         };
         socket.addEventListener("message", messageHandler);
+        this.currentWebSocket = socket;
         const clientVersion = this.additionalHeaders["X-Schematic-Client-Version"] ?? `schematic-js@${version}`;
         const messagePayload = {
           apiKey: this.apiKey,
@@ -1919,7 +2054,17 @@ var Schematic = class {
         { value }
       );
     }
-    listeners.forEach((listener) => notifyFlagValueListener(listener, value));
+    listeners.forEach((listener, index) => {
+      this.debug(`Calling listener ${index} for flag ${flagKey}`, {
+        flagKey,
+        value
+      });
+      notifyFlagValueListener(listener, value);
+      this.debug(`Listener ${index} for flag ${flagKey} completed`, {
+        flagKey,
+        value
+      });
+    });
   };
 };
 var notifyPendingListener = (listener, value) => {

package/dist/schematic.d.ts

@@ -378,6 +378,8 @@ export declare class Schematic {
     private wsReconnectAttempts;
     private wsReconnectTimer;
     private wsIntentionalDisconnect;
+    private currentWebSocket;
+    private isConnecting;
     private maxEventQueueSize;
     private maxEventRetries;
     private eventRetryInitialDelay;
@@ -413,7 +415,11 @@ export declare class Schematic {
      * Helper function to log debug messages
      * Only logs if debug mode is enabled
      */
-    private debug;
+    debug(message: string, ...args: unknown[]): void;
+    /**
+     * Create a persistent message handler for websocket flag updates
+     */
+    private createPersistentMessageHandler;
     /**
      * Helper function to check if client is in offline mode
      */
@@ -481,6 +487,35 @@ export declare class Schematic {
      * In offline mode, this is a no-op.
      */
     cleanup: () => Promise<void>;
+    /**
+     * Force an immediate WebSocket reconnection.
+     * This is useful when the application returns from a background state (e.g., mobile app
+     * coming back to foreground) and wants to immediately re-establish the connection
+     * rather than waiting for the exponential backoff timer.
+     *
+     * This method will:
+     * - Cancel any pending reconnection timer
+     * - Reset the reconnection attempt counter
+     * - Immediately attempt to reconnect
+     * - Re-send the current context to get fresh flag values
+     *
+     * If a connection is already active and healthy, this will close it and create a new one.
+     * If you just want to ensure a connection exists, check the connection state first.
+     *
+     * @example
+     * ```typescript
+     * // React Native example: reconnect when app comes to foreground
+     * useEffect(() => {
+     *   const subscription = AppState.addEventListener("change", (state) => {
+     *     if (state === "active") {
+     *       client.forceReconnect();
+     *     }
+     *   });
+     *   return () => subscription.remove();
+     * }, [client]);
+     * ```
+     */
+    forceReconnect: () => Promise<void>;
     /**
      * Calculate the delay for the next reconnection attempt using exponential backoff with jitter.
      * This helps prevent dogpiling when the server recovers from an outage.
@@ -500,7 +535,6 @@ export declare class Schematic {
      */
     private attemptReconnect;
     private wsConnect;
-    private wsSendContextAfterReconnection;
     private wsSendMessage;
     /**
      * State management