@tehw0lf/yaft 0.0.16 → 0.0.18

package/README.md

@@ -129,6 +129,29 @@ rules can be applied directly to a feature without going through a provider.
 A missing feature is off. Unset, `null` or unparseable dates are ignored rather
 than treated as an error, and never throw.
 
+### API providers and a failing backend
+
+`ApiServiceFeatureProvider` and `ApiServiceBooleanProvider` keep their data
+when a refresh fails — and, **since 0.0.18**, also when `/features` answers
+`200` with something that is not a toggle group (`null`, an array, a proxy's
+error page). Before, that replaced the data with nothing and switched every
+feature off. A failed fetch is now also retried on the next
+`getCollectionHash`; before, one failure stopped refreshing until the backend
+changed again. `normaliseGroup` is exported for providers of your own.
+
+### Boolean shape
+
+The boolean providers hold `{ "myToggle": true }` and have no time logic. Only
+the JSON boolean `true` is on. A JSON `false` is kept in the data and reads as
+off. Any value that is not a boolean -- `"true"`, `"false"`, `1`, `null` -- is
+dropped when the data loads, so its key is missing from the data and reads as
+off. `normaliseBooleans` is exported and applies the same rule.
+
+**Changed in 0.0.17.** Before, `isEnabled` returned whatever was stored, and a
+caller testing it with `if` turned the string `"false"` **on**, because a
+non-empty string is truthy. A configuration that relied on string or number
+values has to switch to real booleans.
+
 ### Date format
 
 Dates must be **RFC 3339 with an offset** (`2026-09-18T15:00:00Z` or
@@ -166,8 +189,8 @@ is tested against that suite rather than only against its own expectations.
 The version is pinned in `conformance.lock`:
 
 ```
-version=v1.1.0
-sha256=d83ff1c960ad29830c00b57727591da628f4323b777faea245f603565d1c9ae9
+version=v2.0.0
+sha256=a10c1342e9ef346f998c0a819d90ae7f4984b53c933ed555eefab09419e993aa
 ```
 
 `npm test` fetches that release, verifies the checksum and unpacks it before

package/examples/ApiServiceBooleanProvider.d.ts

@@ -7,5 +7,7 @@ export declare class ApiServiceBooleanProvider implements FeatureProvider<boolea
     constructor(apiUrl: string, baseUUID: string);
     getCollectionHash(configPathOrUrl: string): Promise<void>;
     getConfig(configPathOrUrl: string): Promise<void>;
+    /** Loads the group and reports whether it did; on failure the data stays. */
+    private loadGroup;
     isEnabled(key: string): boolean;
 }

package/examples/ApiServiceBooleanProvider.js

