@tehw0lf/yaft 0.0.15 → 0.0.16

package/FeatureToggle.d.ts

@@ -0,0 +1,20 @@
+import "reflect-metadata";
+export type Feature = {
+    key: string;
+    value: string;
+    activeAt: string;
+    disabledAt: string;
+    tags?: string[];
+};
+export interface FeatureProvider<T> {
+    apiUrl?: string;
+    baseUUID?: string;
+    data: Record<string, T>;
+    getCollectionHash?(configPathOrUrl: string): void;
+    getConfig(configPathOrUrl: string): void;
+    isEnabled(key: string): boolean;
+}
+export declare function FeatureToggle(key: string, fallback?: any): (target: any, propertyKey?: string, descriptor?: PropertyDescriptor) => any;
+export declare abstract class FeatureToggleBase {
+    static featureProvider: FeatureProvider<any>;
+}

package/FeatureToggle.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FeatureToggleBase = void 0;
+exports.FeatureToggle = FeatureToggle;
+require("reflect-metadata");
+class EmptyClass {
+    constructor() { }
+}
+function FeatureToggle(key, fallback) {
+    if (!FeatureToggleBase.featureProvider) {
+        throw new Error("FeatureToggleProvider not set");
+    }
+    return (target, propertyKey, descriptor) => {
+        if (propertyKey && descriptor) {
+            // Method
+            const originalMethod = descriptor.value;
+            // An async method must keep returning a promise when it is switched
+            // off, or `await` at the call site breaks on a plain undefined. The
+            // empty class shell below already makes this distinction; without it
+            // here, turning a feature off would throw inside unrelated code.
+            const isAsync = originalMethod?.[Symbol.toStringTag] === "AsyncFunction";
+            descriptor.value = function (...args) {
+                const isEnabled = FeatureToggleBase.featureProvider.isEnabled(key);
+                if (isEnabled) {
+                    return originalMethod.apply(this, args);
+                }
+                else {
+                    if (fallback !== undefined) {
+                        const result = fallback.apply(this, args);
+                        // A synchronous fallback on an async method would otherwise hand
+                        // back a plain value, breaking the promise the signature
+                        // advertises. Promise.resolve passes an existing promise through
+                        // unchanged, so an async fallback is unaffected.
+                        return isAsync ? Promise.resolve(result) : result;
+                    }
+                    return isAsync ? Promise.resolve() : undefined;
+                }
+            };
+            return descriptor;
+        }
+        else {
+            // Class
+            const originalConstructor = target;
+            let newConstructor;
+            const isEnabled = FeatureToggleBase.featureProvider.isEnabled(key);
+            if (isEnabled) {
+                newConstructor = originalConstructor;
+            }
+            else {
+                newConstructor = fallback !== undefined ? fallback : EmptyClass;
+                if (fallback)
+                    newConstructor.__proto__ = fallback.__proto__;
+                if (newConstructor === EmptyClass) {
+                    Object.getOwnPropertyNames(originalConstructor.prototype).forEach((name) => {
+                        if (name === "constructor")
+                            return;
+                        if (typeof originalConstructor.prototype[name] === "function")
+                            newConstructor.prototype[name] = () => { };
+                        if (originalConstructor.prototype[name][Symbol.toStringTag] ===
+                            "AsyncFunction")
+                            newConstructor.prototype[name] = async () => { };
+                    });
+                }
+            }
+            return newConstructor;
+        }
+    };
+}
+class FeatureToggleBase {
+    static featureProvider;
+}
+exports.FeatureToggleBase = FeatureToggleBase;

package/README.md

@@ -12,7 +12,16 @@ This provides a client for YaFT which aims to bring simple feature toggles for M
 
 ## Installation
 
-`npm install --save @tehw0lf/yaft`
+```bash
+npm install @tehw0lf/yaft
+```
+
+The example API providers use axios and declare it as an optional peer
+dependency, so install it too if you use them:
+
+```bash
+npm install @tehw0lf/yaft axios
+```
 
 ## Initialization
 

package/evaluate.d.ts

