@tehw0lf/yaft 0.0.10 → 0.0.15

package/.github/workflows/security-scan.yml

@@ -49,7 +49,7 @@ jobs:
 
     steps:
       - name: Download latest dist artifacts from CI
-        uses: dawidd6/action-download-artifact@v6
+        uses: dawidd6/action-download-artifact@bf251b5aa9c2f7eeb574a96ee720e24f801b7c11 # v6
         with:
           workflow: build.yml
           name: dist
@@ -58,7 +58,7 @@ jobs:
 
       - name: Upload artifacts for scanning
         if: hashFiles('dist/**/*') != ''
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
         with:
           name: build
           path: dist/

package/CLAUDE.md

@@ -58,18 +58,31 @@ npx jest -t "test name"      # Run specific test by name pattern
 - Support both boolean and Feature data types
 - Fallback to empty configuration on file load errors
 
+**Evaluation Core (`src/evaluate.ts`)**
+- `evaluate(feature, now)` is the single definition of the evaluation rules
+- Providers call it instead of implementing the logic themselves; before this
+  existed, the feature providers each carried their own copy
+- `Clock` is a `() => number`; providers take one and default to `systemClock`,
+  so tests and the conformance adapter can pin `now`
+- `parseTimestamp` accepts only RFC 3339 with an offset and returns
+  `undefined` for anything else, warning rather than throwing
+
 ### Feature Data Model
 
 ```typescript
 type Feature = {
-  key: string;       // Unique feature identifier
-  value: string;     // Boolean value as string
-  activeAt: string;  // ISO date when feature becomes active
-  disabledAt: string; // ISO date when feature gets disabled
+  key: string;        // Unique feature identifier
+  value: string;      // Boolean value as string; only "true" is on
+  activeAt: string;   // RFC 3339 with offset, or empty
+  disabledAt: string; // RFC 3339 with offset, or empty
+  tags?: string[];
 }
 ```
 
 Features support time-based activation/deactivation logic evaluated at runtime.
+The window is half-open: `now == activeAt` is on, `now == disabledAt` is off.
+Dates without an offset are ignored, because languages disagree on how to read
+them and a feature would otherwise flip at a different instant per port.
 
 ### Decorator Behavior
 

package/README.md

@@ -94,9 +94,85 @@ export type Feature = {
   value: string;
   activeAt: string;
   disabledAt: string;
+  tags?: string[];
 };
 ```
 
+## Evaluation rules
+
+These rules are not this library's own: they are
+[yaft-conformance](https://github.com/tehw0lf/yaft-conformance), the shared
+specification every YaFT implementation is checked against. This port passes
+the whole suite (see [Conformance](#conformance) below), so a feature evaluates
+identically here and in any other port.
+
+A feature is on when all of the following hold. `evaluate` is exported, so the
+rules can be applied directly to a feature without going through a provider.
+
+- The value is exactly `"true"`. `"TRUE"`, `"1"` and `""` are off -- the value
+  is stored as a string, and anything else would be a silent disagreement
+  between backend and client.
+- `activeAt` has passed, if set. The bound is inclusive: at exactly `activeAt`
+  the feature is on.
+- `disabledAt` has not been reached, if set. This bound is exclusive: at
+  exactly `disabledAt` the feature is off.
+
+A missing feature is off. Unset, `null` or unparseable dates are ignored rather
+than treated as an error, and never throw.
+
+### Date format
+
+Dates must be **RFC 3339 with an offset** (`2026-09-18T15:00:00Z` or
+`2026-09-18T15:00:00+02:00`). Anything else -- a bare date such as
+`2026-09-18`, or a timestamp without an offset -- is ignored and logged as a
+warning.
+
+This is stricter than `Date.parse`, on purpose: JavaScript reads a bare date as
+UTC midnight and an offset-less timestamp as local time, while most other
+languages read both as local. Accepting them would make a feature flip at a
+different instant depending on which client evaluated it.
+
+## Testing with a fixed time
+
+Both `Feature` providers take an optional clock, so a test can evaluate against
+a fixed instant instead of the current time:
+
+```ts
+import { LocalStorageFeatureProvider } from "./provider";
+
+const provider = new LocalStorageFeatureProvider(
+  "./test-feature.json",
+  () => Date.parse("2026-09-18T12:00:00Z")
+);
+```
+
+The clock defaults to the system time, so existing code needs no change.
+
+## Conformance
+
+The rules above are specified once, language-neutrally, in
+[yaft-conformance](https://github.com/tehw0lf/yaft-conformance), and this port
+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
+```
+
+`npm test` fetches that release, verifies the checksum and unpacks it before
+Jest runs, so there is no separate step to forget and no way to get a green run
+against stale cases. Upgrading the suite is a one-line change to that file,
+visible in review.
+
+The checksum is not decoration: a Git tag can be moved, and without verifying
+the asset a port's tests could change with no diff at all.
+
+The adapter lives in `src/test/conformance-adapter/`. It fails loudly on a case
+whose `target`, `toggle` or `expected` it does not implement, rather than
+skipping it -- a silently skipped case is a rule that nothing enforces.
+
 # Licenses
 
 - Code: MIT License

