@zudojs/feature-flags 1.3.0 → 1.4.1

package/README.md

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

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

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

package/dist/evaluator/evaluator.core.js

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

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

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

package/dist/evaluator/evaluatorGate.core.js

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

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

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

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

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

package/dist/provider/providerEnvironment.core.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/feature-flags",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "description": "Feature flag system with deterministic rollouts, rule engine, providers, variants, snapshots, and evaluation context.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -11,12 +11,12 @@
     }
   },
   "dependencies": {
-    "@zudojs/errors": "1.2.0",
-    "@zudojs/types": "1.1.1"
+    "@zudojs/errors": "1.3.1",
+    "@zudojs/types": "1.2.0"
   },
   "devDependencies": {
     "typescript": "7.0.2",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.1"
   },
   "license": "MIT",
   "author": {
@@ -43,7 +43,7 @@
     "rollout",
     "a-b-testing"
   ],
-  "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "homepage": "https://zudojs.oyinlola.site/docs/packages-feature-flags",
   "bugs": {
     "url": "https://github.com/oyinlola-tech/zudo/issues"
   },