@@ -0,0 +1,42 @@
+import { Feature } from "./FeatureToggle";
+/**
+ * A source of the current time, in milliseconds since the epoch.
+ *
+ * Everything that evaluates a feature takes one of these instead of calling
+ * `Date.now()` directly, so tests -- and the conformance suite, which supplies
+ * a `now` with every case -- can evaluate against a fixed instant.
+ */
+export type Clock = () => number;
+/** The default clock: the system time. */
+export declare const systemClock: Clock;
+/**
+ * Parses an RFC 3339 timestamp with an offset.
+ *
+ * Returns `undefined` for anything unset, malformed or in another format;
+ * callers treat that as "no bound", never as an error. An invalid value is
+ * warned about but never throws, so a bad timestamp in the backend cannot take
+ * an application down.
+ */
+export declare function parseTimestamp(value: string | null | undefined): number | undefined;
+/**
+ * Decides whether a feature is on at the instant `now`.
+ *
+ * This is the single definition of YaFT's evaluation rules. Providers call it
+ * rather than implementing the logic themselves, so every provider -- and
+ * every port that mirrors this function -- agrees on the same answer.
+ *
+ * The rules:
+ *
+ * - A missing feature is off.
+ * - Only the exact string `"true"` is on. `"TRUE"`, `"1"` and `""` are off,
+ *   because the backend stores the value as a string and anything else would
+ *   be a silent disagreement between backend and client.
+ * - `activeAt` and `disabledAt` are optional bounds. Unset, null or
+ *   unparseable values are ignored rather than treated as an error.
+ * - The window is half-open: at exactly `activeAt` the feature is on
+ *   (`now < activeAt` is off), at exactly `disabledAt` it is off
+ *   (`now >= disabledAt` is off).
+ * - `activeAt` after `disabledAt` is not special-cased; it simply yields a
+ *   window that is never open.
+ */
+export declare function evaluate(feature: Feature | null | undefined, now: number): boolean;