package/conformance.lock

@@ -0,0 +1,2 @@
+version=v1.1.0
+sha256=d83ff1c960ad29830c00b57727591da628f4323b777faea245f603565d1c9ae9

package/logo.svg

@@ -1,4 +1,4 @@
-<svg viewBox="0 0 60 60" stroke="" fill="grey" xmlns="http://www.w3.org/2000/svg">
+<svg viewBox="0 0 60 60" stroke="" fill="#8e8e8e" xmlns="http://www.w3.org/2000/svg">
     <title>YaFT Logo</title>
     <desc>Yet Another Feature Toggle - Copyright 2025 tehw0lf</desc>
     <metadata>
@@ -11,8 +11,8 @@
         </rdf:RDF>
     </metadata>
     <!-- Y -->
-    <path d="M5,5 L30,28" stroke="grey" stroke-width="4" fill="none" />
-    <path d="M55,5 L30,28" stroke="grey" stroke-width="4" fill="none" />
+    <path d="M5,5 L30,28" stroke="#8e8e8e" stroke-width="4" fill="none" />
+    <path d="M55,5 L30,28" stroke="#8e8e8e" stroke-width="4" fill="none" />
     <!-- A -->
     <rect x="19" y="17.5" width="22" height="3" />
     <!-- F -->

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "@tehw0lf/yaft",
-  "version": "0.0.10",
+  "version": "0.0.15",
   "description": "YaFT - Feature Toggles using Go&PostgreSQL or any source!",
   "type": "commonjs",
   "scripts": {
     "build": "tsc && cp package.json README.md logo.svg dist/yaft/ && npm pkg delete devDependencies --prefix dist/yaft",
-    "test": "npx jest"
+    "test": "npx jest",
+    "conformance:fetch": "./scripts/fetch-conformance.sh src/test/conformance",
+    "pretest": "npm run conformance:fetch"
   },
   "repository": {
     "type": "git",

package/scripts/fetch-conformance.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+#
+# Fetches the YaFT conformance suite pinned in conformance.lock.
+#
+# Copy this into a port, next to a conformance.lock of the form:
+#
+#   version=v1.0.0
+#   sha256=<checksum of cases.tar.gz>
+#
+# The checksum is not optional. A Git tag can be moved; verifying the asset is
+# what stops a port's tests from changing without a diff.
+#
+# Usage: scripts/fetch-conformance.sh [target-dir]   (default: src/test/conformance)
+#
+# Set the default to wherever the port's adapter reads the cases from. Ports
+# differ -- yaft-ts uses src/test/conformance -- and a default that does not
+# match leaves the next test run reporting missing cases.
+
+set -euo pipefail
+
+REPO="tehw0lf/yaft-conformance"
+LOCK="${LOCK:-conformance.lock}"
+TARGET="${1:-src/test/conformance}"
+
+if [[ ! -f "$LOCK" ]]; then
+  echo "error: $LOCK not found; run from the port's root" >&2
+  exit 1
+fi
+
+version="$(grep -E '^version=' "$LOCK" | cut -d= -f2-)"
+expected="$(grep -E '^sha256=' "$LOCK" | cut -d= -f2-)"
+
+if [[ -z "$version" || -z "$expected" ]]; then
+  echo "error: $LOCK needs both version= and sha256=" >&2
+  exit 1
+fi
+
+tmp="$(mktemp -d)"
+trap 'rm -rf "$tmp"' EXIT
+
+url="https://github.com/${REPO}/releases/download/${version}/cases.tar.gz"
+echo "fetching conformance suite ${version}"
+curl --fail --location --silent --show-error --output "$tmp/cases.tar.gz" "$url"
+
+# sha256sum is GNU coreutils and is not present on macOS; shasum ships with
+# both. Preferring sha256sum keeps Linux CI on the faster binary.
+if command -v sha256sum >/dev/null 2>&1; then
+  actual="$(sha256sum "$tmp/cases.tar.gz" | cut -d' ' -f1)"
+elif command -v shasum >/dev/null 2>&1; then
+  actual="$(shasum -a 256 "$tmp/cases.tar.gz" | cut -d' ' -f1)"
+else
+  echo "error: neither sha256sum nor shasum found; cannot verify the download" >&2
+  exit 1
+fi
+if [[ "$actual" != "$expected" ]]; then
+  echo "error: checksum mismatch for cases.tar.gz" >&2
+  echo "  expected $expected" >&2
+  echo "  actual   $actual" >&2
+  echo "The tag may have been moved. Do not update the lock without reading the diff." >&2
+  exit 1
+fi
+
+rm -rf "$TARGET"
+mkdir -p "$TARGET"
+tar --extract --gzip --file "$tmp/cases.tar.gz" --directory "$TARGET"
+
+echo "conformance suite ${version} unpacked into ${TARGET}"

package/src/FeatureToggle.ts

@@ -34,14 +34,27 @@ export function FeatureToggle(key: string, fallback?: any) {
       // 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: any[]) {
         const isEnabled = FeatureToggleBase.featureProvider.isEnabled(key);
         if (isEnabled) {
           return originalMethod.apply(this, args);
         } else {
-          return fallback !== undefined
-            ? fallback.apply(this, args as [])
-            : (() => {}).apply(this, args as []);
+          if (fallback !== undefined) {
+            const result = fallback.apply(this, args as []);
+            // 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;

package/src/evaluate.ts

@@ -0,0 +1,122 @@
+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 const systemClock: Clock = () => Date.now();
+
+/**
+ * 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: number): boolean {
+  return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+}
+
+function isRealDate(year: number, month: number, day: number): boolean {
+  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: number, minute: number, second: number): boolean {
+  // 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.
+ */
+export function parseTimestamp(value: string | null | undefined): number | undefined {
+  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.
+ */
+export function evaluate(
+  feature: Feature | null | undefined,
+  now: number
+): boolean {
+  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/src/examples/ApiServiceBooleanProvider.ts

@@ -1,6 +1,7 @@
 import axios from "axios";
 
 import { FeatureProvider } from "../FeatureToggle";
+import { normaliseCollection } from "../mapping";
 
 export class ApiServiceBooleanProvider implements FeatureProvider<boolean> {
   apiUrl: string;
@@ -30,22 +31,28 @@ export class ApiServiceBooleanProvider implements FeatureProvider<boolean> {
   async getConfig(configPathOrUrl: string): Promise<void> {
     try {
       const response = await axios.get(configPathOrUrl);
-      // Handle Go backend response format
-      const featuresArray = response.data.toggles || response.data.value || [];
-      
-      // Convert array to keyed boolean object and handle capitalized field names
+
+      // 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 = normaliseCollection(response.data);
       this.data = {};
-      if (Array.isArray(featuresArray)) {
-        featuresArray.forEach((feature: any) => {
-          const key = feature.key || feature.Key;
-          const value = feature.value || feature.Value;
-          if (key) {
-            this.data[key] = value === 'true' || value === true;
-          }
-        });
-      } else {
-        // Fallback for object format
-        this.data = featuresArray;
+      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);
@@ -58,3 +65,18 @@ export class ApiServiceBooleanProvider implements FeatureProvider<boolean> {
     return feature;
   }
 }
+
+/**
+ * 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: unknown): data is Record<string, boolean> {
+  if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+    return false;
+  }
+  const values = Object.values(data as Record<string, unknown>);
+  return values.length > 0 && values.every((v) => typeof v === 'boolean');
+}

package/src/examples/ApiServiceFeatureProvider.ts

@@ -1,5 +1,7 @@
 import axios from "axios";
 
+import { Clock, evaluate, systemClock } from "../evaluate";
+import { normaliseCollection } from "../mapping";
 import { Feature, FeatureProvider } from "../FeatureToggle";
 
 export class ApiServiceFeatureProvider implements FeatureProvider<Feature> {
@@ -7,8 +9,14 @@ export class ApiServiceFeatureProvider implements FeatureProvider<Feature> {
   baseUUID: string;
   data: Record<string, Feature> = {};
   collectionHash = "";
-
-  constructor(apiUrl: string, baseUUID: string) {
+  private readonly clock: 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 = systemClock) {
+    this.clock = clock;
     this.apiUrl = apiUrl;
     this.baseUUID = baseUUID;
     this.getCollectionHash(`${this.apiUrl}/collectionHash/${this.baseUUID}`);
@@ -30,58 +38,15 @@ export class ApiServiceFeatureProvider implements FeatureProvider<Feature> {
   async getConfig(configPathOrUrl: string): Promise<void> {
     try {
       const response = await axios.get(configPathOrUrl);
-      // Handle Go backend response format
-      const featuresArray = response.data.toggles || response.data.value || [];
-      
-      // Convert array to keyed object and handle capitalized field names
-      this.data = {};
-      if (Array.isArray(featuresArray)) {
-        featuresArray.forEach((feature: any) => {
-          const normalizedFeature = {
-            key: feature.key || feature.Key,
-            value: feature.value || feature.Value,
-            activeAt: feature.activeAt || feature.ActiveAt,
-            disabledAt: feature.disabledAt || feature.DisabledAt,
-            tags: feature.tags || feature.Tags || [],
-          };
-          if (normalizedFeature.key) {
-            this.data[normalizedFeature.key] = normalizedFeature;
-          }
-        });
-      } else {
-        // Fallback for object format
-        this.data = featuresArray;
-      }
+      // The mapping rules live in the core, next to the evaluation rules,
+      // rather than being reimplemented per provider.
+      this.data = normaliseCollection(response.data);
     } catch (error) {
       console.error("Failed to fetch feature toggle from API:", error);
     }
   }
 
   isEnabled(key: string): boolean {
-    const feature = this.data[key];
-
-    if (feature === undefined || feature === null) return false;
-
-    // First check: value must be "true"
-    if (feature.value !== "true") return false;
-
-    // Second check: if activeAt is set and in future, not yet active
-    if (feature.activeAt && feature.activeAt !== "") {
-      const activeTime = Date.parse(feature.activeAt);
-      if (!isNaN(activeTime) && Date.now() < activeTime) {
-        return false;
-      }
-    }
-
-    // Third check: if disabledAt is set and in past, already disabled
-    if (feature.disabledAt && feature.disabledAt !== "") {
-      const disabledTime = Date.parse(feature.disabledAt);
-      if (!isNaN(disabledTime) && Date.now() >= disabledTime) {
-        return false;
-      }
-    }
-
-    // All checks passed, feature is enabled
-    return true;
+    return evaluate(this.data[key], this.clock());
   }
 }

package/src/examples/LocalStorageFeatureProvider.ts

@@ -1,9 +1,17 @@
+import { Clock, evaluate, systemClock } from "../evaluate";
 import { Feature, FeatureProvider } from "../FeatureToggle";
 
 export class LocalStorageFeatureProvider implements FeatureProvider<Feature> {
   data: Record<string, Feature> = {};
-
-  constructor(configPath: string) {
+  private readonly clock: 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 = systemClock) {
+    this.clock = clock;
     this.getConfig(configPath);
   }
 
@@ -18,30 +26,6 @@ export class LocalStorageFeatureProvider implements FeatureProvider<Feature> {
   }
 
   isEnabled(key: string): boolean {
-    const feature = this.data[key] as Feature;
-
-    if (feature === undefined || feature === null) return false;
-
-    // First check: value must be "true"
-    if (feature.value !== "true") return false;
-
-    // Second check: if activeAt is set and in future, not yet active
-    if (feature.activeAt && feature.activeAt !== "") {
-      const activeTime = Date.parse(feature.activeAt);
-      if (!isNaN(activeTime) && Date.now() < activeTime) {
-        return false;
-      }
-    }
-
-    // Third check: if disabledAt is set and in past, already disabled
-    if (feature.disabledAt && feature.disabledAt !== "") {
-      const disabledTime = Date.parse(feature.disabledAt);
-      if (!isNaN(disabledTime) && Date.now() >= disabledTime) {
-        return false;
-      }
-    }
-
-    // All checks passed, feature is enabled
-    return true;
+    return evaluate(this.data[key], this.clock());
   }
 }

package/src/index.ts

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