@zudojs/feature-flags 1.1.0 → 1.3.0

package/README.md

@@ -2,6 +2,12 @@
 
 Feature flag system with deterministic rollouts, rule engine, providers, variants, snapshots, and evaluation context.
 
+<!-- zudo-docs:start -->
+
+**Documentation:** [zudojs.oyinlola.site/docs/packages-feature-flags](https://zudojs.oyinlola.site/docs/packages-feature-flags) · **For AI agents:** [Markdown version](https://zudojs.oyinlola.site/docs/packages-feature-flags.md), [llms.txt](https://zudojs.oyinlola.site/llms.txt)
+
+<!-- zudo-docs:end -->
+
 ## Installation
 
 ```bash
@@ -55,7 +61,7 @@ interface FeatureFlag {
   state?: "active" | "archived" | "draft";
   visibility?: "client" | "server";
   rules?: FeatureFlagRule[]; // evaluated in order, first match wins
-  dependencies?: string[]; // other flags that must be enabled
+  dependencies?: string[]; // other flags that must be on for the same context
   metadata?: { expiresAt?: Date /* … */ };
 }
 ```
@@ -70,7 +76,7 @@ from JSON does — and expires the flag just the same.
 | `static`     | always                                          |
 | `user`       | `context.userId` is in `users`                  |
 | `tenant`     | `context.tenantId` is in `tenants`              |
-| `attribute`  | `attribute` compared to `value` with `operator` |
+| `attribute`  | `attribute` compared to `value` with `operator`; serves `result` (default `true`) |
 | `percentage` | the subject's bucket falls inside `percentage`  |
 | `schedule`   | now is between `startAt` and `endAt`            |
 | `variant`    | always, assigning a variant by weight           |
@@ -86,9 +92,25 @@ Operators: `equals`, `not_equals`, `contains`, `starts_with`, `ends_with`,
 Attribute paths use dot notation and are resolved against the context first,
 then `context.attributes`. Only **own** properties are traversed:
 `__proto__`, `constructor` and `prototype` never resolve, so a rule cannot
-accidentally (or deliberately) target everyone through the prototype chain. A
-`matches` pattern that does not compile, or is longer than 512 characters,
-matches nothing instead of throwing.
+accidentally (or deliberately) target everyone through the prototype chain.
+
+An attribute rule's `value` is the comparison operand; what a match serves is
+`result`, which defaults to `true`. On a non-boolean flag set `result`:
+
+```typescript
+{ key: "theme", enabled: true, defaultValue: "light",
+  rules: [{ type: "attribute", attribute: "plan", operator: "equals", value: "pro", result: "dark" }] }
+```
+
+An attribute rule without `result` on a non-boolean flag is skipped, rather
+than serving `true` from a string flag.
+
+A `matches` pattern matches nothing, instead of throwing or hanging, when it
+does not compile, is longer than 512 characters, or could backtrack
+catastrophically — a repeated group that itself repeats or alternates
+(`(a+)+`, `(a|aa)*`, `(\w+\s?){2,}`) or a backreference. It is tested only
+against values up to 1,024 characters. Patterns used for targeting, such as
+`@example\.com$` or `^(beta|alpha)-`, are unaffected.
 
 ## Rollouts and variants
 
@@ -105,9 +127,13 @@ is 90/10.
 ## Dependencies
 
 A flag may declare `dependencies`. It evaluates normally only when every
-dependency — transitively — exists and is enabled; otherwise the result is
-`dependency_disabled` with the declared default. Cycles resolve to disabled;
-a shared dependency reached down two branches is not a cycle.
+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
+branches is not a cycle.
 
 `evaluateFlag()` on its own has no registry and cannot resolve dependencies,
 so it reports `dependency_disabled` for any flag that declares them unless
@@ -138,6 +164,18 @@ and `createCompositeProvider` forward those announcements — the cache is
 dropped first, and the composite announces its merged view — so the stack
 above still propagates a change made to `remoteProvider`.
 
+`createCachedProvider` holds at most `maxEntries` keys (default 1,000),
+sweeping expired entries and then evicting the oldest. `createFeatureFlags`
+remembers a key the provider does not know for `missingFlagTtlMs` (default
+30 s, at most 1,000 keys; `0` disables it), so request-supplied keys cannot
+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.
 
@@ -167,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/evaluator/evaluator.core.js

@@ -101,6 +101,14 @@ export function evaluateFlag(flag, context = {}, options = {}) {
     }
     for (let i = 0; i < flag.rules.length; i++) {
         const rule = flag.rules[i];
+        // An attribute rule with no `result` serves `true`, which is only a
+        // value of a boolean flag. On any other flag it is skipped, rather than
+        // handing `get<string>()` a boolean.
+        if (rule.type === "attribute" &&
+            rule.result === undefined &&
+            typeof flag.defaultValue !== "boolean") {
+            continue;
+        }
         const result = evaluateRule(rule, context, flag.key);
         if (result.matched) {
             const reason = reasonFor(rule.type);

package/dist/evaluator/evaluatorAttribute.js

@@ -5,6 +5,7 @@
  *
  * @module evaluator/evaluatorAttribute
  */
+import { isUnsafePattern, MAX_MATCH_INPUT_LENGTH, } from "./evaluatorPattern.safety.js";
 /**
  * Path segments that must never be traversed.
  *
@@ -58,7 +59,8 @@ const MAX_CACHED_PATTERNS = 256;
  *
  * A pattern that does not compile used to throw out of rule evaluation and
  * out of `isEnabled()` with it. A flag whose configuration is broken must
- * fall back to its default, not take the caller down.
+ * fall back to its default, not take the caller down. A pattern that could
+ * backtrack catastrophically is treated the same way: it never matches.
  */
 function compilePattern(pattern) {
     if (pattern.length > MAX_PATTERN_LENGTH)
@@ -68,7 +70,7 @@ function compilePattern(pattern) {
         return cached;
     let compiled;
     try {
-        compiled = new RegExp(pattern);
+        compiled = isUnsafePattern(pattern) ? null : new RegExp(pattern);
     }
     catch {
         compiled = null;
@@ -132,6 +134,8 @@ export function matchAttribute(actual, operator, expected) {
             if (typeof actual !== "string" || typeof expected !== "string") {
                 return false;
             }
+            if (actual.length > MAX_MATCH_INPUT_LENGTH)
+                return false;
             const pattern = compilePattern(expected);
             return pattern !== null && pattern.test(actual);
         }

package/dist/evaluator/evaluatorPattern.safety.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Guards for the `matches` operator's regular expressions.
+ *
+ * Flag patterns run on the request path, synchronously, against attribute
+ * values the client controls (email, user agent). JavaScript's backtracking
+ * engine takes exponential time on a pattern such as `^(a+)+$`: 28 characters
+ * cost over three seconds of blocked event loop. Such patterns are refused,
+ * and the input a pattern runs against is capped.
+ *
+ * @module evaluator/evaluatorPattern.safety
+ */
+/** Longest attribute value a `matches` rule is tested against. */
+export declare const MAX_MATCH_INPUT_LENGTH = 1024;
+/**
+ * Whether a pattern can backtrack catastrophically.
+ *
+ * Conservative: it refuses any repeated group that itself contains a
+ * repetition or an alternation (`(a+)+`, `(a|aa)*`, `(\w+\s?){2,}`), and any
+ * backreference. Patterns used for targeting — `@example\.com$`,
+ * `^(beta|alpha)-` — contain neither.
+ */
+export declare function isUnsafePattern(pattern: string): boolean;
+//# sourceMappingURL=evaluatorPattern.safety.d.ts.map

package/dist/evaluator/evaluatorPattern.safety.js

@@ -0,0 +1,79 @@
+/**
+ * Guards for the `matches` operator's regular expressions.
+ *
+ * Flag patterns run on the request path, synchronously, against attribute
+ * values the client controls (email, user agent). JavaScript's backtracking
+ * engine takes exponential time on a pattern such as `^(a+)+$`: 28 characters
+ * cost over three seconds of blocked event loop. Such patterns are refused,
+ * and the input a pattern runs against is capped.
+ *
+ * @module evaluator/evaluatorPattern.safety
+ */
+/** Longest attribute value a `matches` rule is tested against. */
+export const MAX_MATCH_INPUT_LENGTH = 1024;
+/**
+ * Whether a repetition quantifier starts at `index`: `*`, `+` or `{n…}`.
+ *
+ * Bounded counts are included on purpose: `(.*a){20}` is polynomial of
+ * degree twenty, which is no better in practice.
+ */
+function isRepetition(pattern, index) {
+    const char = pattern[index];
+    if (char === "*" || char === "+")
+        return true;
+    return char === "{" && /^\{\d+(,\d*)?\}/.test(pattern.slice(index));
+}
+/**
+ * Whether a pattern can backtrack catastrophically.
+ *
+ * Conservative: it refuses any repeated group that itself contains a
+ * repetition or an alternation (`(a+)+`, `(a|aa)*`, `(\w+\s?){2,}`), and any
+ * backreference. Patterns used for targeting — `@example\.com$`,
+ * `^(beta|alpha)-` — contain neither.
+ */
+export function isUnsafePattern(pattern) {
+    if (/\\[1-9]|\\k</.test(pattern))
+        return true;
+    const stack = [];
+    let risky = false;
+    let inClass = false;
+    for (let i = 0; i < pattern.length; i++) {
+        const char = pattern[i];
+        if (char === "\\") {
+            i += 1;
+            continue;
+        }
+        if (inClass) {
+            if (char === "]")
+                inClass = false;
+            continue;
+        }
+        if (char === "[") {
+            inClass = true;
+        }
+        else if (char === "(") {
+            stack.push(risky);
+            risky = false;
+        }
+        else if (char === ")") {
+            const inner = risky;
+            risky = stack.pop() ?? false;
+            if (isRepetition(pattern, i + 1)) {
+                if (inner)
+                    return true;
+                risky = true;
+            }
+            else if (inner) {
+                risky = true;
+            }
+        }
+        else if (char === "|") {
+            risky = true;
+        }
+        else if (isRepetition(pattern, i)) {
+            risky = true;
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=evaluatorPattern.safety.js.map

package/dist/evaluator/evaluatorRule.core.js

@@ -39,7 +39,7 @@ export function evaluateRule(rule, context, flagKey) {
                 actual = resolvePath(context.attributes, rule.attribute);
             }
             const matched = matchAttribute(actual, rule.operator, rule.value);
-            return { matched, value: matched ? true : undefined };
+            return { matched, value: matched ? (rule.result ?? true) : undefined };
         }
         case "percentage": {
             const subject = context.userId ?? context.tenantId ?? context.sessionId ?? "anonymous";

package/dist/featureFlagTypes/featureFlagRule/featureFlagRule.type.d.ts

@@ -25,12 +25,22 @@ export interface FeatureFlagTenantRule {
     readonly tenants: readonly string[];
     readonly value: FeatureFlagValue;
 }
-/** Target by attribute matching. */
+/**
+ * Target by attribute matching.
+ *
+ * `value` is the comparison operand, not what the rule serves. What a match
+ * serves is `result`, which defaults to `true` — so on a non-boolean flag an
+ * attribute rule must set `result`, and one that does not is skipped rather
+ * than serving a boolean from a string, number or object flag.
+ */
 export interface FeatureFlagAttributeRule {
     readonly type: "attribute";
     readonly attribute: string;
     readonly operator: FeatureFlagOperator;
+    /** The operand the attribute is compared against. */
     readonly value: unknown;
+    /** The value served when the rule matches. Default: `true`. */
+    readonly result?: FeatureFlagValue;
 }
 /** Percentage-based rollout — deterministic per subject. */
 export interface FeatureFlagPercentageRule {

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

@@ -34,6 +34,19 @@ export interface FeatureFlagsOptions {
      * handles itself.
      */
     readonly throwOnProviderError?: boolean;
+    /**
+     * How long a key the provider does not know is remembered as missing, in
+     * ms. Default: 30,000. At most 1,000 missing keys are kept. `0` asks the
+     * provider on every evaluation, as before. The memory is dropped on every
+     * 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

@@ -9,6 +9,8 @@ import { createFeatureFlagRegistry } from "../registry/registry.core.js";
 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.
  *
@@ -16,7 +18,9 @@ import { resolveDependencies, mergeContext } from "./featureFlags.resolve.js";
  * @returns A FeatureFlags API object.
  */
 export function createFeatureFlags(options) {
-    const { provider, defaultContext = {}, throwOnMissing = false, onError, throwOnProviderError = false, } = 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;
     /**
@@ -25,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
@@ -39,6 +44,8 @@ export function createFeatureFlags(options) {
             const flags = await provider.getAll();
             registry = createFeatureFlagRegistry(flags);
             loaded = true;
+            misses.clear();
+            cooloff.recordSuccess();
             return true;
         }
         catch (error) {
@@ -51,16 +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) {
@@ -78,6 +111,8 @@ export function createFeatureFlags(options) {
     let unsubscribe = provider.subscribe?.((flags) => {
         registry = createFeatureFlagRegistry(flags);
         loaded = true;
+        misses.clear();
+        cooloff.recordSuccess();
     });
     const api = {
         async isEnabled(key, context) {
@@ -124,11 +159,11 @@ export function createFeatureFlags(options) {
             }
             const dependenciesSatisfied = !flag.dependencies ||
                 flag.dependencies.length === 0 ||
-                resolveDependencies(key, registry);
+                resolveDependencies(key, registry, undefined, undefined, mergedCtx);
             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();
@@ -140,7 +175,7 @@ export function createFeatureFlags(options) {
                     continue;
                 const dependenciesSatisfied = !flag.dependencies ||
                     flag.dependencies.length === 0 ||
-                    resolveDependencies(flag.key, registry);
+                    resolveDependencies(flag.key, registry, undefined, undefined, mergedCtx);
                 results.set(flag.key, evaluateFlag(flag, mergedCtx, { dependenciesSatisfied }));
             }
             return results;
@@ -155,7 +190,7 @@ export function createFeatureFlags(options) {
             await load();
         },
         async getAll() {
-            await ensureLoaded();
+            requireAvailable(await ensureLoaded(), "getAll");
             return registry.getAll();
         },
         close() {

package/dist/featureFlags/featureFlags.dependency.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Dependency satisfaction for feature flags.
+ *
+ * @module featureFlags/featureFlags.dependency
+ */
+import type { FeatureFlag } from "../featureFlagTypes/featureFlag.interface.js";
+import type { FeatureFlagContext } from "../featureFlagTypes/featureFlagContext.js";
+import type { FeatureFlagEvaluation } from "../featureFlagTypes/featureFlagEvaluation.js";
+import type { FeatureFlagRegistry } from "../registry/registry.core.js";
+/**
+ * Whether a prerequisite's evaluation counts as "on" for this context.
+ *
+ * It must not be gated (disabled, archived, draft, expired, or blocked by its
+ * own dependencies) and must not evaluate to `false`, `null` or `undefined`.
+ * A percentage rollout the subject is outside of evaluates to the default,
+ * typically `false`, so the dependent flag stays off for that subject too.
+ */
+export declare function isDependencyOn(evaluation: FeatureFlagEvaluation): boolean;
+/**
+ * Whether every dependency of a flag is on for a context.
+ *
+ * Each prerequisite is *evaluated* — state, expiry, rules and rollout — for
+ * the same context, recursively. Checking only its kill switch let a flag
+ * turn on for users who could not have the feature it needs: an archived or
+ * expired prerequisite, or one rolled out to someone else.
+ *
+ * @param flag - The dependent flag.
+ * @param registry - Where prerequisites are looked up.
+ * @param context - The evaluation context.
+ * @param chain - Keys on the current path, for cycle detection.
+ * @param memo - Results for this context, so a diamond is walked once.
+ */
+export declare function dependenciesOn(flag: FeatureFlag, registry: FeatureFlagRegistry, context: FeatureFlagContext, chain?: Set<string>, memo?: Map<string, boolean>): boolean;
+//# sourceMappingURL=featureFlags.dependency.d.ts.map

package/dist/featureFlags/featureFlags.dependency.js

@@ -0,0 +1,72 @@
+/**
+ * Dependency satisfaction for feature flags.
+ *
+ * @module featureFlags/featureFlags.dependency
+ */
+import { evaluateFlag } from "../evaluator/evaluator.core.js";
+/** Reasons that mean the prerequisite is off, whatever its value. */
+const GATED = new Set([
+    "disabled",
+    "expired",
+    "dependency_disabled",
+    "not_found",
+    "error",
+]);
+/**
+ * Whether a prerequisite's evaluation counts as "on" for this context.
+ *
+ * It must not be gated (disabled, archived, draft, expired, or blocked by its
+ * own dependencies) and must not evaluate to `false`, `null` or `undefined`.
+ * A percentage rollout the subject is outside of evaluates to the default,
+ * typically `false`, so the dependent flag stays off for that subject too.
+ */
+export function isDependencyOn(evaluation) {
+    if (GATED.has(evaluation.reason))
+        return false;
+    return (evaluation.value !== false &&
+        evaluation.value !== null &&
+        evaluation.value !== undefined);
+}
+/**
+ * Whether every dependency of a flag is on for a context.
+ *
+ * Each prerequisite is *evaluated* — state, expiry, rules and rollout — for
+ * the same context, recursively. Checking only its kill switch let a flag
+ * turn on for users who could not have the feature it needs: an archived or
+ * expired prerequisite, or one rolled out to someone else.
+ *
+ * @param flag - The dependent flag.
+ * @param registry - Where prerequisites are looked up.
+ * @param context - The evaluation context.
+ * @param chain - Keys on the current path, for cycle detection.
+ * @param memo - Results for this context, so a diamond is walked once.
+ */
+export function dependenciesOn(flag, registry, context, chain = new Set([flag.key]), memo = new Map()) {
+    for (const key of flag.dependencies ?? []) {
+        const known = memo.get(key);
+        if (known !== undefined) {
+            if (!known)
+                return false;
+            continue;
+        }
+        if (chain.has(key))
+            return false;
+        const dependency = registry.get(key);
+        let on = false;
+        if (dependency) {
+            chain.add(key);
+            try {
+                const inner = dependenciesOn(dependency, registry, context, chain, memo);
+                on = isDependencyOn(evaluateFlag(dependency, context, { dependenciesSatisfied: inner }));
+            }
+            finally {
+                chain.delete(key);
+            }
+        }
+        memo.set(key, on);
+        if (!on)
+            return false;
+    }
+    return true;
+}
+//# sourceMappingURL=featureFlags.dependency.js.map

package/dist/featureFlags/featureFlags.missCache.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Negative cache for flag keys the provider does not know.
+ *
+ * @module featureFlags/featureFlags.missCache
+ */
+/** Default lifetime of a remembered miss. */
+export declare const DEFAULT_MISSING_FLAG_TTL_MS = 30000;
+/** Most distinct missing keys remembered at once. */
+export declare const MAX_MISSING_FLAGS = 1000;
+/** Remembers recent "no such flag" answers. */
+export interface MissCache {
+    has(key: string): boolean;
+    add(key: string): void;
+    clear(): void;
+}
+/**
+ * Create a bounded, expiring miss cache.
+ *
+ * A registry miss used to go to `provider.get(key)` on every evaluation. When
+ * keys can come from request data (a `?flag=` switch, a client snapshot
+ * request), each distinct key was a remote round trip, every time. A miss is
+ * now remembered for `ttlMs`, up to {@link MAX_MISSING_FLAGS} keys (oldest
+ * evicted). `ttlMs <= 0` disables it.
+ */
+export declare function createMissCache(ttlMs: number): MissCache;
+//# sourceMappingURL=featureFlags.missCache.d.ts.map

package/dist/featureFlags/featureFlags.missCache.js

@@ -0,0 +1,49 @@
+/**
+ * Negative cache for flag keys the provider does not know.
+ *
+ * @module featureFlags/featureFlags.missCache
+ */
+/** Default lifetime of a remembered miss. */
+export const DEFAULT_MISSING_FLAG_TTL_MS = 30_000;
+/** Most distinct missing keys remembered at once. */
+export const MAX_MISSING_FLAGS = 1_000;
+/**
+ * Create a bounded, expiring miss cache.
+ *
+ * A registry miss used to go to `provider.get(key)` on every evaluation. When
+ * keys can come from request data (a `?flag=` switch, a client snapshot
+ * request), each distinct key was a remote round trip, every time. A miss is
+ * now remembered for `ttlMs`, up to {@link MAX_MISSING_FLAGS} keys (oldest
+ * evicted). `ttlMs <= 0` disables it.
+ */
+export function createMissCache(ttlMs) {
+    const misses = new Map();
+    return {
+        has(key) {
+            const expiresAt = misses.get(key);
+            if (expiresAt === undefined)
+                return false;
+            if (Date.now() > expiresAt) {
+                misses.delete(key);
+                return false;
+            }
+            return true;
+        },
+        add(key) {
+            if (ttlMs <= 0)
+                return;
+            misses.delete(key);
+            misses.set(key, Date.now() + ttlMs);
+            while (misses.size > MAX_MISSING_FLAGS) {
+                const oldest = misses.keys().next();
+                if (oldest.done === true)
+                    break;
+                misses.delete(oldest.value);
+            }
+        },
+        clear() {
+            misses.clear();
+        },
+    };
+}
+//# sourceMappingURL=featureFlags.missCache.js.map

package/dist/featureFlags/featureFlags.resolve.d.ts

@@ -8,13 +8,18 @@ import type { FeatureFlagRegistry } from "../registry/registry.core.js";
 /**
  * Resolve dependencies for a flag, detecting cycles.
  *
+ * A dependency is satisfied when the prerequisite *evaluates* on for the
+ * given context (see `dependenciesOn`), not merely when its kill switch is
+ * on. Without a context the prerequisites are evaluated against `{}`.
+ *
  * @param key - The flag key to resolve.
  * @param registry - The flag registry.
  * @param chain - Keys on the current resolution path, for cycle detection.
- * @param satisfied - Keys already proved satisfied, to avoid re-walking them.
- * @returns True if the flag and all its transitive dependencies are enabled.
+ * @param satisfied - Keys already proved satisfied *for this context*.
+ * @param context - The evaluation context the prerequisites are checked for.
+ * @returns True if the flag is enabled and every dependency is on.
  */
-export declare function resolveDependencies(key: string, registry: FeatureFlagRegistry, chain?: Set<string>, satisfied?: Set<string>): boolean;
+export declare function resolveDependencies(key: string, registry: FeatureFlagRegistry, chain?: Set<string>, satisfied?: Set<string>, context?: FeatureFlagContext): boolean;
 /**
  * Merge default context with provided context.
  */

package/dist/featureFlags/featureFlags.resolve.js

@@ -3,45 +3,33 @@
  *
  * @module featureFlags/featureFlags.resolve
  */
+import { dependenciesOn } from "./featureFlags.dependency.js";
 /**
  * Resolve dependencies for a flag, detecting cycles.
  *
+ * A dependency is satisfied when the prerequisite *evaluates* on for the
+ * given context (see `dependenciesOn`), not merely when its kill switch is
+ * on. Without a context the prerequisites are evaluated against `{}`.
+ *
  * @param key - The flag key to resolve.
  * @param registry - The flag registry.
  * @param chain - Keys on the current resolution path, for cycle detection.
- * @param satisfied - Keys already proved satisfied, to avoid re-walking them.
- * @returns True if the flag and all its transitive dependencies are enabled.
+ * @param satisfied - Keys already proved satisfied *for this context*.
+ * @param context - The evaluation context the prerequisites are checked for.
+ * @returns True if the flag is enabled and every dependency is on.
  */
-export function resolveDependencies(key, registry, chain = new Set(), satisfied = new Set()) {
-    // A key already proved good on another branch is good here too. Reusing one
-    // "visited" set for both jobs meant a diamond — A depends on B and C, both
-    // of which depend on D — reported D as a cycle the second time it was
-    // reached and disabled A.
+export function resolveDependencies(key, registry, chain = new Set(), satisfied = new Set(), context = {}) {
     if (satisfied.has(key))
         return true;
     if (chain.has(key))
         return false;
-    chain.add(key);
     const flag = registry.get(key);
-    try {
-        if (!flag || !flag.enabled)
-            return false;
-        if (!flag.dependencies || flag.dependencies.length === 0) {
-            satisfied.add(key);
-            return true;
-        }
-        for (const dep of flag.dependencies) {
-            if (!resolveDependencies(dep, registry, chain, satisfied))
-                return false;
-        }
+    if (!flag || !flag.enabled)
+        return false;
+    const ok = dependenciesOn(flag, registry, context, new Set([...chain, key]));
+    if (ok)
         satisfied.add(key);
-        return true;
-    }
-    finally {
-        // Leaving the key in the chain would make a sibling branch see a cycle
-        // that is not there.
-        chain.delete(key);
-    }
+    return ok;
 }
 /**
  * Merge default context with provided context.

package/dist/provider/providerCached.core.d.ts

@@ -10,6 +10,12 @@ import type { FeatureFlagProvider, RefreshableFeatureFlagProvider } from "../fea
 export interface CachedProviderOptions {
     /** Time-to-live in milliseconds (default: 30,000). */
     readonly ttl?: number;
+    /**
+     * Most per-key entries held (default: 1,000). Past it, expired entries are
+     * swept and then the oldest evicted. Every distinct key asked for used to
+     * stay in the map for good, misses included.
+     */
+    readonly maxEntries?: number;
 }
 /**
  * Create a cached feature flag provider.

package/dist/provider/providerCached.core.js

@@ -14,11 +14,28 @@
  */
 export function createCachedProvider(inner, options = {}) {
     const ttl = options.ttl ?? 30_000;
+    const maxEntries = options.maxEntries ?? 1_000;
     const flagCache = new Map();
     let listCache;
     function isExpired(entry) {
         return Date.now() > entry.expiresAt;
     }
+    function remember(key, entry) {
+        flagCache.delete(key);
+        flagCache.set(key, entry);
+        if (flagCache.size <= maxEntries)
+            return;
+        for (const [cachedKey, cached] of flagCache) {
+            if (isExpired(cached))
+                flagCache.delete(cachedKey);
+        }
+        while (flagCache.size > maxEntries) {
+            const oldest = flagCache.keys().next();
+            if (oldest.done === true)
+                break;
+            flagCache.delete(oldest.value);
+        }
+    }
     function clear() {
         flagCache.clear();
         listCache = undefined;
@@ -45,7 +62,7 @@ export function createCachedProvider(inner, options = {}) {
             if (cached && !isExpired(cached))
                 return cached.value;
             const flag = await inner.get(key);
-            flagCache.set(key, { value: flag, expiresAt: Date.now() + ttl });
+            remember(key, { value: flag, expiresAt: Date.now() + ttl });
             return flag;
         },
         async getAll() {

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

@@ -5,11 +5,23 @@
  */
 import type { FeatureFlagValue } from "../featureFlagTypes/featureFlagRule/featureFlagValue.type.js";
 /**
- * Check if a value is a plain object (not null, not array).
+ * `isPlainObject` is owned by `@zudojs/types` and re-exported here so the
+ * existing public export keeps working (and is the same function).
+ *
+ * @deprecated Import `isPlainObject` from `@zudojs/types`.
  */
-export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+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

@@ -4,24 +4,77 @@
  * @module utils/utils
  */
 /**
- * Check if a value is a plain object (not null, not array).
+ * `isPlainObject` is owned by `@zudojs/types` and re-exported here so the
+ * existing public export keeps working (and is the same function).
+ *
+ * @deprecated Import `isPlainObject` from `@zudojs/types`.
  */
-export function isPlainObject(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
+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);
+    }
+    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());
     }
-    return false;
+    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.1.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,7 +11,8 @@
     }
   },
   "dependencies": {
-    "@zudojs/errors": "1.0.1"
+    "@zudojs/errors": "1.2.0",
+    "@zudojs/types": "1.1.1"
   },
   "devDependencies": {
     "typescript": "7.0.2",