package/evaluate.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.systemClock = void 0;
+exports.parseTimestamp = parseTimestamp;
+exports.evaluate = evaluate;
+/** The default clock: the system time. */
+const systemClock = () => Date.now();
+exports.systemClock = systemClock;
+/**
+ * Matches RFC 3339 timestamps that carry an explicit offset (`Z` or `±hh:mm`).
+ *
+ * Only this format is accepted. A bare date such as `2026-09-18` or a
+ * timestamp without an offset is rejected, because languages disagree on how
+ * to read them -- JavaScript treats a bare date as UTC midnight and an
+ * offset-less timestamp as local time, while most other languages read both as
+ * local. A feature would then flip at a different instant depending on which
+ * port evaluated it, so such values are ignored rather than guessed at.
+ */
+const RFC3339_WITH_OFFSET = /^(\d{4})-(\d{2})-(\d{2})[Tt](\d{2}):(\d{2}):(\d{2})(\.\d+)?([Zz]|[+-]\d{2}:\d{2})$/;
+/** Days per month, index 1-12; February is handled by the leap-year branch. */
+const DAYS_IN_MONTH = [0, 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+function isLeapYear(year) {
+    return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+}
+function isRealDate(year, month, day) {
+    if (month < 1 || month > 12 || day < 1)
+        return false;
+    const max = month === 2 && isLeapYear(year) ? 29 : DAYS_IN_MONTH[month];
+    return day <= max;
+}
+function isRealTime(hour, minute, second) {
+    // RFC 3339 permits second 60 for a leap second; it is allowed through here
+    // and then rejected by the NaN guard, because Date.parse cannot represent
+    // one. The value ends up ignored either way.
+    return hour <= 23 && minute <= 59 && second <= 60;
+}
+/**
+ * Parses an RFC 3339 timestamp with an offset.
+ *
+ * Returns `undefined` for anything unset, malformed or in another format;
+ * callers treat that as "no bound", never as an error. An invalid value is
+ * warned about but never throws, so a bad timestamp in the backend cannot take
+ * an application down.
+ */
+function parseTimestamp(value) {
+    if (value === null || value === undefined || value === "")
+        return undefined;
+    const match = RFC3339_WITH_OFFSET.exec(value);
+    if (!match) {
+        console.warn(`YaFT: ignoring "${value}", expected RFC 3339 with an offset (e.g. 2026-09-18T15:00:00Z)`);
+        return undefined;
+    }
+    // The pattern only checks the shape, and Date.parse does not reject an
+    // impossible calendar date -- it rolls it over, turning 2027-02-30 into
+    // 2027-03-02. Silently shifting a bound by days is worse than ignoring it,
+    // so the components are range-checked first.
+    const [, year, month, day, hour, minute, second] = match;
+    if (!isRealDate(+year, +month, +day) || !isRealTime(+hour, +minute, +second)) {
+        console.warn(`YaFT: ignoring "${value}", not a valid date or time`);
+        return undefined;
+    }
+    const parsed = Date.parse(value);
+    if (Number.isNaN(parsed)) {
+        console.warn(`YaFT: ignoring "${value}", not a valid timestamp`);
+        return undefined;
+    }
+    return parsed;
+}
+/**
+ * Decides whether a feature is on at the instant `now`.
+ *
+ * This is the single definition of YaFT's evaluation rules. Providers call it
+ * rather than implementing the logic themselves, so every provider -- and
+ * every port that mirrors this function -- agrees on the same answer.
+ *
+ * The rules:
+ *
+ * - A missing feature is off.
+ * - Only the exact string `"true"` is on. `"TRUE"`, `"1"` and `""` are off,
+ *   because the backend stores the value as a string and anything else would
+ *   be a silent disagreement between backend and client.
+ * - `activeAt` and `disabledAt` are optional bounds. Unset, null or
+ *   unparseable values are ignored rather than treated as an error.
+ * - The window is half-open: at exactly `activeAt` the feature is on
+ *   (`now < activeAt` is off), at exactly `disabledAt` it is off
+ *   (`now >= disabledAt` is off).
+ * - `activeAt` after `disabledAt` is not special-cased; it simply yields a
+ *   window that is never open.
+ */
+function evaluate(feature, now) {
+    if (feature === undefined || feature === null)
+        return false;
+    if (feature.value !== "true")
+        return false;
+    const activeAt = parseTimestamp(feature.activeAt);
+    if (activeAt !== undefined && now < activeAt)
+        return false;
+    const disabledAt = parseTimestamp(feature.disabledAt);
+    if (disabledAt !== undefined && now >= disabledAt)
+        return false;
+    return true;
+}

package/examples/ApiServiceBooleanProvider.d.ts

@@ -0,0 +1,11 @@
+import { FeatureProvider } from "../FeatureToggle";
+export declare class ApiServiceBooleanProvider implements FeatureProvider<boolean> {
+    apiUrl: string;
+    baseUUID: string;
+    data: Record<string, boolean>;
+    collectionHash: string;
+    constructor(apiUrl: string, baseUUID: string);
+    getCollectionHash(configPathOrUrl: string): Promise<void>;
+    getConfig(configPathOrUrl: string): Promise<void>;
+    isEnabled(key: string): boolean;
+}

package/examples/ApiServiceBooleanProvider.js

@@ -0,0 +1,82 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiServiceBooleanProvider = void 0;
+const axios_1 = __importDefault(require("axios"));
+const mapping_1 = require("../mapping");
+class ApiServiceBooleanProvider {
+    apiUrl;
+    baseUUID;
+    data = {};
+    collectionHash = "";
+    constructor(apiUrl, baseUUID) {
+        this.apiUrl = apiUrl;
+        this.baseUUID = baseUUID;
+        this.getCollectionHash(`${this.apiUrl}/collectionHash/${this.baseUUID}`);
+    }
+    async getCollectionHash(configPathOrUrl) {
+        try {
+            const response = await axios_1.default.get(configPathOrUrl);
+            const newHash = response.data.collectionHash || response.data.value;
+            if (this.collectionHash !== newHash) {
+                this.collectionHash = newHash;
+                await this.getConfig(`${this.apiUrl}/features/${this.baseUUID}`);
+            }
+        }
+        catch (error) {
+            console.error("Failed to fetch feature toggle from API:", error);
+        }
+    }
+    async getConfig(configPathOrUrl) {
+        try {
+            const response = await axios_1.default.get(configPathOrUrl);
+            // A keyed boolean object is already in this provider's shape and is
+            // taken as-is; anything else is a feature-shaped response and goes
+            // through the core normaliser, so the two providers cannot disagree
+            // about what a response means.
+            if (isKeyedBooleans(response.data)) {
+                this.data = response.data;
+                return;
+            }
+            // 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
+            // "true" -- activeAt and disabledAt are dropped.
+            //
+            // That is a real trap when this provider is pointed at a backend that
+            // 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);
+            this.data = {};
+            for (const [key, feature] of Object.entries(features)) {
+                this.data[key] = feature.value === 'true';
+            }
+        }
+        catch (error) {
+            console.error("Failed to fetch feature toggle from API:", error);
+        }
+    }
+    isEnabled(key) {
+        const feature = this.data[key];
+        if (feature === undefined || feature === null)
+            return false;
+        return feature;
+    }
+}
+exports.ApiServiceBooleanProvider = ApiServiceBooleanProvider;
+/**
+ * True when the payload is already `{ "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.
+ */
+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');
+}

package/examples/ApiServiceFeatureProvider.d.ts

