@zudojs/feature-flags 1.2.0 → 1.3.0

package/README.md

@@ -171,6 +171,11 @@ remembers a key the provider does not know for `missingFlagTtlMs` (default
 turn every evaluation into a remote round trip. The memory is dropped on
 every reload.
 
+A provider that fails is left alone for `providerCooloffMs` (default 5 s;
+`0` disables it) before it is probed again, so an outage costs one pair of
+calls per window instead of two per evaluation. The first successful call
+closes the window, and `refresh()` always probes.
+
 `createEnvironmentProvider` parses `true`/`false` and numbers; anything else,
 including an empty `FEATURE_X=`, stays a string.
 
@@ -200,6 +205,12 @@ not throw `FeatureFlagNotFoundError` under `throwOnMissing`.
 An unreachable store never enables a flag. Set `throwOnProviderError: true`
 to own the failure yourself instead.
 
+`snapshot()` and `getAll()` reject with `FeatureFlagProviderError` when the
+flags were never loaded: an empty `Map` cannot be told apart from "no flags
+are configured", and shipping one to a browser turns an outage into every
+flag being off. Once a load has succeeded they keep serving that data, even
+if a later reload fails.
+
 ```typescript
 const flags = createFeatureFlags({
   provider,

package/dist/featureFlags/featureFlags.cooloff.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Cool-off window for a provider that is failing.
+ *
+ * @module featureFlags/featureFlags.cooloff
+ */
+/** Default cool-off after a provider failure, in ms. */
+export declare const DEFAULT_PROVIDER_COOLOFF_MS = 5000;
+/** Tracks whether a failing provider should be probed again yet. */
+export interface ProviderCooloff {
+    /** Whether the provider is inside its cool-off window and must not be called. */
+    active(): boolean;
+    /** Records a failed provider call, opening a new window. */
+    recordFailure(): void;
+    /** Records a successful provider call, closing any open window. */
+    recordSuccess(): void;
+}
+/**
+ * Create a cool-off gate.
+ *
+ * Without one, every evaluation against an unreachable store re-ran
+ * `getAll()` and `get(key)` — two remote round trips per call, each one
+ * waiting out its own timeout, for as long as the outage lasted. After a
+ * failure the provider is probed at most once per `cooloffMs`; a success
+ * clears the window immediately. `cooloffMs <= 0` disables the gate.
+ */
+export declare function createProviderCooloff(cooloffMs: number): ProviderCooloff;
+//# sourceMappingURL=featureFlags.cooloff.d.ts.map

package/dist/featureFlags/featureFlags.cooloff.js

@@ -0,0 +1,34 @@
+/**
+ * Cool-off window for a provider that is failing.
+ *
+ * @module featureFlags/featureFlags.cooloff
+ */
+/** Default cool-off after a provider failure, in ms. */
+export const DEFAULT_PROVIDER_COOLOFF_MS = 5_000;
+/**
+ * Create a cool-off gate.
+ *
+ * Without one, every evaluation against an unreachable store re-ran
+ * `getAll()` and `get(key)` — two remote round trips per call, each one
+ * waiting out its own timeout, for as long as the outage lasted. After a
+ * failure the provider is probed at most once per `cooloffMs`; a success
+ * clears the window immediately. `cooloffMs <= 0` disables the gate.
+ */
+export function createProviderCooloff(cooloffMs) {
+    const window = Number.isFinite(cooloffMs) ? Math.max(0, cooloffMs) : 0;
+    let until = 0;
+    return {
+        active() {
+            if (window === 0)
+                return false;
+            return Date.now() < until;
+        },
+        recordFailure() {
+            until = Date.now() + window;
+        },
+        recordSuccess() {
+            until = 0;
+        },
+    };
+}
+//# sourceMappingURL=featureFlags.cooloff.js.map

package/dist/featureFlags/featureFlags.core.d.ts

@@ -41,6 +41,12 @@ export interface FeatureFlagsOptions {
      * reload (`refresh()`, a provider change notification).
      */
     readonly missingFlagTtlMs?: number;
+    /**
+     * How long a failing provider is left alone before it is probed again, in
+     * ms. Default: 5,000. `0` calls the provider on every evaluation, as
+     * before. A successful call clears the window at once.
+     */
+    readonly providerCooloffMs?: number;
 }
 /** The public FeatureFlags API. */
 export interface FeatureFlags {

package/dist/featureFlags/featureFlags.core.js

@@ -10,6 +10,7 @@ import { evaluateFlag } from "../evaluator/evaluator.core.js";
 import { FeatureFlagNotFoundError, FeatureFlagProviderError, } from "../featureFlagErrors/featureFlagError.types.js";
 import { resolveDependencies, mergeContext } from "./featureFlags.resolve.js";
 import { createMissCache, DEFAULT_MISSING_FLAG_TTL_MS, } from "./featureFlags.missCache.js";
+import { createProviderCooloff, DEFAULT_PROVIDER_COOLOFF_MS, } from "./featureFlags.cooloff.js";
 /**
  * Create a FeatureFlags instance.
  *
@@ -17,8 +18,9 @@ import { createMissCache, DEFAULT_MISSING_FLAG_TTL_MS, } from "./featureFlags.mi
  * @returns A FeatureFlags API object.
  */
 export function createFeatureFlags(options) {
-    const { provider, defaultContext = {}, throwOnMissing = false, onError, throwOnProviderError = false, missingFlagTtlMs = DEFAULT_MISSING_FLAG_TTL_MS, } = options;
+    const { provider, defaultContext = {}, throwOnMissing = false, onError, throwOnProviderError = false, missingFlagTtlMs = DEFAULT_MISSING_FLAG_TTL_MS, providerCooloffMs = DEFAULT_PROVIDER_COOLOFF_MS, } = options;
     const misses = createMissCache(missingFlagTtlMs);
+    const cooloff = createProviderCooloff(providerCooloffMs);
     let registry = createFeatureFlagRegistry();
     let loaded = false;
     /**
@@ -27,6 +29,7 @@ export function createFeatureFlags(options) {
      * @returns `false` when the failure was contained.
      */
     function handleProviderError(error, source) {
+        cooloff.recordFailure();
         if (throwOnProviderError)
             throw error;
         onError?.(error instanceof Error
@@ -42,6 +45,7 @@ export function createFeatureFlags(options) {
             registry = createFeatureFlagRegistry(flags);
             loaded = true;
             misses.clear();
+            cooloff.recordSuccess();
             return true;
         }
         catch (error) {
@@ -54,20 +58,42 @@ export function createFeatureFlags(options) {
         // every single evaluation.
         if (loaded)
             return true;
+        // A provider that just failed is left alone until its window closes,
+        // rather than being re-queried (and waited on) by every evaluation.
+        if (cooloff.active())
+            return false;
         return load();
     }
+    /**
+     * Fails a bulk read that has no flags because the store could not be read.
+     *
+     * `evaluate()` can say `reason: "error"` per flag; a `Map` or an array has
+     * nowhere to put that, and an empty one is indistinguishable from "no flags
+     * are configured" — a total outage would otherwise ship to a browser as
+     * every flag being off. `onError` still sees the underlying failure first.
+     *
+     * @throws {FeatureFlagProviderError} When the flags were never loaded.
+     */
+    function requireAvailable(available, operation) {
+        if (available)
+            return;
+        throw new FeatureFlagProviderError(`Feature flags are unavailable: ${operation}() cannot report flags because the provider could not be loaded.`, { provider: "FeatureFlagProvider.getAll" });
+    }
     async function resolveFlag(key) {
         const known = registry.get(key);
         if (known)
             return { flag: known, reachable: true };
         if (misses.has(key))
             return { flag: undefined, reachable: true };
+        if (cooloff.active())
+            return { flag: undefined, reachable: false };
         try {
             const flag = await provider.get(key);
             if (flag)
                 registry.set(flag);
             else if (loaded)
                 misses.add(key);
+            cooloff.recordSuccess();
             return { flag, reachable: true };
         }
         catch (error) {
@@ -86,6 +112,7 @@ export function createFeatureFlags(options) {
         registry = createFeatureFlagRegistry(flags);
         loaded = true;
         misses.clear();
+        cooloff.recordSuccess();
     });
     const api = {
         async isEnabled(key, context) {
@@ -136,7 +163,7 @@ export function createFeatureFlags(options) {
             return evaluateFlag(flag, mergedCtx, { dependenciesSatisfied });
         },
         async snapshot(context) {
-            await ensureLoaded();
+            requireAvailable(await ensureLoaded(), "snapshot");
             const mergedCtx = mergeContext(defaultContext, context);
             const flags = registry.getAll();
             const results = new Map();
@@ -163,7 +190,7 @@ export function createFeatureFlags(options) {
             await load();
         },
         async getAll() {
-            await ensureLoaded();
+            requireAvailable(await ensureLoaded(), "getAll");
             return registry.getAll();
         },
         close() {

package/dist/utils/utils.helper.d.ts

@@ -13,6 +13,15 @@ import type { FeatureFlagValue } from "../featureFlagTypes/featureFlagRule/featu
 export { isPlainObject } from "@zudojs/types";
 /**
  * Check if two feature flag values are equal.
+ *
+ * The comparison is structural, not `JSON.stringify`: key order does not
+ * matter, a key whose value is `undefined` is not the same as an absent key,
+ * and a self-referencing value is compared instead of throwing. Arrays match
+ * element-wise, `Date`s by instant, and `NaN` equals `NaN`. Any other class
+ * instance (Map, Set, RegExp, …) matches only by reference.
+ *
+ * `@zudojs/types` owns the shared type guards but has no deep-equality helper,
+ * so the walk lives here rather than pulling in a new dependency.
  */
 export declare function valuesEqual(a: FeatureFlagValue, b: FeatureFlagValue): boolean;
 //# sourceMappingURL=utils.helper.d.ts.map

package/dist/utils/utils.helper.js

@@ -12,17 +12,69 @@
 export { isPlainObject } from "@zudojs/types";
 /**
  * Check if two feature flag values are equal.
+ *
+ * The comparison is structural, not `JSON.stringify`: key order does not
+ * matter, a key whose value is `undefined` is not the same as an absent key,
+ * and a self-referencing value is compared instead of throwing. Arrays match
+ * element-wise, `Date`s by instant, and `NaN` equals `NaN`. Any other class
+ * instance (Map, Set, RegExp, …) matches only by reference.
+ *
+ * `@zudojs/types` owns the shared type guards but has no deep-equality helper,
+ * so the walk lives here rather than pulling in a new dependency.
  */
 export function valuesEqual(a, b) {
+    return deepEqual(a, b, new Map());
+}
+function deepEqual(a, b, seen) {
     if (a === b)
         return true;
-    if (a === null || b === null)
+    if (typeof a === "number" && typeof b === "number") {
+        return Number.isNaN(a) && Number.isNaN(b);
+    }
+    if (typeof a !== "object" || typeof b !== "object")
         return false;
-    if (typeof a !== typeof b)
+    if (a === null || b === null)
         return false;
-    if (typeof a === "object" && typeof b === "object") {
-        return JSON.stringify(a) === JSON.stringify(b);
+    // A pair already on the comparison stack is assumed equal: the cycle it
+    // closes is only reached through positions that matched.
+    const pending = seen.get(a);
+    if (pending?.has(b) === true)
+        return true;
+    if (pending)
+        pending.add(b);
+    else
+        seen.set(a, new Set([b]));
+    try {
+        return deepEqualObjects(a, b, seen);
     }
-    return false;
+    finally {
+        seen.get(a)?.delete(b);
+    }
+}
+function deepEqualObjects(a, b, seen) {
+    if (a instanceof Date || b instanceof Date) {
+        return (a instanceof Date && b instanceof Date && a.getTime() === b.getTime());
+    }
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b))
+            return false;
+        if (a.length !== b.length)
+            return false;
+        return a.every((item, index) => deepEqual(item, b[index], seen));
+    }
+    if (!isComparableObject(a) || !isComparableObject(b))
+        return false;
+    const aKeys = Object.keys(a);
+    const bKeys = Object.keys(b);
+    if (aKeys.length !== bKeys.length)
+        return false;
+    const other = b;
+    return aKeys.every((key) => Object.hasOwn(other, key) &&
+        deepEqual(a[key], other[key], seen));
+}
+/** Plain objects and null-prototype records; anything else compares by reference. */
+function isComparableObject(value) {
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
 }
 //# sourceMappingURL=utils.helper.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/feature-flags",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Feature flag system with deterministic rollouts, rule engine, providers, variants, snapshots, and evaluation context.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -11,8 +11,8 @@
     }
   },
   "dependencies": {
-    "@zudojs/errors": "1.1.0",
-    "@zudojs/types": "1.1.0"
+    "@zudojs/errors": "1.2.0",
+    "@zudojs/types": "1.1.1"
   },
   "devDependencies": {
     "typescript": "7.0.2",