@zudojs/feature-flags 1.2.0 → 1.4.0

package/README.md

@@ -57,8 +57,9 @@ choose.
 interface FeatureFlag {
   key: string;
   enabled: boolean; // the global kill switch
-  defaultValue: FeatureFlagValue; // used whenever no rule decides
-  state?: "active" | "archived" | "draft";
+  defaultValue: FeatureFlagValue; // used when the flag is on and no rule decides
+  offValue?: FeatureFlagValue; // served while the flag is off (see below)
+  state?: "active" | "disabled" | "archived" | "draft";
   visibility?: "client" | "server";
   rules?: FeatureFlagRule[]; // evaluated in order, first match wins
   dependencies?: string[]; // other flags that must be on for the same context
@@ -69,6 +70,27 @@ interface FeatureFlag {
 `expiresAt` may also arrive as an ISO string or a timestamp — a flag loaded
 from JSON does — and expires the flag just the same.
 
+### Off means off
+
+A flag is **off** when it is killed (`enabled: false` or `state:
+"disabled"`), a draft, archived, expired, or blocked by a dependency. An off
+flag runs no rules and serves its **off value**:
+
+1. `offValue`, when the flag declares one;
+2. otherwise `false` for a boolean flag;
+3. otherwise `defaultValue` (a string, number or object flag has no natural
+   "off", so the baseline value is served).
+
+So `{ key: "x", enabled: false, defaultValue: true }` evaluates to `false`
+and `isEnabled("x")` is `false`. Before 1.4 an off flag served
+`defaultValue`, which made the kill switch fail open for any flag whose
+default was `true`. For a variant flag, declare the variant to fall back to:
+
+```typescript
+{ key: "checkout", enabled: false, defaultValue: "new", offValue: "control",
+  rules: [{ type: "variant", variants: [{ key: "new", weight: 50 }, { key: "control", weight: 50 }] }] }
+```
+
 ## Rules
 
 | Type         | Matches when                                    |
@@ -131,8 +153,8 @@ dependency is **on for the same context**: the prerequisite is evaluated —
 state, expiry, rules, rollout, and its own dependencies — and must not be
 disabled, draft, archived or expired, nor evaluate to `false`, `null` or
 `undefined`. A prerequisite rolled out to 10% keeps its dependents off for the
-other 90%. Otherwise the result is `dependency_disabled` with the declared
-default. Cycles resolve to disabled; a shared dependency reached down two
+other 90%. Otherwise the result is `dependency_disabled` with the flag's
+off value. Cycles resolve to disabled; a shared dependency reached down two
 branches is not a cycle.
 
 `evaluateFlag()` on its own has no registry and cannot resolve dependencies,
@@ -171,8 +193,22 @@ 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.
+including an empty `FEATURE_X=`, stays a string. Every flag it reads is
+enabled.
+
+Keys are the variable name without the prefix, **lower-cased with `_`
+turned into `-`**: `FEATURE_NEW_CHECKOUT=true` is the flag `new-checkout`,
+the same key a memory or remote provider uses, so an environment variable
+overrides that flag inside a composite. `get()` normalises the key it is
+asked for the same way, so `NEW_CHECKOUT` and `new_checkout` also find it.
+Pass `keyFormat: "preserve"` to keep the variable's spelling (`NEW_CHECKOUT`),
+which was the behaviour before 1.4.
 
 ## Change propagation
 
@@ -188,9 +224,9 @@ changes.
 | -------------------------------- | ------------------------------------------------------ |
 | Flag not found                   | `not_found`, value `undefined`; `isEnabled` is `false` |
 | Flag not found, `throwOnMissing` | throws `FeatureFlagNotFoundError`                      |
-| Flag disabled or draft           | `disabled`, the declared default                       |
-| Flag archived or expired         | `expired`, the declared default                        |
-| Dependency not satisfied         | `dependency_disabled`, the declared default            |
+| Flag disabled or draft           | `disabled`, the off value; `isEnabled` is `false`      |
+| Flag archived or expired         | `expired`, the off value; `isEnabled` is `false`       |
+| Dependency not satisfied         | `dependency_disabled`, the off value                   |
 | Provider unreachable             | `error`, reported to `onError`; never enabled          |
 
 "Unreachable" covers both `getAll()` and a `get()` for a flag not yet loaded:
@@ -200,6 +236,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/evaluator/evaluator.core.d.ts

@@ -25,6 +25,10 @@ export interface EvaluateFlagOptions {
 /**
  * Evaluate a feature flag against a context.
  *
+ * A flag that is off — killed, draft, archived, expired, or blocked by a
+ * dependency — serves its off value (see {@link offValueOf}): `offValue`
+ * when declared, else `false` for a boolean flag, else `defaultValue`.
+ *
  * @param flag - The feature flag definition.
  * @param context - The evaluation context.
  * @param options - Facts the caller resolved that this function cannot.

package/dist/evaluator/evaluator.core.js

@@ -6,25 +6,7 @@
  * @module evaluator/evaluator
  */
 import { evaluateRule } from "./evaluatorRule.core.js";
-/**
- * Whether an `expiresAt` lies in the past.
- *
- * The type says `Date`, but a flag loaded from JSON — which is what every
- * remote provider hands over — carries an ISO string, and `"2020-01-01" <
- * new Date()` is always `false`. A flag that had expired at the source
- * therefore never expired here. Anything `Date` can parse is honoured; a
- * value it cannot parse is treated as no expiry.
- */
-function isExpired(expiresAt) {
-    if (expiresAt === undefined || expiresAt === null)
-        return false;
-    const time = expiresAt instanceof Date
-        ? expiresAt.getTime()
-        : typeof expiresAt === "string" || typeof expiresAt === "number"
-            ? new Date(expiresAt).getTime()
-            : Number.NaN;
-    return !Number.isNaN(time) && time < Date.now();
-}
+import { gateReason, offValueOf } from "./evaluatorGate.core.js";
 /** The evaluation reason a matching rule of each type produces. */
 function reasonFor(type) {
     switch (type) {
@@ -46,48 +28,22 @@ function reasonFor(type) {
 /**
  * Evaluate a feature flag against a context.
  *
+ * A flag that is off — killed, draft, archived, expired, or blocked by a
+ * dependency — serves its off value (see {@link offValueOf}): `offValue`
+ * when declared, else `false` for a boolean flag, else `defaultValue`.
+ *
  * @param flag - The feature flag definition.
  * @param context - The evaluation context.
  * @param options - Facts the caller resolved that this function cannot.
  * @returns A structured evaluation result.
  */
 export function evaluateFlag(flag, context = {}, options = {}) {
-    if (!flag.enabled) {
-        return {
-            key: flag.key,
-            value: flag.defaultValue,
-            reason: "disabled",
-            defaulted: true,
-        };
-    }
-    if (flag.state === "archived" || flag.state === "draft") {
-        return {
-            key: flag.key,
-            value: flag.defaultValue,
-            reason: flag.state === "archived" ? "expired" : "disabled",
-            defaulted: true,
-        };
-    }
-    if (isExpired(flag.metadata?.expiresAt)) {
-        return {
-            key: flag.key,
-            value: flag.defaultValue,
-            reason: "expired",
-            defaulted: true,
-        };
-    }
-    if (flag.dependencies &&
-        flag.dependencies.length > 0 &&
-        options.dependenciesSatisfied !== true) {
-        // Previously this returned `dependency_disabled` for *every* flag that
-        // declared a dependency, satisfied or not — so a flag with dependencies
-        // could never turn on, and the caller's own dependency resolution was
-        // computed and then discarded.
+    const gate = gateReason(flag, options);
+    if (gate) {
         return {
             key: flag.key,
-            value: flag.defaultValue,
-            reason: "dependency_disabled",
-            matchedRule: undefined,
+            value: offValueOf(flag),
+            reason: gate,
             defaulted: true,
         };
     }

package/dist/evaluator/evaluatorGate.core.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Gates that turn a flag off before any rule runs, and the value it serves
+ * while it is off.
+ *
+ * @module evaluator/evaluatorGate.core
+ */
+import type { FeatureFlag } from "../featureFlagTypes/featureFlag.interface.js";
+import type { FeatureFlagValue } from "../featureFlagTypes/featureFlagRule/featureFlagValue.type.js";
+import type { FeatureFlagEvaluationReason } from "../featureFlagTypes/featureFlagEvaluation.js";
+import type { EvaluateFlagOptions } from "./evaluator.core.js";
+/**
+ * Why a flag is off before any rule runs, or `undefined` when it is live.
+ *
+ * Checked in order: the kill switch (`enabled: false`, `state: "disabled"`),
+ * a draft, an archived or expired flag, then unsatisfied dependencies.
+ */
+export declare function gateReason(flag: FeatureFlag, options: EvaluateFlagOptions): FeatureFlagEvaluationReason | undefined;
+/**
+ * Resolve what a flag serves when it is off — killed (`enabled: false` or
+ * `state: "disabled"`), a draft, archived, expired, or blocked by a
+ * dependency.
+ *
+ * 1. `flag.offValue`, when the flag declares one.
+ * 2. `false`, for a boolean flag. The kill switch must turn a feature off,
+ *    and serving `defaultValue: true` from a killed flag left it on.
+ * 3. `flag.defaultValue` otherwise. A string, number or object flag has no
+ *    natural "off", so the declared default — the baseline experience — is
+ *    the fallback. `isEnabled()` is `false` for these regardless, because it
+ *    is `true` only for the boolean `true`.
+ *
+ * @param flag - The flag that is off.
+ * @returns The value to serve.
+ */
+export declare function offValueOf(flag: FeatureFlag): FeatureFlagValue;
+//# sourceMappingURL=evaluatorGate.core.d.ts.map

package/dist/evaluator/evaluatorGate.core.js

@@ -0,0 +1,68 @@
+/**
+ * Gates that turn a flag off before any rule runs, and the value it serves
+ * while it is off.
+ *
+ * @module evaluator/evaluatorGate.core
+ */
+/**
+ * Whether an `expiresAt` lies in the past.
+ *
+ * The type says `Date`, but a flag loaded from JSON — which is what every
+ * remote provider hands over — carries an ISO string, and `"2020-01-01" <
+ * new Date()` is always `false`. A flag that had expired at the source
+ * therefore never expired here. Anything `Date` can parse is honoured; a
+ * value it cannot parse is treated as no expiry.
+ */
+function isExpired(expiresAt) {
+    if (expiresAt === undefined || expiresAt === null)
+        return false;
+    const time = expiresAt instanceof Date
+        ? expiresAt.getTime()
+        : typeof expiresAt === "string" || typeof expiresAt === "number"
+            ? new Date(expiresAt).getTime()
+            : Number.NaN;
+    return !Number.isNaN(time) && time < Date.now();
+}
+/**
+ * Why a flag is off before any rule runs, or `undefined` when it is live.
+ *
+ * Checked in order: the kill switch (`enabled: false`, `state: "disabled"`),
+ * a draft, an archived or expired flag, then unsatisfied dependencies.
+ */
+export function gateReason(flag, options) {
+    if (!flag.enabled || flag.state === "disabled" || flag.state === "draft") {
+        return "disabled";
+    }
+    if (flag.state === "archived" || isExpired(flag.metadata?.expiresAt)) {
+        return "expired";
+    }
+    const hasDependencies = !!flag.dependencies && flag.dependencies.length > 0;
+    if (hasDependencies && options.dependenciesSatisfied !== true) {
+        return "dependency_disabled";
+    }
+    return undefined;
+}
+/**
+ * Resolve what a flag serves when it is off — killed (`enabled: false` or
+ * `state: "disabled"`), a draft, archived, expired, or blocked by a
+ * dependency.
+ *
+ * 1. `flag.offValue`, when the flag declares one.
+ * 2. `false`, for a boolean flag. The kill switch must turn a feature off,
+ *    and serving `defaultValue: true` from a killed flag left it on.
+ * 3. `flag.defaultValue` otherwise. A string, number or object flag has no
+ *    natural "off", so the declared default — the baseline experience — is
+ *    the fallback. `isEnabled()` is `false` for these regardless, because it
+ *    is `true` only for the boolean `true`.
+ *
+ * @param flag - The flag that is off.
+ * @returns The value to serve.
+ */
+export function offValueOf(flag) {
+    if (flag.offValue !== undefined)
+        return flag.offValue;
+    if (typeof flag.defaultValue === "boolean")
+        return false;
+    return flag.defaultValue;
+}
+//# sourceMappingURL=evaluatorGate.core.js.map

package/dist/featureFlagTypes/featureFlag.interface.d.ts

@@ -30,8 +30,17 @@ export interface FeatureFlag {
     readonly key: string;
     /** Default value when no rule matches. */
     readonly defaultValue: FeatureFlagValue;
-    /** Whether the flag is globally enabled. */
+    /**
+     * Whether the flag is globally enabled — the kill switch. A flag with
+     * `enabled: false` serves its off value, never `defaultValue: true`.
+     */
     readonly enabled: boolean;
+    /**
+     * What the flag serves while it is off: killed, draft, archived, expired,
+     * or blocked by a dependency. Default: `false` for a boolean flag, the
+     * `defaultValue` for any other.
+     */
+    readonly offValue?: FeatureFlagValue;
     /** Human-readable description. */
     readonly description?: string;
     /** Lifecycle state. */

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/provider/providerEnvironment.core.d.ts

@@ -3,7 +3,7 @@
  *
  * Reads feature flags from environment variables with a configurable prefix.
  *
- * Example: FEATURE_NEW_UI=true → key "NEW_UI" with value true.
+ * Example: FEATURE_NEW_UI=true → key "new-ui" with value true.
  *
  * @module provider/providerEnvironment
  */
@@ -14,7 +14,29 @@ export interface EnvironmentProviderOptions {
     readonly prefix?: string;
     /** Process env object to read from (default: process.env). */
     readonly env?: Readonly<Record<string, string | undefined>>;
+    /**
+     * How a variable name becomes a flag key, once the prefix is removed.
+     *
+     * - `"kebab"` (default): lower-cased, `_` becomes `-`, so
+     *   `FEATURE_NEW_CHECKOUT` is the flag `new-checkout` — the same key a
+     *   memory or remote provider would use.
+     * - `"preserve"`: the name as written (`NEW_CHECKOUT`), the behaviour
+     *   before 1.4.
+     *
+     * With `"kebab"`, `get()` normalises the key it is asked for the same way,
+     * so `get("NEW_CHECKOUT")`, `get("new_checkout")` and
+     * `get("new-checkout")` all find the flag.
+     */
+    readonly keyFormat?: "kebab" | "preserve";
 }
+/**
+ * Normalise an environment-derived key to kebab case: `NEW_CHECKOUT` and
+ * `new_checkout` both become `new-checkout`.
+ *
+ * @param key - The key, with the prefix already removed.
+ * @returns The lower-cased key with underscores replaced by hyphens.
+ */
+export declare function toEnvironmentFlagKey(key: string): string;
 /**
  * Create an environment-variable feature flag provider.
  *

package/dist/provider/providerEnvironment.core.js

@@ -3,10 +3,20 @@
  *
  * Reads feature flags from environment variables with a configurable prefix.
  *
- * Example: FEATURE_NEW_UI=true → key "NEW_UI" with value true.
+ * Example: FEATURE_NEW_UI=true → key "new-ui" with value true.
  *
  * @module provider/providerEnvironment
  */
+/**
+ * Normalise an environment-derived key to kebab case: `NEW_CHECKOUT` and
+ * `new_checkout` both become `new-checkout`.
+ *
+ * @param key - The key, with the prefix already removed.
+ * @returns The lower-cased key with underscores replaced by hyphens.
+ */
+export function toEnvironmentFlagKey(key) {
+    return key.toLowerCase().replace(/_/g, "-");
+}
 /**
  * Parse a string value into a feature flag value.
  */
@@ -33,12 +43,15 @@ function parseEnvValue(raw) {
  */
 export function createEnvironmentProvider(options = {}) {
     const prefix = options.prefix ?? "FEATURE_";
+    const normalise = options.keyFormat === "preserve"
+        ? (key) => key
+        : toEnvironmentFlagKey;
     const env = options.env ?? (typeof process !== "undefined" ? process.env : {});
     function readFlags() {
         const flags = [];
         for (const [key, value] of Object.entries(env)) {
             if (key.startsWith(prefix) && value !== undefined) {
-                const flagKey = key.slice(prefix.length);
+                const flagKey = normalise(key.slice(prefix.length));
                 flags.push({
                     key: flagKey,
                     enabled: true,
@@ -53,7 +66,8 @@ export function createEnvironmentProvider(options = {}) {
         async get(key) {
             if (!cached)
                 cached = readFlags();
-            return cached.find((f) => f.key === key);
+            const wanted = normalise(key);
+            return cached.find((f) => f.key === wanted);
         },
         async getAll() {
             if (!cached)

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.4.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,12 +11,12 @@
     }
   },
   "dependencies": {
-    "@zudojs/errors": "1.1.0",
-    "@zudojs/types": "1.1.0"
+    "@zudojs/errors": "1.3.0",
+    "@zudojs/types": "1.2.0"
   },
   "devDependencies": {
     "typescript": "7.0.2",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.1"
   },
   "license": "MIT",
   "author": {
@@ -43,7 +43,7 @@
     "rollout",
     "a-b-testing"
   ],
-  "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "homepage": "https://zudojs.oyinlola.site/docs/packages-feature-flags",
   "bugs": {
     "url": "https://github.com/oyinlola-tech/zudo/issues"
   },