@zudojs/feature-flags 0.1.0 → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zudojs Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -10,27 +10,185 @@ npm install @zudojs/feature-flags
 
 ## Quick Start
 
+Flags come from a **provider**; `createFeatureFlags` evaluates them against a
+context.
+
 ```typescript
-import { createFeatureFlags } from "@zudojs/feature-flags";
+import {
+  createFeatureFlags,
+  createMemoryProvider,
+} from "@zudojs/feature-flags";
 
 const flags = createFeatureFlags({
-  rules: [
-    { key: "new-ui", rollout: 0.1 },
-    { key: "beta-feature", users: ["user-123"] },
-  ],
+  provider: createMemoryProvider([
+    {
+      key: "new-ui",
+      enabled: true,
+      defaultValue: false,
+      rules: [{ type: "percentage", percentage: 10, value: true }],
+    },
+    {
+      key: "beta-feature",
+      enabled: true,
+      defaultValue: false,
+      rules: [{ type: "user", users: ["user-123"], value: true }],
+    },
+  ]),
 });
 
-const enabled = await flags.isEnabled("new-ui", { userId: "user-456" });
+await flags.isEnabled("beta-feature", { userId: "user-123" }); // true
+await flags.isEnabled("new-ui", { userId: "user-456" }); // stable per user
+```
+
+`isEnabled` is strictly boolean: a flag whose value is a string, a number or
+an object reports `false`. Use `get()` for a typed value, or `getBoolean(key,
+fallback)` when a missing or unreachable flag should fall back to a value you
+choose.
+
+## Flag definition
+
+```typescript
+interface FeatureFlag {
+  key: string;
+  enabled: boolean; // the global kill switch
+  defaultValue: FeatureFlagValue; // used whenever no rule decides
+  state?: "active" | "archived" | "draft";
+  visibility?: "client" | "server";
+  rules?: FeatureFlagRule[]; // evaluated in order, first match wins
+  dependencies?: string[]; // other flags that must be enabled
+  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                                    |
+| ------------ | ----------------------------------------------- |
+| `static`     | always                                          |
+| `user`       | `context.userId` is in `users`                  |
+| `tenant`     | `context.tenantId` is in `tenants`              |
+| `attribute`  | `attribute` compared to `value` with `operator` |
+| `percentage` | the subject's bucket falls inside `percentage`  |
+| `schedule`   | now is between `startAt` and `endAt`            |
+| `variant`    | always, assigning a variant by weight           |
+
+Rules are evaluated in declaration order and the first match wins. The
+subject for `percentage` and `variant` is `userId`, then `tenantId`, then
+`sessionId`, then `"anonymous"`.
+
+Operators: `equals`, `not_equals`, `contains`, `starts_with`, `ends_with`,
+`in`, `not_in`, `greater_than`, `greater_than_or_equal`, `less_than`,
+`less_than_or_equal`, `exists`, `matches`.
+
+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.
+
+## Rollouts and variants
+
+```typescript
+import { getBucket, isInRollout, hashString } from "@zudojs/feature-flags";
 ```
 
-## Features
+Bucketing is deterministic: `hash(flagKey + ":" + subject)` over 10,000
+buckets, so the same subject always lands in the same bucket for the same
+flag, and raising a percentage never removes anyone already inside it.
+Variant weights are applied over those same buckets, so a 90/10 split really
+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.
+
+`evaluateFlag()` on its own has no registry and cannot resolve dependencies,
+so it reports `dependency_disabled` for any flag that declares them unless
+the caller passes `{ dependenciesSatisfied: true }`.
+
+## Providers
+
+```typescript
+import {
+  createMemoryProvider,
+  createEnvironmentProvider,
+  createCompositeProvider,
+  createCachedProvider,
+} from "@zudojs/feature-flags";
+
+const provider = createCachedProvider(
+  createCompositeProvider([
+    createEnvironmentProvider({ prefix: "FEATURE_" }),
+    remoteProvider,
+  ]),
+  { ttl: 30_000 },
+);
+```
+
+`createMemoryProvider` returns a typed provider with `set`, `delete` and
+`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`.
+
+`createEnvironmentProvider` parses `true`/`false` and numbers; anything else,
+including an empty `FEATURE_X=`, stays a string.
+
+## Change propagation
+
+`createFeatureFlags` subscribes to the provider when it offers `subscribe()`,
+so a flag flipped at the source reaches an already-loaded instance without a
+manual `refresh()`. Call `flags.close()` to unsubscribe, and
+`flags.refresh()` to reload explicitly from a provider that cannot announce
+changes.
+
+## Failure behaviour
+
+| Situation                        | Result                                                 |
+| -------------------------------- | ------------------------------------------------------ |
+| 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            |
+| 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.
+
+```typescript
+const flags = createFeatureFlags({
+  provider,
+  onError: (error, source) => logger.error({ error, source }, "flag store"),
+});
+```
+
+## Snapshots
+
+```typescript
+const snapshot = await flags.snapshot({ userId });
+```
+
+Only flags explicitly marked `visibility: "client"` are included — a snapshot
+is shipped to a browser, so a flag that declares no visibility is withheld.
+
+## Errors
 
-- Percentage rollouts
-- User and segment targeting
-- A/B testing variants
-- Rule engine with AND/OR logic
-- Snapshot export for client-side flags
-- Evaluation context
+`FeatureFlagError` is the base: `FeatureFlagNotFoundError` ·
+`FeatureFlagProviderError` · `FeatureFlagEvaluationError` ·
+`FeatureFlagRuleError` · `FeatureFlagDependencyError` ·
+`FeatureFlagConfigurationError` · `FeatureFlagTypeError`.
 
 ## Use Cases
 

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

@@ -9,12 +9,26 @@ import type { FeatureFlag } from "../featureFlagTypes/featureFlag.interface.js";
 import type { FeatureFlagContext } from "../featureFlagTypes/featureFlagContext.js";
 import type { FeatureFlagValue } from "../featureFlagTypes/featureFlagRule/featureFlagValue.type.js";
 import type { FeatureFlagEvaluation } from "../featureFlagTypes/featureFlagEvaluation.js";
+/** Options for {@link evaluateFlag}. */
+export interface EvaluateFlagOptions {
+    /**
+     * Whether the flag's declared dependencies have been resolved and are all
+     * enabled.
+     *
+     * `evaluateFlag` has no registry and cannot resolve a dependency itself, so
+     * it defaults to `false` and returns `dependency_disabled` — the safe
+     * answer for a flag whose preconditions are unknown. The caller that *can*
+     * resolve them (`createFeatureFlags`) passes `true` once it has.
+     */
+    readonly dependenciesSatisfied?: boolean;
+}
 /**
  * Evaluate a feature flag against a context.
  *
  * @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 declare function evaluateFlag<TValue extends FeatureFlagValue = FeatureFlagValue>(flag: FeatureFlag, context?: FeatureFlagContext): FeatureFlagEvaluation<TValue>;
+export declare function evaluateFlag<TValue extends FeatureFlagValue = FeatureFlagValue>(flag: FeatureFlag, context?: FeatureFlagContext, options?: EvaluateFlagOptions): FeatureFlagEvaluation<TValue>;
 //# sourceMappingURL=evaluator.core.d.ts.map

package/dist/evaluator/evaluator.core.js

@@ -6,14 +6,52 @@
  * @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) {
+        case "percentage":
+            return "percentage_rollout";
+        case "variant":
+            return "variant_assignment";
+        case "static":
+            return "static";
+        case "user":
+        case "tenant":
+            // Explicit targeting, which is what `target_match` is for — it was a
+            // declared reason nothing ever produced.
+            return "target_match";
+        default:
+            return "rule_match";
+    }
+}
 /**
  * Evaluate a feature flag against a context.
  *
  * @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 = {}) {
+export function evaluateFlag(flag, context = {}, options = {}) {
     if (!flag.enabled) {
         return {
             key: flag.key,
@@ -30,7 +68,7 @@ export function evaluateFlag(flag, context = {}) {
             defaulted: true,
         };
     }
-    if (flag.metadata?.expiresAt && flag.metadata.expiresAt < new Date()) {
+    if (isExpired(flag.metadata?.expiresAt)) {
         return {
             key: flag.key,
             value: flag.defaultValue,
@@ -38,7 +76,13 @@ export function evaluateFlag(flag, context = {}) {
             defaulted: true,
         };
     }
-    if (flag.dependencies && flag.dependencies.length > 0) {
+    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.
         return {
             key: flag.key,
             value: flag.defaultValue,
@@ -59,13 +103,7 @@ export function evaluateFlag(flag, context = {}) {
         const rule = flag.rules[i];
         const result = evaluateRule(rule, context, flag.key);
         if (result.matched) {
-            const reason = rule.type === "percentage"
-                ? "percentage_rollout"
-                : rule.type === "variant"
-                    ? "variant_assignment"
-                    : rule.type === "static"
-                        ? "static"
-                        : "rule_match";
+            const reason = reasonFor(rule.type);
             return {
                 key: flag.key,
                 value: (result.value ?? flag.defaultValue),

package/dist/evaluator/evaluatorAttribute.d.ts

@@ -9,6 +9,11 @@ import type { FeatureFlagOperator } from "../featureFlagTypes/featureFlagRule/fe
 /**
  * Safely resolve a dot-notation path from an object.
  *
+ * Only own, enumerable-or-not *own* properties are traversed: `toString`,
+ * `constructor` and friends live on the prototype, and resolving them made
+ * `{ attribute: "toString", operator: "exists" }` match every context there
+ * has ever been — a targeting rule that silently targets everyone.
+ *
  * @param obj - The object to traverse.
  * @param path - Dot-separated path (e.g. "user.country").
  * @returns The value at the path, or undefined.

package/dist/evaluator/evaluatorAttribute.js

@@ -5,26 +5,79 @@
  *
  * @module evaluator/evaluatorAttribute
  */
+/**
+ * Path segments that must never be traversed.
+ *
+ * Evaluation context attributes come from request data, and a rule's
+ * attribute path comes from flag configuration. Either side reaching the
+ * prototype chain turns a targeting rule into a universal one.
+ */
+const FORBIDDEN_SEGMENTS = new Set(["__proto__", "prototype", "constructor"]);
 /**
  * Safely resolve a dot-notation path from an object.
  *
+ * Only own, enumerable-or-not *own* properties are traversed: `toString`,
+ * `constructor` and friends live on the prototype, and resolving them made
+ * `{ attribute: "toString", operator: "exists" }` match every context there
+ * has ever been — a targeting rule that silently targets everyone.
+ *
  * @param obj - The object to traverse.
  * @param path - Dot-separated path (e.g. "user.country").
  * @returns The value at the path, or undefined.
  */
 export function resolvePath(obj, path) {
+    if (path === "")
+        return undefined;
     const parts = path.split(".");
     let current = obj;
     for (const part of parts) {
+        if (FORBIDDEN_SEGMENTS.has(part))
+            return undefined;
         if (current === null ||
             current === undefined ||
             typeof current !== "object") {
             return undefined;
         }
+        if (!Object.hasOwn(current, part))
+            return undefined;
         current = current[part];
     }
     return current;
 }
+/** Longest pattern accepted by the `matches` operator. */
+const MAX_PATTERN_LENGTH = 512;
+/**
+ * Compiled patterns, so a rule evaluated on every request does not recompile
+ * its regular expression every time.
+ */
+const patternCache = new Map();
+/** Cap on distinct cached patterns, since flag config can change at runtime. */
+const MAX_CACHED_PATTERNS = 256;
+/**
+ * Compile a rule pattern, or return `null` when it cannot be used.
+ *
+ * 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.
+ */
+function compilePattern(pattern) {
+    if (pattern.length > MAX_PATTERN_LENGTH)
+        return null;
+    const cached = patternCache.get(pattern);
+    if (cached !== undefined)
+        return cached;
+    let compiled;
+    try {
+        compiled = new RegExp(pattern);
+    }
+    catch {
+        compiled = null;
+    }
+    if (patternCache.size >= MAX_CACHED_PATTERNS)
+        patternCache.clear();
+    patternCache.set(pattern, compiled);
+    return compiled;
+}
 /**
  * Evaluate an attribute rule against a context value.
  *
@@ -54,6 +107,8 @@ export function matchAttribute(actual, operator, expected) {
         case "in":
             return Array.isArray(expected) && expected.includes(actual);
         case "not_in":
+            // A malformed rule must not match everyone: `not_in` with a non-array
+            // expectation is unusable, so it matches nobody.
             return Array.isArray(expected) && !expected.includes(actual);
         case "greater_than":
             return (typeof actual === "number" &&
@@ -73,10 +128,13 @@ export function matchAttribute(actual, operator, expected) {
                 actual <= expected);
         case "exists":
             return actual !== undefined && actual !== null;
-        case "matches":
-            return (typeof actual === "string" &&
-                typeof expected === "string" &&
-                new RegExp(expected).test(actual));
+        case "matches": {
+            if (typeof actual !== "string" || typeof expected !== "string") {
+                return false;
+            }
+            const pattern = compilePattern(expected);
+            return pattern !== null && pattern.test(actual);
+        }
         default:
             return false;
     }

package/dist/evaluator/evaluatorRule.core.js

@@ -5,8 +5,10 @@
  *
  * @module evaluator/evaluatorRule
  */
-import { isInRollout } from "../rollout/rolloutBucketing.js";
+import { getBucket, isInRollout } from "../rollout/rolloutBucketing.js";
 import { matchAttribute, resolvePath } from "./evaluatorAttribute.js";
+/** Bucket resolution for variant assignment — 0.01% precision. */
+const VARIANT_BUCKETS = 10_000;
 /**
  * Evaluate a single feature flag rule against a context.
  *
@@ -45,25 +47,48 @@ export function evaluateRule(rule, context, flagKey) {
             return { matched, value: matched ? rule.value : undefined };
         }
         case "schedule": {
-            const now = Date.now();
             const start = new Date(rule.startAt).getTime();
             const end = new Date(rule.endAt).getTime();
+            // An unparseable date yields NaN, and every comparison against NaN is
+            // false — which happens to fail closed, but only by accident. Say so.
+            if (Number.isNaN(start) || Number.isNaN(end))
+                return { matched: false };
+            const now = Date.now();
             const matched = now >= start && now <= end;
             return { matched, value: matched ? rule.value : undefined };
         }
         case "variant": {
             const subject = context.userId ?? context.tenantId ?? context.sessionId ?? "anonymous";
-            const totalWeight = rule.variants.reduce((sum, v) => sum + v.weight, 0);
+            // Negative or non-finite weights would make the cumulative walk
+            // non-monotonic, shifting every downstream variant's band, so they are
+            // treated as zero.
+            const weighted = rule.variants.map((variant) => ({
+                key: variant.key,
+                weight: Number.isFinite(variant.weight) && variant.weight > 0
+                    ? variant.weight
+                    : 0,
+            }));
+            const totalWeight = weighted.reduce((sum, entry) => sum + entry.weight, 0);
             if (totalWeight <= 0)
                 return { matched: false };
-            const bucket = isInRollout(flagKey, subject, 100) ? 99 : 0;
+            // The real bucket for this (flag, subject) pair. This used to be
+            // `isInRollout(flagKey, subject, 100) ? 99 : 0`, which is always 99 —
+            // so every subject landed in the last variant and the weights did
+            // nothing at all.
+            const bucket = getBucket(flagKey, subject, VARIANT_BUCKETS);
             let cumulative = 0;
-            for (const variant of rule.variants) {
-                cumulative += (variant.weight / totalWeight) * 100;
+            for (const entry of weighted) {
+                cumulative += (entry.weight / totalWeight) * VARIANT_BUCKETS;
                 if (bucket < cumulative) {
-                    return { matched: true, value: variant.key, variant: variant.key };
+                    return { matched: true, value: entry.key, variant: entry.key };
                 }
             }
+            // Floating-point rounding can leave the last bucket just past the
+            // cumulative total; the final weighted variant owns it.
+            const positive = weighted.filter((entry) => entry.weight > 0);
+            const last = positive[positive.length - 1];
+            if (last)
+                return { matched: true, value: last.key, variant: last.key };
             return { matched: false };
         }
         default:

package/dist/featureFlagTypes/featureFlagProvider.d.ts

@@ -21,4 +21,14 @@ export interface FeatureFlagProvider {
     /** Optional: subscribe to flag changes. */
     subscribe?(listener: FeatureFlagChangeListener): Unsubscribe;
 }
+/**
+ * A provider that always implements {@link FeatureFlagProvider.refresh}.
+ *
+ * The built-in providers all do, but declaring them as `FeatureFlagProvider`
+ * hid it behind an optional method, so a caller could not invoke `refresh()`
+ * without a non-null assertion.
+ */
+export interface RefreshableFeatureFlagProvider extends FeatureFlagProvider {
+    refresh(): Promise<void>;
+}
 //# sourceMappingURL=featureFlagProvider.d.ts.map

package/dist/featureFlagTypes/index.d.ts

@@ -5,5 +5,5 @@ export type { FeatureFlagValue, FeatureFlagState, FeatureFlagVisibility, Feature
 export type { FeatureFlagContext } from "./featureFlagContext.js";
 export type { FeatureFlagMetadata, FeatureFlag, } from "./featureFlag.interface.js";
 export type { FeatureFlagEvaluationReason, FeatureFlagEvaluation, } from "./featureFlagEvaluation.js";
-export type { FeatureFlagProvider, FeatureFlagChangeListener, Unsubscribe, } from "./featureFlagProvider.js";
+export type { FeatureFlagProvider, RefreshableFeatureFlagProvider, FeatureFlagChangeListener, Unsubscribe, } from "./featureFlagProvider.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -18,14 +18,25 @@ export interface FeatureFlagsOptions {
     readonly defaultContext?: FeatureFlagContext;
     /** Whether to throw on missing flags (default: false, returns default value). */
     readonly throwOnMissing?: boolean;
+    /**
+     * Reports a provider failure that evaluation contained.
+     *
+     * A store that cannot be reached must not decide a flag, and it must not
+     * take the caller down either: the evaluation falls back to the flag's
+     * declared default (or `not_found` when nothing is known about it) and the
+     * failure surfaces here.
+     */
+    readonly onError?: (error: unknown, source: string) => void;
+    /**
+     * Rethrow provider failures instead of containing them. Default: `false`.
+     *
+     * Set it when an unreachable store should be a hard failure the caller
+     * handles itself.
+     */
+    readonly throwOnProviderError?: boolean;
 }
-/**
- * Create a FeatureFlags instance.
- *
- * @param options - Configuration options.
- * @returns A FeatureFlags API object.
- */
-export declare function createFeatureFlags(options: FeatureFlagsOptions): {
+/** The public FeatureFlags API. */
+export interface FeatureFlags {
     isEnabled(key: string, context?: FeatureFlagContext): Promise<boolean>;
     get<T extends FeatureFlagValue = FeatureFlagValue>(key: string, context?: FeatureFlagContext): Promise<T | undefined>;
     getBoolean(key: string, defaultValue: boolean, context?: FeatureFlagContext): Promise<boolean>;
@@ -33,5 +44,14 @@ export declare function createFeatureFlags(options: FeatureFlagsOptions): {
     snapshot(context?: FeatureFlagContext): Promise<ReadonlyMap<string, FeatureFlagEvaluation>>;
     refresh(): Promise<void>;
     getAll(): Promise<readonly FeatureFlag[]>;
-};
+    /** Stop listening for provider changes. */
+    close(): void;
+}
+/**
+ * Create a FeatureFlags instance.
+ *
+ * @param options - Configuration options.
+ * @returns A FeatureFlags API object.
+ */
+export declare function createFeatureFlags(options: FeatureFlagsOptions): FeatureFlags;
 //# sourceMappingURL=featureFlags.core.d.ts.map