@schematichq/schematic-js 1.2.8 → 1.2.10

package/dist/schematic.cjs.js

@@ -800,7 +800,7 @@ function contextString(context) {
 }
 
 // src/version.ts
-var version = "1.2.8";
+var version = "1.2.10";
 
 // 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;
@@ -841,6 +843,8 @@ var Schematic = class {
   eventRetryMaxDelay = 3e4;
   // Maximum retry delay in ms
   retryTimer = null;
+  flagValueDefaults = {};
+  flagCheckDefaults = {};
   constructor(apiKey, options) {
     this.apiKey = apiKey;
     this.eventQueue = [];
@@ -911,6 +915,12 @@ var Schematic = class {
     if (options?.eventRetryMaxDelay !== void 0) {
       this.eventRetryMaxDelay = options.eventRetryMaxDelay;
     }
+    if (options?.flagValueDefaults !== void 0) {
+      this.flagValueDefaults = options.flagValueDefaults;
+    }
+    if (options?.flagCheckDefaults !== void 0) {
+      this.flagCheckDefaults = options.flagCheckDefaults;
+    }
     if (typeof window !== "undefined" && window?.addEventListener) {
       window.addEventListener("beforeunload", () => {
         this.flushEventQueue();
@@ -935,6 +945,62 @@ var Schematic = class {
       this.debug("Initialized with debug mode enabled");
     }
   }
+  /**
+   * Resolve fallback value according to priority order:
+   * 1. Callsite fallback value (if provided)
+   * 2. Initialization fallback value (flagValueDefaults)
+   * 3. Default to false
+   */
+  resolveFallbackValue(key, callsiteFallback) {
+    if (callsiteFallback !== void 0) {
+      return callsiteFallback;
+    }
+    if (key in this.flagValueDefaults) {
+      return this.flagValueDefaults[key];
+    }
+    return false;
+  }
+  /**
+   * Resolve complete CheckFlagReturn object according to priority order:
+   * 1. Use callsite fallback for boolean value, construct CheckFlagReturn
+   * 2. Use flagCheckDefaults if available for this flag
+   * 3. Use flagValueDefaults if available for this flag, construct CheckFlagReturn
+   * 4. Default CheckFlagReturn with value: false
+   */
+  resolveFallbackCheckFlagReturn(key, callsiteFallback, reason = "Fallback value used", error) {
+    if (callsiteFallback !== void 0) {
+      return {
+        flag: key,
+        value: callsiteFallback,
+        reason,
+        error
+      };
+    }
+    if (key in this.flagCheckDefaults) {
+      const defaultReturn = this.flagCheckDefaults[key];
+      return {
+        ...defaultReturn,
+        flag: key,
+        // Ensure flag matches the requested key
+        reason: error !== void 0 ? reason : defaultReturn.reason,
+        error
+      };
+    }
+    if (key in this.flagValueDefaults) {
+      return {
+        flag: key,
+        value: this.flagValueDefaults[key],
+        reason,
+        error
+      };
+    }
+    return {
+      flag: key,
+      value: false,
+      reason,
+      error
+    };
+  }
   /**
    * Get value for a single flag.
    * In WebSocket mode, returns cached values if connection is active, otherwise establishes
@@ -943,16 +1009,21 @@ var Schematic = class {
    * In REST mode, makes an API call for each check.
    */
   async checkFlag(options) {
-    const { fallback = false, key } = options;
+    const { fallback, key } = options;
     const context = options.context || this.context;
     const contextStr = contextString(context);
     this.debug(`checkFlag: ${key}`, { context, fallback });
     if (this.isOffline()) {
+      const resolvedFallbackResult = this.resolveFallbackCheckFlagReturn(
+        key,
+        fallback,
+        "Offline mode - using initialization defaults"
+      );
       this.debug(`checkFlag offline result: ${key}`, {
-        value: fallback,
+        value: resolvedFallbackResult.value,
         offlineMode: true
       });
-      return fallback;
+      return resolvedFallbackResult.value;
     }
     if (!this.useWebSocket) {
       const requestUrl = `${this.apiUrl}/flags/${key}/check`;
@@ -980,14 +1051,14 @@ var Schematic = class {
         return result.value;
       }).catch((error) => {
         console.error("There was a problem with the fetch operation:", error);
-        const errorResult = {
-          flag: key,
-          value: fallback,
-          reason: "API request failed",
-          error: error instanceof Error ? error.message : String(error)
-        };
+        const errorResult = this.resolveFallbackCheckFlagReturn(
+          key,
+          fallback,
+          "API request failed",
+          error instanceof Error ? error.message : String(error)
+        );
         this.submitFlagCheckEvent(key, errorResult, context);
-        return fallback;
+        return errorResult.value;
       });
     }
     try {
@@ -997,7 +1068,7 @@ var Schematic = class {
         return existingVals[key].value;
       }
       if (this.isOffline()) {
-        return fallback;
+        return this.resolveFallbackValue(key, fallback);
       }
       try {
         await this.setContext(context);
@@ -1010,10 +1081,10 @@ var Schematic = class {
       }
       const contextVals = this.checks[contextStr] ?? {};
       const flagCheck = contextVals[key];
-      const result = flagCheck?.value ?? fallback;
+      const result = flagCheck?.value ?? this.resolveFallbackValue(key, fallback);
       this.debug(
         `checkFlag WebSocket result: ${key}`,
-        typeof flagCheck !== "undefined" ? flagCheck : { value: fallback, fallbackUsed: true }
+        typeof flagCheck !== "undefined" ? flagCheck : { value: result, fallbackUsed: true }
       );
       if (typeof flagCheck !== "undefined") {
         this.submitFlagCheckEvent(key, flagCheck, context);
@@ -1021,14 +1092,14 @@ var Schematic = class {
       return result;
     } catch (error) {
       console.error("Unexpected error in checkFlag:", error);
-      const errorResult = {
-        flag: key,
-        value: fallback,
-        reason: "Unexpected error in flag check",
-        error: error instanceof Error ? error.message : String(error)
-      };
+      const errorResult = this.resolveFallbackCheckFlagReturn(
+        key,
+        fallback,
+        "Unexpected error in flag check",
+        error instanceof Error ? error.message : String(error)
+      );
       this.submitFlagCheckEvent(key, errorResult, context);
-      return fallback;
+      return errorResult.value;
     }
   }
   /**
@@ -1040,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
    */
@@ -1071,11 +1185,12 @@ var Schematic = class {
    */
   async fallbackToRest(key, context, fallback) {
     if (this.isOffline()) {
+      const resolvedFallback = this.resolveFallbackValue(key, fallback);
       this.debug(`fallbackToRest offline result: ${key}`, {
-        value: fallback,
+        value: resolvedFallback,
         offlineMode: true
       });
-      return fallback;
+      return resolvedFallback;
     }
     try {
       const requestUrl = `${this.apiUrl}/flags/${key}/check`;
@@ -1102,14 +1217,14 @@ var Schematic = class {
       return result.value;
     } catch (error) {
       console.error("REST API call failed, using fallback value:", error);
-      const errorResult = {
-        flag: key,
-        value: fallback,
-        reason: "API request failed (fallback)",
-        error: error instanceof Error ? error.message : String(error)
-      };
+      const errorResult = this.resolveFallbackCheckFlagReturn(
+        key,
+        fallback,
+        "API request failed (fallback)",
+        error instanceof Error ? error.message : String(error)
+      );
       this.submitFlagCheckEvent(key, errorResult, context);
-      return fallback;
+      return errorResult.value;
     }
   }
   /**
@@ -1190,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`
@@ -1197,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);
@@ -1362,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 {
@@ -1430,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;
@@ -1441,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();
@@ -1479,11 +1631,17 @@ 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;
       }
     }
   };
@@ -1508,7 +1666,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);
       }
@@ -1523,7 +1683,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);
@@ -1546,7 +1708,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(
@@ -1559,23 +1724,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);
       }
@@ -1593,6 +1792,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(() => {
@@ -1611,7 +1812,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) => {
@@ -1619,7 +1820,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 = () => {
@@ -1627,121 +1828,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,
@@ -1849,7 +1977,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) => {