@@ -0,0 +1,17 @@
+import { Clock } from "../evaluate";
+import { Feature, FeatureProvider } from "../FeatureToggle";
+export declare class ApiServiceFeatureProvider implements FeatureProvider<Feature> {
+    apiUrl: string;
+    baseUUID: string;
+    data: Record<string, Feature>;
+    collectionHash: string;
+    private readonly clock;
+    /**
+     * @param clock source of the current time; override it to evaluate against a
+     *              fixed instant in tests
+     */
+    constructor(apiUrl: string, baseUUID: string, clock?: Clock);
+    getCollectionHash(configPathOrUrl: string): Promise<void>;
+    getConfig(configPathOrUrl: string): Promise<void>;
+    isEnabled(key: string): boolean;
+}

package/examples/ApiServiceFeatureProvider.js

@@ -0,0 +1,54 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiServiceFeatureProvider = void 0;
+const axios_1 = __importDefault(require("axios"));
+const evaluate_1 = require("../evaluate");
+const mapping_1 = require("../mapping");
+class ApiServiceFeatureProvider {
+    apiUrl;
+    baseUUID;
+    data = {};
+    collectionHash = "";
+    clock;
+    /**
+     * @param clock source of the current time; override it to evaluate against a
+     *              fixed instant in tests
+     */
+    constructor(apiUrl, baseUUID, clock = evaluate_1.systemClock) {
+        this.clock = clock;
+        this.apiUrl = apiUrl;
+        this.baseUUID = baseUUID;
+        this.getCollectionHash(`${this.apiUrl}/collectionHash/${this.baseUUID}`);
+    }
+    async getCollectionHash(configPathOrUrl) {
+        try {
+            const response = await axios_1.default.get(configPathOrUrl);
+            const newHash = response.data.collectionHash || response.data.value;
+            if (this.collectionHash !== newHash) {
+                this.collectionHash = newHash;
+                await this.getConfig(`${this.apiUrl}/features/${this.baseUUID}`);
+            }
+        }
+        catch (error) {
+            console.error("Failed to fetch feature toggle from API:", error);
+        }
+    }
+    async getConfig(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);
+        }
+        catch (error) {
+            console.error("Failed to fetch feature toggle from API:", error);
+        }
+    }
+    isEnabled(key) {
+        return (0, evaluate_1.evaluate)(this.data[key], this.clock());
+    }
+}
+exports.ApiServiceFeatureProvider = ApiServiceFeatureProvider;

package/examples/LocalStorageBooleanProvider.d.ts

@@ -0,0 +1,7 @@
+import { FeatureProvider } from "../FeatureToggle";
+export declare class LocalStorageBooleanProvider implements FeatureProvider<boolean> {
+    data: Record<string, boolean>;
+    constructor(configPath: string);
+    getConfig(configPathOrUrl: string): void;
+    isEnabled(key: string): boolean;
+}

package/examples/LocalStorageBooleanProvider.js

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

package/examples/LocalStorageFeatureProvider.d.ts

@@ -0,0 +1,14 @@
+import { Clock } from "../evaluate";
+import { Feature, FeatureProvider } from "../FeatureToggle";
+export declare class LocalStorageFeatureProvider implements FeatureProvider<Feature> {
+    data: Record<string, Feature>;
+    private readonly clock;
+    /**
+     * @param configPath path passed to `require()`
+     * @param clock source of the current time; override it to evaluate against a
+     *              fixed instant in tests
+     */
+    constructor(configPath: string, clock?: Clock);
+    getConfig(configPathOrUrl: string): void;
+    isEnabled(key: string): boolean;
+}

package/examples/LocalStorageFeatureProvider.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalStorageFeatureProvider = void 0;
+const evaluate_1 = require("../evaluate");
+class LocalStorageFeatureProvider {
+    data = {};
+    clock;
+    /**
+     * @param configPath path passed to `require()`
+     * @param clock source of the current time; override it to evaluate against a
+     *              fixed instant in tests
+     */
+    constructor(configPath, clock = evaluate_1.systemClock) {
+        this.clock = clock;
+        this.getConfig(configPath);
+    }
+    getConfig(configPathOrUrl) {
+        try {
+            const configData = require(configPathOrUrl);
+            this.data = configData;
+        }
+        catch (error) {
+            console.error("Failed to load configuration from local file:", error);
+            this.data = {};
+        }
+    }
+    isEnabled(key) {
+        return (0, evaluate_1.evaluate)(this.data[key], this.clock());
+    }
+}
+exports.LocalStorageFeatureProvider = LocalStorageFeatureProvider;

package/{src/index.ts → index.d.ts}

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

