@tehw0lf/yaft 0.0.15 → 0.0.16

package/package.json

@@ -1,8 +1,21 @@
 {
   "name": "@tehw0lf/yaft",
-  "version": "0.0.15",
+  "version": "0.0.16",
   "description": "YaFT - Feature Toggles using Go&PostgreSQL or any source!",
   "type": "commonjs",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./examples/*": {
+      "types": "./examples/*.d.ts",
+      "default": "./examples/*.js"
+    },
+    "./package.json": "./package.json"
+  },
   "scripts": {
     "build": "tsc && cp package.json README.md logo.svg dist/yaft/ && npm pkg delete devDependencies --prefix dist/yaft",
     "test": "npx jest",
@@ -28,13 +41,12 @@
   "dependencies": {
     "reflect-metadata": "0.2.2"
   },
-  "devDependencies": {
-    "@types/jest": "30.0.0",
-    "@types/node": "24.1.0",
-    "axios": "1.18.0",
-    "jest": "30.4.2",
-    "ts-jest": "29.4.11",
-    "ts-node": "10.9.2",
-    "typescript": "6.0.3"
+  "peerDependencies": {
+    "axios": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "axios": {
+      "optional": true
+    }
   }
 }

package/.github/workflows/build.yml

@@ -1,28 +0,0 @@
-name: build and publish pipeline
-
-on:
-  push:
-    branches:
-      - main
-  pull_request:
-
-jobs:
-  build:
-    name: external workflow
-    uses: tehw0lf/workflows/.github/workflows/build-test-publish.yml@main
-    permissions:
-      actions: write
-      attestations: write
-      contents: write
-      packages: write
-      id-token: write
-      security-events: write
-      pull-requests: write
-    with:
-      tool: "npm"
-      test: "run test"
-      build_branch: "run build"
-      build_main: "run build"
-      artifact_path: "dist"
-      library_path: "dist"
-      npm_audit_omit_dev: true

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

@@ -1,79 +0,0 @@
-# Security Monitoring Workflow
-#
-# This workflow performs security scanning using only the security-specific
-# reusable workflows, without building or publishing.
-#
-# Schedule: Runs daily at 2:00 AM UTC to catch newly disclosed vulnerabilities
-# Manual Trigger: Can be triggered via GitHub Actions UI or gh CLI
-#
-# Security Checks:
-# - Source code scanning: Semgrep (OWASP Top 10, security-audit, CI), npm audit
-# - Artifact scanning: Trivy on dist/ artifacts (requires prior build)
-#
-name: Security Monitoring
-
-on:
-  schedule:
-    # Run daily at 2:00 AM UTC
-    - cron: "0 2 * * *"
-  workflow_dispatch:
-    # Allow manual triggering
-
-permissions:
-  contents: read
-  security-events: write
-  actions: read
-  pull-requests: write
-
-jobs:
-  # Scan source code for security vulnerabilities
-  scan_source:
-    name: Scan Source Code
-    uses: tehw0lf/workflows/.github/workflows/security-scan-source.yml@main
-    permissions:
-      contents: write
-      security-events: write
-      actions: read
-      pull-requests: write
-    with:
-      tool: "npm"
-      semgrep_rules: "auto p/security-audit p/owasp-top-ten p/ci p/nodejs p/typescript"
-      npm_audit_omit_dev: true
-      npm_audit_severity_threshold: "high"
-
-  # Download artifacts from latest CI build
-  # Note: Reuses artifacts from the main CI workflow instead of rebuilding
-  download_artifacts:
-    name: Download Build Artifacts
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Download latest dist artifacts from CI
-        uses: dawidd6/action-download-artifact@bf251b5aa9c2f7eeb574a96ee720e24f801b7c11 # v6
-        with:
-          workflow: build.yml
-          name: dist
-          path: dist/
-          if_no_artifact_found: warn
-
-      - name: Upload artifacts for scanning
-        if: hashFiles('dist/**/*') != ''
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
-        with:
-          name: build
-          path: dist/
-          retention-days: 1
-
-  # Scan built artifacts for vulnerabilities
-  scan_artifacts:
-    name: Scan Artifacts
-    needs: download_artifacts
-    if: needs.download_artifacts.result == 'success'
-    uses: tehw0lf/workflows/.github/workflows/security-scan-artifacts.yml@main
-    permissions:
-      contents: read
-      security-events: write
-      actions: read
-    with:
-      tool: "npm"
-      artifact_path: "dist"

package/CLAUDE.md

@@ -1,151 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Project Overview
-
-YaFT (Yet another Feature Toggle) is a TypeScript library that provides decorator-based feature toggles for classes and methods. It integrates with backend services (Go/PostgreSQL by default) or local data sources to enable/disable features at runtime.
-
-## Development Commands
-
-### Building
-```bash
-npm run build                # Compile TypeScript and prepare package for publishing
-```
-
-### Testing
-```bash
-npm test                     # Run Jest tests with ts-jest transform
-npx jest                     # Alternative test command
-npx jest --watch             # Run tests in watch mode
-npx jest --coverage          # Run tests with coverage report
-```
-
-### Running Single Tests
-```bash
-npx jest yaft.spec.ts        # Run specific test file
-npx jest -t "test name"      # Run specific test by name pattern
-```
-
-## Architecture
-
-### Core Components
-
-**FeatureToggle Decorator (`src/FeatureToggle.ts`)**
-- Main decorator function that can be applied to classes or methods
-- Evaluates feature state at decoration time using the configured provider
-- Returns fallback implementations when features are disabled
-
-**FeatureToggleBase Class**
-- Static container for the global `featureProvider` instance
-- Must be configured before using any `@FeatureToggle` decorators
-
-**FeatureProvider Interface**
-- Defines contract for data sources: `isEnabled(key: string): boolean`
-- Optional API integration with `apiUrl`, `baseUUID`, and collection hash support
-- Flexible data structure support via generic type parameter
-
-### Provider Implementations
-
-**API Providers** (`src/examples/ApiService*Provider.ts`)
-- Integrate with YaFT Go backend via HTTP API
-- Support collection hash for efficient cache invalidation
-- Handle both boolean and Feature data types
-- Include error handling for network failures
-
-**Local Storage Providers** (`src/examples/LocalStorage*Provider.ts`)
-- Load configuration from local JSON files using `require()`
-- 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; 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
-
-**Method Decoration:**
-- Replaces method implementation based on feature state
-- Supports fallback method when feature is disabled
-- Returns empty function if no fallback provided
-
-**Class Decoration:**
-- Replaces entire class constructor and prototype
-- Supports fallback class when feature is disabled
-- Creates EmptyClass with stub methods if no fallback provided
-- Preserves async method signatures in EmptyClass stubs
-
-## Usage Patterns
-
-### Initialization
-```typescript
-import { FeatureToggleBase } from "@tehw0lf/yaft";
-import { LocalStorageFeatureProvider } from "./examples/LocalStorageFeatureProvider";
-
-FeatureToggleBase.featureProvider = new LocalStorageFeatureProvider("./config.json");
-```
-
-### Method Toggle
-```typescript
-@FeatureToggle("myFeature", fallbackMethod)
-myMethod() {
-  // Implementation when feature is enabled
-}
-```
-
-### Class Toggle
-```typescript
-@FeatureToggle("myFeature", FallbackClass)
-class MyClass {
-  // Implementation when feature is enabled
-}
-```
-
-## Testing Strategy
-
-Tests use LocalStorageFeatureProvider with test configuration files (`src/test/test-*.json`). The test suite demonstrates:
-- Class decoration with fallback classes
-- Method decoration with and without fallbacks
-- Async method handling
-- Provider configuration and feature evaluation
-
-## Build Configuration
-
-- **TypeScript**: CommonJS output targeting ES2022
-- **Decorators**: Experimental decorators enabled for `@FeatureToggle` syntax
-- **Output**: Compiled to `dist/yaft/` with declaration files
-- **Package**: Strips devDependencies during build process
-
-## Dependencies
-
-- **Runtime**: `reflect-metadata` for decorator metadata
-- **Development**: TypeScript, Jest, ts-jest for testing
-- **Optional**: `axios` for API provider implementations
-
-## Pre-commit Validation
-
-```bash
-npm test && npm run build
-```

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 Robert Weyres
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/conformance.lock

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

package/jest.config.js

@@ -1,16 +0,0 @@
-/** @type {import('ts-jest').JestConfigWithTsJest} **/
-module.exports = {
-  displayName: 'yaft',
-  setupFilesAfterEnv: [
-    '<rootDir>/src/test/test-setup.ts'
-  ],
-  globals: {},
-  coverageDirectory: 'coverage/yaft',
-  testEnvironment: "node",
-  testMatch: [
-    '<rootDir>/src/**/*.spec.ts'
-  ],
-  transform: {
-    "^.+\\.tsx?$": ["ts-jest", { tsconfig: "tsconfig.spec.json" }],
-  },
-};

package/scripts/fetch-conformance.sh

@@ -1,67 +0,0 @@
-#!/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

@@ -1,95 +0,0 @@
-import "reflect-metadata";
-
-class EmptyClass {
-  constructor() {}
-}
-
-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 function FeatureToggle(key: string, fallback?: any) {
-  if (!FeatureToggleBase.featureProvider) {
-    throw new Error("FeatureToggleProvider not set");
-  }
-  return (
-    target: any,
-    propertyKey?: string,
-    descriptor?: PropertyDescriptor
-  ) => {
-    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: any[]) {
-        const isEnabled = FeatureToggleBase.featureProvider.isEnabled(key);
-        if (isEnabled) {
-          return originalMethod.apply(this, args);
-        } else {
-          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;
-    } else {
-      // Class
-      const originalConstructor = target;
-      let newConstructor: any;
-
-      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: string) => {
-              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;
-    }
-  };
-}
-
-export abstract class FeatureToggleBase {
-  static featureProvider: FeatureProvider<any>;
-}

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;
-}