@@ -20,9 +20,9 @@ class ApiServiceBooleanProvider {
         try {
             const response = await axios_1.default.get(configPathOrUrl);
             const newHash = response.data.collectionHash || response.data.value;
-            if (this.collectionHash !== newHash) {
+            // Recorded only once the group has loaded, so a failed fetch is retried.
+            if (this.collectionHash !== newHash && (await this.loadGroup(`${this.apiUrl}/features/${this.baseUUID}`))) {
                 this.collectionHash = newHash;
-                await this.getConfig(`${this.apiUrl}/features/${this.baseUUID}`);
             }
         }
         catch (error) {
@@ -30,6 +30,10 @@ class ApiServiceBooleanProvider {
         }
     }
     async getConfig(configPathOrUrl) {
+        await this.loadGroup(configPathOrUrl);
+    }
+    /** Loads the group and reports whether it did; on failure the data stays. */
+    async loadGroup(configPathOrUrl) {
         try {
             const response = await axios_1.default.get(configPathOrUrl);
             // A keyed boolean object is already in this provider's shape and is
@@ -37,8 +41,8 @@ class ApiServiceBooleanProvider {
             // through the core normaliser, so the two providers cannot disagree
             // about what a response means.
             if (isKeyedBooleans(response.data)) {
-                this.data = response.data;
-                return;
+                this.data = (0, mapping_1.normaliseBooleans)(response.data);
+                return true;
             }
             // Only the value matters here. The boolean shape has no time logic by
             // design (R21), so a feature collapses to whether its value is exactly
@@ -48,35 +52,44 @@ class ApiServiceBooleanProvider {
             // schedules toggles: the window is then enforced only by the backend's
             // cron job, which lags by up to a minute, instead of being evaluated
             // locally. Use ApiServiceFeatureProvider when the toggles carry dates.
-            const features = (0, mapping_1.normaliseCollection)(response.data);
+            const features = (0, mapping_1.normaliseGroup)(response.data);
+            if (features === undefined) {
+                console.error("Ignoring a response that is not a toggle group:", response.data);
+                return false;
+            }
             this.data = {};
             for (const [key, feature] of Object.entries(features)) {
                 this.data[key] = feature.value === 'true';
             }
+            return true;
         }
         catch (error) {
             console.error("Failed to fetch feature toggle from API:", error);
+            return false;
         }
     }
     isEnabled(key) {
-        const feature = this.data[key];
-        if (feature === undefined || feature === null)
-            return false;
-        return feature;
+        return this.data[key] === true;
     }
 }
 exports.ApiServiceBooleanProvider = ApiServiceBooleanProvider;
 /**
- * True when the payload is already `{ "myToggle": true }`.
+ * True when the payload is in the boolean shape, `{ "myToggle": true }`.
  *
  * Distinguishing this from a feature-shaped response matters: running a keyed
  * boolean object through the feature normaliser would look for a `key` field,
  * find none and discard every entry.
+ *
+ * One boolean value is enough. A mixed payload such as
+ * `{ "a": true, "b": "x" }` is still the boolean shape; normaliseBooleans then
+ * drops `b` and keeps `a` (R29), exactly as the local provider does. Requiring
+ * every value to be boolean sent it to the feature normaliser instead, which
+ * lost `a` as well. Feature responses never carry a boolean -- `value` is a
+ * string -- so they are not caught by this.
  */
 function isKeyedBooleans(data) {
     if (data === null || typeof data !== 'object' || Array.isArray(data)) {
         return false;
     }
-    const values = Object.values(data);
-    return values.length > 0 && values.every((v) => typeof v === 'boolean');
+    return Object.values(data).some((v) => typeof v === 'boolean');
 }

package/examples/ApiServiceFeatureProvider.d.ts

@@ -13,5 +13,7 @@ export declare class ApiServiceFeatureProvider implements FeatureProvider<Featur
     constructor(apiUrl: string, baseUUID: string, clock?: Clock);
     getCollectionHash(configPathOrUrl: string): Promise<void>;
     getConfig(configPathOrUrl: string): Promise<void>;
+    /** Loads the group and reports whether it did; on failure the data stays. */
+    private loadGroup;
     isEnabled(key: string): boolean;
 }

package/examples/ApiServiceFeatureProvider.js

@@ -27,9 +27,11 @@ class ApiServiceFeatureProvider {
         try {
             const response = await axios_1.default.get(configPathOrUrl);
             const newHash = response.data.collectionHash || response.data.value;
-            if (this.collectionHash !== newHash) {
+            // The hash is recorded only once the group has loaded. Recording it
+            // first meant one failed fetch stopped every later refresh until the
+            // backend changed again.
+            if (this.collectionHash !== newHash && (await this.loadGroup(`${this.apiUrl}/features/${this.baseUUID}`))) {
                 this.collectionHash = newHash;
-                await this.getConfig(`${this.apiUrl}/features/${this.baseUUID}`);
             }
         }
         catch (error) {
@@ -37,14 +39,25 @@ class ApiServiceFeatureProvider {
         }
     }
     async getConfig(configPathOrUrl) {
+        await this.loadGroup(configPathOrUrl);
+    }
+    /** Loads the group and reports whether it did; on failure the data stays. */
+    async loadGroup(configPathOrUrl) {
         try {
             const response = await axios_1.default.get(configPathOrUrl);
             // The mapping rules live in the core, next to the evaluation rules,
             // rather than being reimplemented per provider.
-            this.data = (0, mapping_1.normaliseCollection)(response.data);
+            const group = (0, mapping_1.normaliseGroup)(response.data);
+            if (group === undefined) {
+                console.error("Ignoring a response that is not a toggle group:", response.data);
+                return false;
+            }
+            this.data = group;
+            return true;
         }
         catch (error) {
             console.error("Failed to fetch feature toggle from API:", error);
+            return false;
         }
     }
     isEnabled(key) {

package/examples/LocalStorageBooleanProvider.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LocalStorageBooleanProvider = void 0;
+const mapping_1 = require("../mapping");
 class LocalStorageBooleanProvider {
     data = {};
     constructor(configPath) {
@@ -8,8 +9,7 @@ class LocalStorageBooleanProvider {
     }
     getConfig(configPathOrUrl) {
         try {
-            const configData = require(configPathOrUrl);
-            this.data = configData;
+            this.data = (0, mapping_1.normaliseBooleans)(require(configPathOrUrl));
         }
         catch (error) {
             console.error("Failed to load configuration from local file:", error);
@@ -17,10 +17,7 @@ class LocalStorageBooleanProvider {
         }
     }
     isEnabled(key) {
-        const feature = this.data[key];
-        if (feature === undefined || feature === null)
-            return false;
-        return feature;
+        return this.data[key] === true;
     }
 }
 exports.LocalStorageBooleanProvider = LocalStorageBooleanProvider;

package/index.d.ts

@@ -1,3 +1,3 @@
 export { Feature, FeatureToggle, FeatureToggleBase, FeatureProvider, } from "./FeatureToggle";
 export { Clock, evaluate, parseTimestamp, systemClock } from "./evaluate";
-export { normaliseCollection, normaliseFeature } from "./mapping";
+export { normaliseBooleans, normaliseCollection, normaliseFeature, normaliseGroup } from "./mapping";

package/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.normaliseFeature = exports.normaliseCollection = exports.systemClock = exports.parseTimestamp = exports.evaluate = exports.FeatureToggleBase = exports.FeatureToggle = void 0;
+exports.normaliseGroup = exports.normaliseFeature = exports.normaliseCollection = exports.normaliseBooleans = exports.systemClock = exports.parseTimestamp = exports.evaluate = exports.FeatureToggleBase = exports.FeatureToggle = void 0;
 var FeatureToggle_1 = require("./FeatureToggle");
 Object.defineProperty(exports, "FeatureToggle", { enumerable: true, get: function () { return FeatureToggle_1.FeatureToggle; } });
 Object.defineProperty(exports, "FeatureToggleBase", { enumerable: true, get: function () { return FeatureToggle_1.FeatureToggleBase; } });
@@ -9,5 +9,7 @@ Object.defineProperty(exports, "evaluate", { enumerable: true, get: function ()
 Object.defineProperty(exports, "parseTimestamp", { enumerable: true, get: function () { return evaluate_1.parseTimestamp; } });
 Object.defineProperty(exports, "systemClock", { enumerable: true, get: function () { return evaluate_1.systemClock; } });
 var mapping_1 = require("./mapping");
+Object.defineProperty(exports, "normaliseBooleans", { enumerable: true, get: function () { return mapping_1.normaliseBooleans; } });
 Object.defineProperty(exports, "normaliseCollection", { enumerable: true, get: function () { return mapping_1.normaliseCollection; } });
 Object.defineProperty(exports, "normaliseFeature", { enumerable: true, get: function () { return mapping_1.normaliseFeature; } });
+Object.defineProperty(exports, "normaliseGroup", { enumerable: true, get: function () { return mapping_1.normaliseGroup; } });

package/mapping.d.ts

@@ -24,4 +24,23 @@ export declare function normaliseFeature(raw: RawFeature): Feature;
  * where `isEnabled("")` could reach it.
  */
 export declare function normaliseCollection(response: unknown): Record<string, Feature>;
+/**
+ * Normalises a /features response, but only if it is recognisably a toggle
+ * group: a collection envelope -- an empty one is a valid empty group -- or a
+ * single toggle. Returns `undefined` for anything else.
+ *
+ * `normaliseCollection` turns null, an array, a proxy's error object or a
+ * collection whose entries are all unusable into `{}`. A provider storing that
+ * would switch every feature off without an error; this is what it should
+ * check instead. Unusable entries next to good ones are still skipped (R25).
+ */
+export declare function normaliseGroup(response: unknown): Record<string, Feature> | undefined;
+/**
+ * Normalises a boolean-shape payload, `{ "myToggle": true }`.
+ *
+ * Only real booleans are kept (R29). Anything else is dropped, so its key
+ * reads as missing and therefore off. Keeping it and testing its truthiness
+ * would turn `"false"` on, since a non-empty string is truthy.
+ */
+export declare function normaliseBooleans(response: unknown): Record<string, boolean>;
 export {};

package/mapping.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.normaliseFeature = normaliseFeature;
 exports.normaliseCollection = normaliseCollection;
+exports.normaliseGroup = normaliseGroup;
+exports.normaliseBooleans = normaliseBooleans;
 /**
  * Reads a field by presence, not by truthiness.
  *
@@ -77,3 +79,46 @@ function normaliseCollection(response) {
     }
     return data;
 }
+/**
+ * Normalises a /features response, but only if it is recognisably a toggle
+ * group: a collection envelope -- an empty one is a valid empty group -- or a
+ * single toggle. Returns `undefined` for anything else.
+ *
+ * `normaliseCollection` turns null, an array, a proxy's error object or a
+ * collection whose entries are all unusable into `{}`. A provider storing that
+ * would switch every feature off without an error; this is what it should
+ * check instead. Unusable entries next to good ones are still skipped (R25).
+ */
+function normaliseGroup(response) {
+    if (response === null || typeof response !== 'object' || Array.isArray(response)) {
+        return undefined;
+    }
+    const data = normaliseCollection(response);
+    if (Object.keys(data).length > 0)
+        return data;
+    const body = response;
+    const collection = Array.isArray(body['toggles'])
+        ? body['toggles']
+        : Array.isArray(body['value'])
+            ? body['value']
+            : undefined;
+    return collection !== undefined && collection.length === 0 ? data : undefined;
+}
+/**
+ * Normalises a boolean-shape payload, `{ "myToggle": true }`.
+ *
+ * Only real booleans are kept (R29). Anything else is dropped, so its key
+ * reads as missing and therefore off. Keeping it and testing its truthiness
+ * would turn `"false"` on, since a non-empty string is truthy.
+ */
+function normaliseBooleans(response) {
+    if (response === null || typeof response !== 'object' || Array.isArray(response)) {
+        return {};
+    }
+    const data = {};
+    for (const [key, value] of Object.entries(response)) {
+        if (typeof value === 'boolean')
+            data[key] = value;
+    }
+    return data;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tehw0lf/yaft",
-  "version": "0.0.16",
+  "version": "0.0.18",
   "description": "YaFT - Feature Toggles using Go&PostgreSQL or any source!",
   "type": "commonjs",
   "main": "index.js",