@tehw0lf/yaft 0.0.15 → 0.0.17

package/src/evaluate.ts

@@ -1,122 +0,0 @@
-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,82 +0,0 @@
-import axios from "axios";
-
-import { FeatureProvider } from "../FeatureToggle";
-import { normaliseCollection } from "../mapping";
-
-export class ApiServiceBooleanProvider implements FeatureProvider<boolean> {
-  apiUrl: string;
-  baseUUID: string;
-  data: Record<string, boolean> = {};
-  collectionHash = "";
-
-  constructor(apiUrl: string, baseUUID: string) {
-    this.apiUrl = apiUrl;
-    this.baseUUID = baseUUID;
-    this.getCollectionHash(`${this.apiUrl}/collectionHash/${this.baseUUID}`);
-  }
-
-  async getCollectionHash(configPathOrUrl: string): Promise<void> {
-    try {
-      const response = await axios.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: string): Promise<void> {
-    try {
-      const response = await axios.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 = 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: string): boolean {
-    const feature = this.data[key];
-    if (feature === undefined || feature === null) return false;
-    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,52 +0,0 @@
-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> {
-  apiUrl: string;
-  baseUUID: string;
-  data: Record<string, Feature> = {};
-  collectionHash = "";
-  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}`);
-  }
-
-  async getCollectionHash(configPathOrUrl: string): Promise<void> {
-    try {
-      const response = await axios.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: string): Promise<void> {
-    try {
-      const response = await axios.get(configPathOrUrl);
-      // 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 {
-    return evaluate(this.data[key], this.clock());
-  }
-}

package/src/examples/LocalStorageBooleanProvider.ts

@@ -1,25 +0,0 @@
-import { FeatureProvider } from "../FeatureToggle";
-
-export class LocalStorageBooleanProvider implements FeatureProvider<boolean> {
-  data: Record<string, boolean> = {};
-
-  constructor(configPath: string) {
-    this.getConfig(configPath);
-  }
-
-  getConfig(configPathOrUrl: string): void {
-    try {
-      const configData = require(configPathOrUrl);
-      this.data = configData;
-    } catch (error) {
-      console.error("Failed to load configuration from local file:", error);
-      this.data = {};
-    }
-  }
-
-  isEnabled(key: string): boolean {
-    const feature = this.data[key];
-    if (feature === undefined || feature === null) return false;
-    return feature;
-  }
-}

package/src/examples/LocalStorageFeatureProvider.ts

@@ -1,31 +0,0 @@
-import { Clock, evaluate, systemClock } from "../evaluate";
-import { Feature, FeatureProvider } from "../FeatureToggle";
-
-export class LocalStorageFeatureProvider implements FeatureProvider<Feature> {
-  data: Record<string, Feature> = {};
-  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);
-  }
-
-  getConfig(configPathOrUrl: string): void {
-    try {
-      const configData = require(configPathOrUrl);
-      this.data = configData;
-    } catch (error) {
-      console.error("Failed to load configuration from local file:", error);
-      this.data = {};
-    }
-  }
-
-  isEnabled(key: string): boolean {
-    return evaluate(this.data[key], this.clock());
-  }
-}

package/src/index.ts

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

package/src/mapping.ts

@@ -1,92 +0,0 @@
-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>;
-
-/**
- * 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: RawFeature, lower: string, upper: string): unknown {
-  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: unknown): string {
-  return typeof value === 'string' ? value : '';
-}
-
-/** Normalises one entry into a `Feature`, whichever spelling it arrived in. */
-export function normaliseFeature(raw: RawFeature): Feature {
-  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): tag is string => 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.
- */
-export function normaliseCollection(response: unknown): Record<string, Feature> {
-  if (response === null || typeof response !== 'object') return {};
-
-  const body = response as Record<string, unknown>;
-  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: Record<string, Feature> = {};
-  for (const entry of entries) {
-    if (entry === null || typeof entry !== 'object') continue;
-
-    const feature = normaliseFeature(entry as RawFeature);
-    if (feature.key !== '') data[feature.key] = feature;
-  }
-  return data;
-}

package/src/test/conformance-adapter/cases.ts

@@ -1,104 +0,0 @@
-import { existsSync, readFileSync } from 'fs';
-import { join } from 'path';
-
-/**
- * Loads the conformance case files.
- *
- * The cases live in `cases/`, fetched by `scripts/fetch-conformance.sh` from
- * the version pinned in `conformance.lock`. They are not checked in: the lock
- * file plus its checksum is what makes a suite bump a reviewable one-line
- * diff, and a committed copy would drift from the tag it claims to be.
- */
-
-const CASES_DIR = join(__dirname, '..', 'conformance', 'cases');
-
-/** A rule id from SPEC.md, such as `R5` or `R22a`. */
-export type Rule = string;
-
-interface CaseFile<T> {
-  suite: string;
-  version: number;
-  cases: T[];
-}
-
-export interface EvaluationCase {
-  name: string;
-  rules: Rule[];
-  why?: string;
-  now: string;
-  features: Record<string, unknown>;
-  key: string;
-  expected: boolean;
-}
-
-export interface DecoratorCase {
-  name: string;
-  rules: Rule[];
-  why?: string;
-  target: 'class' | 'method' | 'async-method';
-  toggle: 'on' | 'off' | 'on-then-off' | 'off-then-on' | 'no-provider';
-  fallback: 'none' | 'class' | 'method';
-  expected:
-    | 'original'
-    | 'fallback'
-    | 'nothing'
-    | 'resolved-nothing'
-    | 'empty-shell'
-    | 'decoration-error';
-  assertions?: ('same-arguments' | 'same-receiver')[];
-}
-
-export interface MappingCase {
-  name: string;
-  rules: Rule[];
-  why?: string;
-  shape: 'feature' | 'boolean';
-  response: unknown;
-  expected: Record<string, unknown>;
-}
-
-function load<T>(suite: string): CaseFile<T> {
-  const path = join(CASES_DIR, `${suite}.json`);
-
-  if (!existsSync(path)) {
-    throw new Error(
-      `Conformance cases missing at ${path}.\n` +
-        'Run scripts/fetch-conformance.sh before the tests; CI does this in a ' +
-        'dedicated step.'
-    );
-  }
-
-  const file = JSON.parse(readFileSync(path, 'utf8')) as CaseFile<T>;
-  if (file.suite !== suite) {
-    throw new Error(`${path} declares suite "${file.suite}", expected "${suite}"`);
-  }
-  return file;
-}
-
-export const evaluationCases = () => load<EvaluationCase>('evaluation').cases;
-export const decoratorCases = () => load<DecoratorCase>('decorator').cases;
-export const mappingCases = () => load<MappingCase>('mapping').cases;
-
-/**
- * Names a case for the test output, so a failure points at a rule without
- * anyone having to open the case file.
- */
-export function title(c: { name: string; rules: Rule[] }): string {
-  return `${c.name} [${c.rules.join(', ')}]`;
-}
-
-/**
- * Rejects a value the adapter does not know how to handle.
- *
- * A case whose `target`, `toggle` or `expected` this adapter has never seen is
- * a rule that nothing enforces here. Skipping it would leave the suite looking
- * green while a requirement goes unchecked, so an unknown value is a failure
- * instead -- it means the suite grew and the adapter has to catch up.
- */
-export function unsupported(kind: string, value: string, caseName: string): never {
-  throw new Error(
-    `Case "${caseName}" uses ${kind} "${value}", which this adapter does not ` +
-      'implement. The conformance suite has gained a case this port does not ' +
-      'cover yet -- extend the adapter rather than skipping the case.'
-  );
-}