package/index.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normaliseFeature = exports.normaliseCollection = 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; } });
+var evaluate_1 = require("./evaluate");
+Object.defineProperty(exports, "evaluate", { enumerable: true, get: function () { return evaluate_1.evaluate; } });
+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, "normaliseCollection", { enumerable: true, get: function () { return mapping_1.normaliseCollection; } });
+Object.defineProperty(exports, "normaliseFeature", { enumerable: true, get: function () { return mapping_1.normaliseFeature; } });

package/mapping.d.ts

@@ -0,0 +1,27 @@
+import { Feature } from './FeatureToggle';
+/**
+ * Turns a backend response into provider data.
+ *
+ * This is the single definition of YaFT's mapping rules, the way `evaluate` is
+ * the single definition of the evaluation rules. Providers call it instead of
+ * unpacking responses themselves, so every provider -- and every port that
+ * mirrors it -- agrees on what a response means.
+ */
+/** A raw entry as it arrives over the wire, in either field spelling. */
+type RawFeature = Record<string, unknown>;
+/** Normalises one entry into a `Feature`, whichever spelling it arrived in. */
+export declare function normaliseFeature(raw: RawFeature): Feature;
+/**
+ * Normalises a whole response into features keyed by their key.
+ *
+ * Three envelopes are accepted, because the backend uses all three:
+ *
+ * - `{ "toggles": [...] }` for a UUID group;
+ * - `{ "value": [...] }`, the same thing under a different name;
+ * - a flat object for a single toggle.
+ *
+ * An entry without a usable key is skipped rather than stored under `""`,
+ * where `isEnabled("")` could reach it.
+ */
+export declare function normaliseCollection(response: unknown): Record<string, Feature>;
+export {};

package/mapping.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normaliseFeature = normaliseFeature;
+exports.normaliseCollection = normaliseCollection;
+/**
+ * Reads a field by presence, not by truthiness.
+ *
+ * The obvious `raw.value || raw.Value` is wrong: a present but empty value
+ * falls through to the other spelling, so a feature stored as `""` reads as
+ * whatever the capitalised field holds. An off feature then reports on. The
+ * same trap applies to `tags: []`.
+ *
+ * Backends from 0.2.0 on send only the lowercase spelling; the capitalised one
+ * is read because instances before that are still around.
+ */
+function field(raw, lower, upper) {
+    if (lower in raw)
+        return raw[lower];
+    if (upper in raw)
+        return raw[upper];
+    return undefined;
+}
+/**
+ * Normalises a date field. The backend sends `null` for an unset bound and
+ * local fixtures use `""`; both mean "no bound", and `evaluate` ignores either.
+ */
+function date(value) {
+    return typeof value === 'string' ? value : '';
+}
+/** Normalises one entry into a `Feature`, whichever spelling it arrived in. */
+function normaliseFeature(raw) {
+    const tags = field(raw, 'tags', 'Tags');
+    return {
+        key: String(field(raw, 'key', 'Key') ?? ''),
+        value: String(field(raw, 'value', 'Value') ?? ''),
+        activeAt: date(field(raw, 'activeAt', 'ActiveAt')),
+        disabledAt: date(field(raw, 'disabledAt', 'DisabledAt')),
+        // Filtered rather than asserted: `as string[]` is a compile-time claim
+        // that a backend sending a mixed array would quietly break, handing
+        // callers a non-string through a field typed as string.
+        tags: Array.isArray(tags)
+            ? tags.filter((tag) => typeof tag === 'string')
+            : [],
+    };
+}
+/**
+ * Normalises a whole response into features keyed by their key.
+ *
+ * Three envelopes are accepted, because the backend uses all three:
+ *
+ * - `{ "toggles": [...] }` for a UUID group;
+ * - `{ "value": [...] }`, the same thing under a different name;
+ * - a flat object for a single toggle.
+ *
+ * An entry without a usable key is skipped rather than stored under `""`,
+ * where `isEnabled("")` could reach it.
+ */
+function normaliseCollection(response) {
+    if (response === null || typeof response !== 'object')
+        return {};
+    const body = response;
+    const collection = Array.isArray(body['toggles'])
+        ? body['toggles']
+        : Array.isArray(body['value'])
+            ? body['value']
+            : undefined;
+    // A single toggle comes back flat, not wrapped. Older code only handled the
+    // collections and dropped this shape entirely.
+    const entries = collection ?? [body];
+    const data = {};
+    for (const entry of entries) {
+        if (entry === null || typeof entry !== 'object')
+            continue;
+        const feature = normaliseFeature(entry);
+        if (feature.key !== '')
+            data[feature.key] = feature;
+    }
+    return data;
+}