@zudojs/feature-flags 1.0.0 → 1.1.0

package/README.md

@@ -60,6 +60,9 @@ 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.
+
 ## Rules
 
 | Type         | Matches when                                    |
@@ -130,7 +133,13 @@ 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`.
+
+`createEnvironmentProvider` parses `true`/`false` and numbers; anything else,
+including an empty `FEATURE_X=`, stays a string.
 
 ## Change propagation
 
@@ -151,6 +160,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,

package/dist/featureFlags/featureFlags.core.js

@@ -56,16 +56,20 @@ export function createFeatureFlags(options) {
     async function resolveFlag(key) {
         const known = registry.get(key);
         if (known)
-            return known;
+            return { flag: known, reachable: true };
         try {
             const flag = await provider.get(key);
             if (flag)
                 registry.set(flag);
-            return flag;
+            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
@@ -97,9 +101,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 {

package/dist/provider/providerCached.core.js

@@ -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.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/feature-flags",
-  "version": "1.0.0",
+  "version": "1.1.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,17 @@
     }
   },
   "dependencies": {
-    "@zudojs/errors": "1.0.0"
+    "@zudojs/errors": "1.0.1"
   },
   "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",