@schematichq/schematic-react 1.2.8 → 1.2.9

package/dist/schematic-react.cjs.js

@@ -799,7 +799,7 @@ function contextString(context) {
   }, {});
   return JSON.stringify(sortedContext);
 }
-var version = "1.2.8";
+var version = "1.2.9";
 var anonymousIdKey = "schematicId";
 var Schematic = class {
   additionalHeaders = {};
@@ -838,6 +838,8 @@ var Schematic = class {
   eventRetryMaxDelay = 3e4;
   // Maximum retry delay in ms
   retryTimer = null;
+  flagValueDefaults = {};
+  flagCheckDefaults = {};
   constructor(apiKey, options) {
     this.apiKey = apiKey;
     this.eventQueue = [];
@@ -908,6 +910,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();
@@ -932,6 +940,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
@@ -940,16 +1004,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`;
@@ -977,14 +1046,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 {
@@ -994,7 +1063,7 @@ var Schematic = class {
         return existingVals[key].value;
       }
       if (this.isOffline()) {
-        return fallback;
+        return this.resolveFallbackValue(key, fallback);
       }
       try {
         await this.setContext(context);
@@ -1007,10 +1076,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);
@@ -1018,14 +1087,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;
     }
   }
   /**
@@ -1068,11 +1137,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`;
@@ -1099,14 +1169,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;
     }
   }
   /**
@@ -1875,7 +1945,7 @@ var notifyFlagValueListener = (listener, value) => {
 var import_react = __toESM(require("react"));
 
 // src/version.ts
-var version2 = "1.2.8";
+var version2 = "1.2.9";
 
 // src/context/schematic.tsx
 var import_jsx_runtime = require("react/jsx-runtime");

package/dist/schematic-react.esm.js

@@ -754,7 +754,7 @@ function contextString(context) {
   }, {});
   return JSON.stringify(sortedContext);
 }
-var version = "1.2.8";
+var version = "1.2.9";
 var anonymousIdKey = "schematicId";
 var Schematic = class {
   additionalHeaders = {};
@@ -793,6 +793,8 @@ var Schematic = class {
   eventRetryMaxDelay = 3e4;
   // Maximum retry delay in ms
   retryTimer = null;
+  flagValueDefaults = {};
+  flagCheckDefaults = {};
   constructor(apiKey, options) {
     this.apiKey = apiKey;
     this.eventQueue = [];
@@ -863,6 +865,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();
@@ -887,6 +895,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
@@ -895,16 +959,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`;
@@ -932,14 +1001,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 {
@@ -949,7 +1018,7 @@ var Schematic = class {
         return existingVals[key].value;
       }
       if (this.isOffline()) {
-        return fallback;
+        return this.resolveFallbackValue(key, fallback);
       }
       try {
         await this.setContext(context);
@@ -962,10 +1031,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);
@@ -973,14 +1042,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;
     }
   }
   /**
@@ -1023,11 +1092,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`;
@@ -1054,14 +1124,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;
     }
   }
   /**
@@ -1830,7 +1900,7 @@ var notifyFlagValueListener = (listener, value) => {
 import React, { createContext, useEffect, useMemo, useRef } from "react";
 
 // src/version.ts
-var version2 = "1.2.8";
+var version2 = "1.2.9";
 
 // src/context/schematic.tsx
 import { jsx } from "react/jsx-runtime";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@schematichq/schematic-react",
-  "version": "1.2.8",
+  "version": "1.2.9",
   "main": "dist/schematic-react.cjs.js",
   "module": "dist/schematic-react.esm.js",
   "types": "dist/schematic-react.d.ts",
@@ -31,7 +31,7 @@
     "prepare": "husky"
   },
   "dependencies": {
-    "@schematichq/schematic-js": "^1.2.8"
+    "@schematichq/schematic-js": "^1.2.9"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.1",