@zudojs/feature-flags 1.0.0 → 1.2.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,11 +61,14 @@ 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 /* … */ };
 }
 ```
 
+`expiresAt` may also arrive as an ISO string or a timestamp — a flag loaded
+from JSON does — and expires the flag just the same.
+
 ## Rules
 
 | Type         | Matches when                                    |
@@ -67,7 +76,7 @@ interface FeatureFlag {
 | `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           |
@@ -83,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
 
@@ -102,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
@@ -130,7 +159,20 @@ const provider = createCachedProvider(
 ```
 
 `createMemoryProvider` returns a typed provider with `set`, `delete` and
-`setAll`, and it announces every change to subscribers.
+`setAll`, and it announces every change to subscribers. `createCachedProvider`
+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.
+
+`createEnvironmentProvider` parses `true`/`false` and numbers; anything else,
+including an empty `FEATURE_X=`, stays a string.
 
 ## Change propagation
 
@@ -151,6 +193,10 @@ changes.
 | Dependency not satisfied         | `dependency_disabled`, the declared default            |
 | Provider unreachable             | `error`, reported to `onError`; never enabled          |
 
+"Unreachable" covers both `getAll()` and a `get()` for a flag not yet loaded:
+a lookup the store could not answer is `error`, never `not_found`, and does
+not throw `FeatureFlagNotFoundError` under `throwOnMissing`.
+
 An unreachable store never enables a flag. Set `throwOnProviderError: true`
 to own the failure yourself instead.
 

package/dist/evaluator/evaluator.core.js

@@ -6,6 +6,25 @@
  * @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();
+}
 /** The evaluation reason a matching rule of each type produces. */
 function reasonFor(type) {
     switch (type) {
@@ -49,7 +68,7 @@ export function evaluateFlag(flag, context = {}, options = {}) {
             defaulted: true,
         };
     }
-    if (flag.metadata?.expiresAt && flag.metadata.expiresAt < new Date()) {
+    if (isExpired(flag.metadata?.expiresAt)) {
         return {
             key: flag.key,
             value: flag.defaultValue,
@@ -82,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.core.d.ts

@@ -34,6 +34,13 @@ 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;
 }
 /** The public FeatureFlags API. */
 export interface FeatureFlags {

package/dist/featureFlags/featureFlags.core.js

@@ -9,6 +9,7 @@ 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";
 /**
  * Create a FeatureFlags instance.
  *
@@ -16,7 +17,8 @@ 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, } = options;
+    const misses = createMissCache(missingFlagTtlMs);
     let registry = createFeatureFlagRegistry();
     let loaded = false;
     /**
@@ -39,6 +41,7 @@ export function createFeatureFlags(options) {
             const flags = await provider.getAll();
             registry = createFeatureFlagRegistry(flags);
             loaded = true;
+            misses.clear();
             return true;
         }
         catch (error) {
@@ -56,16 +59,24 @@ export function createFeatureFlags(options) {
     async function resolveFlag(key) {
         const known = registry.get(key);
         if (known)
-            return known;
+            return { flag: known, reachable: true };
+        if (misses.has(key))
+            return { flag: undefined, reachable: true };
         try {
             const flag = await provider.get(key);
             if (flag)
                 registry.set(flag);
-            return flag;
+            else if (loaded)
+                misses.add(key);
+            return { flag, reachable: true };
         }
         catch (error) {
             handleProviderError(error, "FeatureFlagProvider.get");
-            return undefined;
+            // A `get()` that failed is not a `get()` that found nothing: reporting
+            // it as `not_found` (or throwing FeatureFlagNotFoundError under
+            // `throwOnMissing`) told the caller the flag does not exist when the
+            // truth is that the store could not be asked.
+            return { flag: undefined, reachable: false };
         }
     }
     // A provider that can announce changes is asked to: without this, a flag
@@ -74,6 +85,7 @@ export function createFeatureFlags(options) {
     let unsubscribe = provider.subscribe?.((flags) => {
         registry = createFeatureFlagRegistry(flags);
         loaded = true;
+        misses.clear();
     });
     const api = {
         async isEnabled(key, context) {
@@ -97,9 +109,9 @@ export function createFeatureFlags(options) {
         async evaluate(key, context) {
             const available = await ensureLoaded();
             const mergedCtx = mergeContext(defaultContext, context);
-            const flag = await resolveFlag(key);
+            const { flag, reachable } = await resolveFlag(key);
             if (!flag) {
-                if (!available) {
+                if (!available || !reachable) {
                     // The store could not be reached and nothing is known about this
                     // flag. Report it as an error, not as a decision.
                     return {
@@ -120,7 +132,7 @@ 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) {
@@ -136,7 +148,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;

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,18 +14,55 @@
  */
 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;
+    }
+    // A change announced by the upstream provider is forwarded, and the cache
+    // is dropped first so a `get()` made by the listener sees the new state.
+    // Without this the wrapper had no `subscribe`, so `createFeatureFlags` on
+    // a cached provider never heard about a flag flipped at the source and
+    // served the stale copy until the TTL ran out.
+    const subscribe = inner.subscribe
+        ? {
+            subscribe(listener) {
+                return inner.subscribe((flags) => {
+                    clear();
+                    listener(flags);
+                });
+            },
+        }
+        : {};
     return {
+        ...subscribe,
         async get(key) {
             const cached = flagCache.get(key);
             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() {
@@ -36,8 +73,7 @@ export function createCachedProvider(inner, options = {}) {
             return flags;
         },
         async refresh() {
-            flagCache.clear();
-            listCache = undefined;
+            clear();
             await inner.refresh?.();
         },
     };

package/dist/provider/providerComposite.core.js

@@ -15,7 +15,68 @@
  * @returns A composite FeatureFlagProvider.
  */
 export function createCompositeProvider(providers) {
+    /**
+     * The last flag list each member produced — from its own `getAll()` or
+     * from a change it announced. Lets a change be re-announced synchronously
+     * as the merged view, without a round trip to every other member.
+     */
+    const lastSeen = new Map();
+    function merge(lists) {
+        const seen = new Set();
+        const result = [];
+        for (const flags of lists) {
+            for (const flag of flags) {
+                if (!seen.has(flag.key)) {
+                    seen.add(flag.key);
+                    result.push(flag);
+                }
+            }
+        }
+        return result;
+    }
+    async function getAll() {
+        const lists = [];
+        for (const provider of providers) {
+            const flags = await provider.getAll();
+            lastSeen.set(provider, flags);
+            lists.push(flags);
+        }
+        return merge(lists);
+    }
+    // Changes announced by any member are re-announced as the merged view, so
+    // a consumer subscribed to the composite sees the same precedence
+    // `getAll()` applies. The composite used to have no `subscribe` at all,
+    // which silently cut change propagation for every provider behind it.
+    const subscribable = providers.filter((provider) => provider.subscribe);
+    const subscribe = subscribable.length > 0
+        ? {
+            subscribe(listener) {
+                // A merged snapshot fetched asynchronously must not overtake a
+                // later change.
+                let version = 0;
+                const unsubscribes = subscribable.map((provider) => provider.subscribe((flags) => {
+                    lastSeen.set(provider, flags);
+                    const current = ++version;
+                    if (providers.every((member) => lastSeen.has(member))) {
+                        listener(merge(providers.map((member) => lastSeen.get(member))));
+                        return;
+                    }
+                    void getAll().then((merged) => {
+                        if (current === version)
+                            listener(merged);
+                    }, () => {
+                        /* a member that cannot be read keeps the last view */
+                    });
+                }));
+                return () => {
+                    for (const unsubscribe of unsubscribes)
+                        unsubscribe();
+                };
+            },
+        }
+        : {};
     return {
+        ...subscribe,
         async get(key) {
             for (const provider of providers) {
                 const flag = await provider.get(key);
@@ -24,20 +85,7 @@ export function createCompositeProvider(providers) {
             }
             return undefined;
         },
-        async getAll() {
-            const seen = new Set();
-            const result = [];
-            for (const provider of providers) {
-                const flags = await provider.getAll();
-                for (const flag of flags) {
-                    if (!seen.has(flag.key)) {
-                        seen.add(flag.key);
-                        result.push(flag);
-                    }
-                }
-            }
-            return result;
-        },
+        getAll,
         async refresh() {
             for (const provider of providers) {
                 await provider.refresh?.();

package/dist/provider/providerEnvironment.core.js

@@ -15,9 +15,14 @@ function parseEnvValue(raw) {
         return true;
     if (raw === "false")
         return false;
-    const num = Number(raw);
-    if (!Number.isNaN(num))
-        return num;
+    // `Number("")` and `Number("   ")` are both `0`, so an empty
+    // `FEATURE_X=` used to become the number zero. Only a value that is not
+    // blank is a candidate for a number; blank stays the string it is.
+    if (raw.trim() !== "") {
+        const num = Number(raw);
+        if (!Number.isNaN(num))
+            return num;
+    }
     return raw;
 }
 /**

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

@@ -5,9 +5,12 @@
  */
 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.
  */

package/dist/utils/utils.helper.js

@@ -4,11 +4,12 @@
  * @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.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/feature-flags",
-  "version": "1.0.0",
+  "version": "1.2.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,13 +11,18 @@
     }
   },
   "dependencies": {
-    "@zudojs/errors": "1.0.0"
+    "@zudojs/errors": "1.1.0",
+    "@zudojs/types": "1.1.0"
   },
   "devDependencies": {
     "typescript": "7.0.2",
     "vitest": "^4.1.11"
   },
   "license": "MIT",
+  "author": {
+    "name": "Oluwayemi Oyinlola",
+    "url": "https://github.com/oyinlola-tech"
+  },
   "type": "module",
   "files": [
     "dist",