@zudojs/feature-flags 0.1.0 → 1.1.0

package/dist/featureFlags/featureFlags.core.js

@@ -7,7 +7,7 @@
  */
 import { createFeatureFlagRegistry } from "../registry/registry.core.js";
 import { evaluateFlag } from "../evaluator/evaluator.core.js";
-import { FeatureFlagNotFoundError } from "../featureFlagErrors/featureFlagError.types.js";
+import { FeatureFlagNotFoundError, FeatureFlagProviderError, } from "../featureFlagErrors/featureFlagError.types.js";
 import { resolveDependencies, mergeContext } from "./featureFlags.resolve.js";
 /**
  * Create a FeatureFlags instance.
@@ -16,45 +16,103 @@ import { resolveDependencies, mergeContext } from "./featureFlags.resolve.js";
  * @returns A FeatureFlags API object.
  */
 export function createFeatureFlags(options) {
-    const { provider, defaultContext = {}, throwOnMissing = false } = options;
+    const { provider, defaultContext = {}, throwOnMissing = false, onError, throwOnProviderError = false, } = options;
     let registry = createFeatureFlagRegistry();
+    let loaded = false;
+    /**
+     * Report a provider failure, or rethrow it when the caller asked to own it.
+     *
+     * @returns `false` when the failure was contained.
+     */
+    function handleProviderError(error, source) {
+        if (throwOnProviderError)
+            throw error;
+        onError?.(error instanceof Error
+            ? error
+            : new FeatureFlagProviderError(`Provider ${source} failed.`, {
+                cause: error,
+            }), source);
+        return false;
+    }
     async function load() {
-        const flags = await provider.getAll();
-        registry = createFeatureFlagRegistry(flags);
+        try {
+            const flags = await provider.getAll();
+            registry = createFeatureFlagRegistry(flags);
+            loaded = true;
+            return true;
+        }
+        catch (error) {
+            return handleProviderError(error, "FeatureFlagProvider.getAll");
+        }
     }
     async function ensureLoaded() {
-        if (registry.size === 0)
-            await load();
+        // Keyed on whether a load has ever succeeded, not on `registry.size`: a
+        // provider that legitimately holds no flags used to be re-queried on
+        // every single evaluation.
+        if (loaded)
+            return true;
+        return load();
     }
     async function resolveFlag(key) {
-        let flag = registry.get(key);
-        if (!flag) {
-            flag = await provider.get(key);
+        const known = registry.get(key);
+        if (known)
+            return { flag: known, reachable: true };
+        try {
+            const flag = await provider.get(key);
             if (flag)
                 registry.set(flag);
+            return { flag, reachable: true };
+        }
+        catch (error) {
+            handleProviderError(error, "FeatureFlagProvider.get");
+            // 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 };
         }
-        return flag;
     }
-    return {
+    // A provider that can announce changes is asked to: without this, a flag
+    // flipped at the source never reached an already-loaded instance until
+    // somebody called refresh() by hand.
+    let unsubscribe = provider.subscribe?.((flags) => {
+        registry = createFeatureFlagRegistry(flags);
+        loaded = true;
+    });
+    const api = {
         async isEnabled(key, context) {
-            const result = await this.evaluate(key, context);
-            return result.value;
+            const result = await api.evaluate(key, context);
+            // Strictly `true`. Returning the raw value meant a flag holding a
+            // string or a number — "off", 0.5, a config object — came back truthy
+            // from a method whose whole contract is a boolean.
+            return result.value === true;
         },
         async get(key, context) {
-            const result = await this.evaluate(key, context);
+            const result = await api.evaluate(key, context);
             return result.value;
         },
         async getBoolean(key, defaultValue, context) {
-            const result = await this.evaluate(key, context);
-            if (result.reason === "not_found")
+            const result = await api.evaluate(key, context);
+            if (result.reason === "not_found" || result.reason === "error") {
                 return defaultValue;
-            return result.value;
+            }
+            return typeof result.value === "boolean" ? result.value : defaultValue;
         },
         async evaluate(key, context) {
-            await ensureLoaded();
+            const available = await ensureLoaded();
             const mergedCtx = mergeContext(defaultContext, context);
-            const flag = await resolveFlag(key);
+            const { flag, reachable } = await resolveFlag(key);
             if (!flag) {
+                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 {
+                        key,
+                        value: undefined,
+                        reason: "error",
+                        defaulted: true,
+                    };
+                }
                 if (throwOnMissing)
                     throw new FeatureFlagNotFoundError(key);
                 return {
@@ -64,17 +122,10 @@ export function createFeatureFlags(options) {
                     defaulted: true,
                 };
             }
-            if (flag.dependencies && flag.dependencies.length > 0) {
-                if (!resolveDependencies(key, registry)) {
-                    return {
-                        key,
-                        value: flag.defaultValue,
-                        reason: "dependency_disabled",
-                        defaulted: true,
-                    };
-                }
-            }
-            return evaluateFlag(flag, mergedCtx);
+            const dependenciesSatisfied = !flag.dependencies ||
+                flag.dependencies.length === 0 ||
+                resolveDependencies(key, registry);
+            return evaluateFlag(flag, mergedCtx, { dependenciesSatisfied });
         },
         async snapshot(context) {
             await ensureLoaded();
@@ -82,20 +133,36 @@ export function createFeatureFlags(options) {
             const flags = registry.getAll();
             const results = new Map();
             for (const flag of flags) {
-                if (flag.visibility === "client") {
-                    results.set(flag.key, evaluateFlag(flag, mergedCtx));
-                }
+                // Only flags explicitly marked client-visible. A flag that declares
+                // no visibility stays server-side: a snapshot is shipped to a
+                // browser, so the safe default is to withhold.
+                if (flag.visibility !== "client")
+                    continue;
+                const dependenciesSatisfied = !flag.dependencies ||
+                    flag.dependencies.length === 0 ||
+                    resolveDependencies(flag.key, registry);
+                results.set(flag.key, evaluateFlag(flag, mergedCtx, { dependenciesSatisfied }));
             }
             return results;
         },
         async refresh() {
-            await provider.refresh?.();
+            try {
+                await provider.refresh?.();
+            }
+            catch (error) {
+                handleProviderError(error, "FeatureFlagProvider.refresh");
+            }
             await load();
         },
         async getAll() {
             await ensureLoaded();
             return registry.getAll();
         },
+        close() {
+            unsubscribe?.();
+            unsubscribe = undefined;
+        },
     };
+    return api;
 }
 //# sourceMappingURL=featureFlags.core.js.map

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

@@ -10,10 +10,11 @@ import type { FeatureFlagRegistry } from "../registry/registry.core.js";
  *
  * @param key - The flag key to resolve.
  * @param registry - The flag registry.
- * @param visited - Set of already-visited keys (for cycle detection).
- * @returns True if all dependencies are enabled.
+ * @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.
  */
-export declare function resolveDependencies(key: string, registry: FeatureFlagRegistry, visited?: Set<string>): boolean;
+export declare function resolveDependencies(key: string, registry: FeatureFlagRegistry, chain?: Set<string>, satisfied?: Set<string>): boolean;
 /**
  * Merge default context with provided context.
  */

package/dist/featureFlags/featureFlags.resolve.js

@@ -8,23 +8,40 @@
  *
  * @param key - The flag key to resolve.
  * @param registry - The flag registry.
- * @param visited - Set of already-visited keys (for cycle detection).
- * @returns True if all dependencies are enabled.
+ * @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.
  */
-export function resolveDependencies(key, registry, visited = new Set()) {
-    if (visited.has(key))
+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.
+    if (satisfied.has(key))
+        return true;
+    if (chain.has(key))
         return false;
-    visited.add(key);
+    chain.add(key);
     const flag = registry.get(key);
-    if (!flag || !flag.enabled)
-        return false;
-    if (!flag.dependencies || flag.dependencies.length === 0)
-        return true;
-    for (const dep of flag.dependencies) {
-        if (!resolveDependencies(dep, registry, visited))
+    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;
+        }
+        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 true;
 }
 /**
  * Merge default context with provided context.

package/dist/index.d.ts

@@ -12,6 +12,7 @@ export { FeatureFlagNotFoundError, FeatureFlagProviderError, FeatureFlagEvaluati
 export { hashString } from "./rollout/rolloutHashing.js";
 export { getBucket, isInRollout } from "./rollout/rolloutBucketing.js";
 export { createMemoryProvider } from "./provider/providerMemory.core.js";
+export type { MemoryFeatureFlagProvider } from "./provider/providerMemory.core.js";
 export { createEnvironmentProvider } from "./provider/providerEnvironment.core.js";
 export type { EnvironmentProviderOptions } from "./provider/providerEnvironment.core.js";
 export { createCompositeProvider } from "./provider/providerComposite.core.js";
@@ -21,9 +22,11 @@ export { resolvePath, matchAttribute } from "./evaluator/evaluatorAttribute.js";
 export { evaluateRule } from "./evaluator/evaluatorRule.core.js";
 export type { RuleEvaluationResult } from "./evaluator/evaluatorRule.core.js";
 export { evaluateFlag } from "./evaluator/evaluator.core.js";
+export type { EvaluateFlagOptions } from "./evaluator/evaluator.core.js";
 export { createFeatureFlagRegistry } from "./registry/registry.core.js";
 export type { FeatureFlagRegistry } from "./registry/registry.core.js";
 export { createFeatureFlags } from "./featureFlags/featureFlags.core.js";
-export type { FeatureFlagsOptions } from "./featureFlags/featureFlags.core.js";
+export type { FeatureFlags, FeatureFlagsOptions, } from "./featureFlags/featureFlags.core.js";
+export { resolveDependencies, mergeContext, } from "./featureFlags/featureFlags.resolve.js";
 export { isPlainObject, valuesEqual } from "./utils/utils.helper.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -24,6 +24,7 @@ export { evaluateFlag } from "./evaluator/evaluator.core.js";
 export { createFeatureFlagRegistry } from "./registry/registry.core.js";
 // ─── FeatureFlags ─────────────────────────────────────────────────────────
 export { createFeatureFlags } from "./featureFlags/featureFlags.core.js";
+export { resolveDependencies, mergeContext, } from "./featureFlags/featureFlags.resolve.js";
 // ─── Utils ────────────────────────────────────────────────────────────────
 export { isPlainObject, valuesEqual } from "./utils/utils.helper.js";
 //# sourceMappingURL=index.js.map

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

@@ -5,7 +5,7 @@
  *
  * @module provider/providerCached
  */
-import type { FeatureFlagProvider } from "../featureFlagTypes/featureFlagProvider.js";
+import type { FeatureFlagProvider, RefreshableFeatureFlagProvider } from "../featureFlagTypes/featureFlagProvider.js";
 /** Options for the cached provider. */
 export interface CachedProviderOptions {
     /** Time-to-live in milliseconds (default: 30,000). */
@@ -16,7 +16,7 @@ export interface CachedProviderOptions {
  *
  * @param inner - The upstream provider to cache.
  * @param options - Caching options.
- * @returns A FeatureFlagProvider with in-memory TTL caching.
+ * @returns A provider with in-memory TTL caching.
  */
-export declare function createCachedProvider(inner: FeatureFlagProvider, options?: CachedProviderOptions): FeatureFlagProvider;
+export declare function createCachedProvider(inner: FeatureFlagProvider, options?: CachedProviderOptions): RefreshableFeatureFlagProvider;
 //# sourceMappingURL=providerCached.core.d.ts.map

package/dist/provider/providerCached.core.js

@@ -10,7 +10,7 @@
  *
  * @param inner - The upstream provider to cache.
  * @param options - Caching options.
- * @returns A FeatureFlagProvider with in-memory TTL caching.
+ * @returns A provider with in-memory TTL caching.
  */
 export function createCachedProvider(inner, options = {}) {
     const ttl = options.ttl ?? 30_000;
@@ -19,7 +19,27 @@ export function createCachedProvider(inner, options = {}) {
     function isExpired(entry) {
         return Date.now() > entry.expiresAt;
     }
+    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))
@@ -36,8 +56,7 @@ export function createCachedProvider(inner, options = {}) {
             return flags;
         },
         async refresh() {
-            flagCache.clear();
-            listCache = undefined;
+            clear();
             await inner.refresh?.();
         },
     };

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

@@ -5,7 +5,7 @@
  *
  * @module provider/providerComposite
  */
-import type { FeatureFlagProvider } from "../featureFlagTypes/featureFlagProvider.js";
+import type { FeatureFlagProvider, RefreshableFeatureFlagProvider } from "../featureFlagTypes/featureFlagProvider.js";
 /**
  * Create a composite provider that queries providers in order.
  *
@@ -15,5 +15,5 @@ import type { FeatureFlagProvider } from "../featureFlagTypes/featureFlagProvide
  * @param providers - Providers to chain, in priority order.
  * @returns A composite FeatureFlagProvider.
  */
-export declare function createCompositeProvider(providers: readonly FeatureFlagProvider[]): FeatureFlagProvider;
+export declare function createCompositeProvider(providers: readonly FeatureFlagProvider[]): RefreshableFeatureFlagProvider;
 //# sourceMappingURL=providerComposite.core.d.ts.map

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.d.ts

@@ -7,7 +7,7 @@
  *
  * @module provider/providerEnvironment
  */
-import type { FeatureFlagProvider } from "../featureFlagTypes/featureFlagProvider.js";
+import type { RefreshableFeatureFlagProvider } from "../featureFlagTypes/featureFlagProvider.js";
 /** Options for the environment provider. */
 export interface EnvironmentProviderOptions {
     /** Prefix for environment variable names (default: "FEATURE_"). */
@@ -19,7 +19,7 @@ export interface EnvironmentProviderOptions {
  * Create an environment-variable feature flag provider.
  *
  * @param options - Configuration options.
- * @returns A FeatureFlagProvider that reads from environment variables.
+ * @returns A provider that reads from environment variables.
  */
-export declare function createEnvironmentProvider(options?: EnvironmentProviderOptions): FeatureFlagProvider;
+export declare function createEnvironmentProvider(options?: EnvironmentProviderOptions): RefreshableFeatureFlagProvider;
 //# sourceMappingURL=providerEnvironment.core.d.ts.map

package/dist/provider/providerEnvironment.core.js

@@ -15,16 +15,21 @@ 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;
 }
 /**
  * Create an environment-variable feature flag provider.
  *
  * @param options - Configuration options.
- * @returns A FeatureFlagProvider that reads from environment variables.
+ * @returns A provider that reads from environment variables.
  */
 export function createEnvironmentProvider(options = {}) {
     const prefix = options.prefix ?? "FEATURE_";

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

@@ -6,12 +6,28 @@
  * @module provider/providerMemory
  */
 import type { FeatureFlag } from "../featureFlagTypes/featureFlag.interface.js";
-import type { FeatureFlagProvider } from "../featureFlagTypes/featureFlagProvider.js";
+import type { FeatureFlagChangeListener, FeatureFlagProvider, Unsubscribe } from "../featureFlagTypes/featureFlagProvider.js";
+/**
+ * An in-memory provider, with the mutation methods it actually has.
+ *
+ * `createMemoryProvider` used to return `FeatureFlagProvider` through a cast,
+ * so `set` and `delete` existed at runtime and were invisible to the type
+ * system — callers had to cast to reach them.
+ */
+export interface MemoryFeatureFlagProvider extends FeatureFlagProvider {
+    /** Add or update a flag at runtime, notifying subscribers. */
+    set(flag: FeatureFlag): void;
+    /** Remove a flag by key, notifying subscribers. Returns whether it existed. */
+    delete(key: string): boolean;
+    /** Replace every flag at once, notifying subscribers. */
+    setAll(flags: readonly FeatureFlag[]): void;
+    subscribe(listener: FeatureFlagChangeListener): Unsubscribe;
+}
 /**
  * Create an in-memory feature flag provider.
  *
  * @param flags - Initial flag definitions.
  * @returns A FeatureFlagProvider backed by a Map.
  */
-export declare function createMemoryProvider(flags?: readonly FeatureFlag[]): FeatureFlagProvider;
+export declare function createMemoryProvider(flags?: readonly FeatureFlag[]): MemoryFeatureFlagProvider;
 //# sourceMappingURL=providerMemory.core.d.ts.map

package/dist/provider/providerMemory.core.js

@@ -13,23 +13,57 @@
  */
 export function createMemoryProvider(flags = []) {
     const store = new Map();
+    const listeners = new Set();
     for (const flag of flags) {
         store.set(flag.key, Object.freeze({ ...flag }));
     }
+    function snapshot() {
+        return [...store.values()];
+    }
+    /** Announce a change so an already-loaded consumer picks it up. */
+    function notify() {
+        if (listeners.size === 0)
+            return;
+        const current = snapshot();
+        for (const listener of listeners) {
+            // A broken listener must not stop the others, or the mutation itself.
+            try {
+                listener(current);
+            }
+            catch {
+                /* listener failures are the listener's problem */
+            }
+        }
+    }
     return {
         async get(key) {
             return store.get(key);
         },
         async getAll() {
-            return [...store.values()];
+            return snapshot();
         },
-        /** Add or update a flag at runtime. */
         set(flag) {
             store.set(flag.key, Object.freeze({ ...flag }));
+            notify();
         },
-        /** Remove a flag by key. */
         delete(key) {
-            return store.delete(key);
+            const existed = store.delete(key);
+            if (existed)
+                notify();
+            return existed;
+        },
+        setAll(next) {
+            store.clear();
+            for (const flag of next) {
+                store.set(flag.key, Object.freeze({ ...flag }));
+            }
+            notify();
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
         },
     };
 }