@tehw0lf/yaft 0.0.2 → 0.0.4

package/.github/workflows/build.yml

@@ -0,0 +1,26 @@
+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
+      contents: write
+      packages: write
+    with:
+      tool: "npm"
+      test: "run test"
+      build_branch: "run build"
+      build_main: "run build"
+      event_name: ${{ github.event_name }}
+      artifact_path: "dist"
+      library_path: "dist"
+    secrets:
+      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

package/CLAUDE.md

@@ -0,0 +1,138 @@
+# 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
+
+### 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
+}
+```
+
+Features support time-based activation/deactivation logic evaluated at runtime.
+
+### 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

@@ -0,0 +1,21 @@
+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/README.md

@@ -0,0 +1,103 @@
+# YaFT for TypeScript
+
+<div align="center">
+  <img src="./logo.svg" alt="YaFT Logo" width="140">
+</div>
+
+---
+
+This provides a client for YaFT which aims to bring simple feature toggles for Methods and Classes to Typescript.
+
+---
+
+## Installation
+
+`npm install --save @tehw0lf/yaft`
+
+## Initialization
+
+To be able to use YaFT, implement and set a `FeatureProvider` on the abstract Base Class, or copy and adapt one of the example providers.
+
+In this example a local json file with the `Feature` data type is used, but in theory any data type can be used since the Provider implements the isEnabled function which can be overridden as necessary.
+
+```ts
+import { FeatureToggleBase } from "@tehw0lf/yaft";
+import { LocalStorageFeatureProvider } from "./provider";
+
+FeatureToggleBase.featureProvider = new LocalStorageFeatureProvider(
+  "./test-feature.json"
+);
+```
+
+This repo contains examples for two provider types: API Providers for `boolean` and `Feature` and LocalStorage Providers for `boolean` and `Feature`. The APi providers are designed to work with the default Go implementation of YaFT, but can be implemented through their interface:
+
+```ts
+export interface FeatureProvider<T> {
+  apiUrl?: string;
+  baseUUID?: string;
+  data: Record<string, T>;
+  initConfig(configPathOrUrl: string): void;
+  isEnabled(key: string): boolean;
+}
+```
+
+## Usage
+
+To manage anything with a feature toggle, decorate it with the feature's key:
+
+```ts
+import { FeatureToggle } from "@tehw0lf/yaft";
+
+@FeatureToggle("myKey")
+class MyClass {}
+```
+
+```ts
+import { FeatureToggle } from "@tehw0lf/yaft";
+
+@FeatureToggle("myKey")
+myMethod() {}
+```
+
+If the feature is enabled, the original class/method will be used.
+
+If the feature is disabled, a fallback can be provided:
+
+```ts
+import { FeatureToggle } from "@tehw0lf/yaft";
+
+@FeatureToggle("myKey", MyFallbackClass)
+class MyClass {}
+```
+
+```ts
+import { FeatureToggle } from "@tehw0lf/yaft";
+
+@FeatureToggle("myKey", myFallbackMethod)
+myMethod() {}
+```
+
+Otherwise, or if the feature does not exist, the class/method gets replaced with an empty object/an empty function.
+
+## Collection Hash
+
+The default YaFT API provides a collection hash to efficiently check whether the locally cached features are still up to date. See API provider examples for details.
+This can be scheduled to automatically update feature data in the background.
+
+## Feature Data Type
+
+The default data type for YaFT is `Feature`. A feature has a key string, a value string representing a boolean and optional activeAt and disabledAt date strings.
+
+```ts
+export type Feature = {
+  key: string;
+  value: string;
+  activeAt: string;
+  disabledAt: string;
+};
+```
+
+# Licenses
+
+- Code: MIT License
+- Logo/Branding: All rights reserved

package/jest.config.js

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

package/logo.svg

@@ -0,0 +1,27 @@
+<svg viewBox="0 0 60 60" stroke="" fill="grey" xmlns="http://www.w3.org/2000/svg">
+    <title>YaFT Logo</title>
+    <desc>Yet Another Feature Toggle - Copyright 2025 tehw0lf</desc>
+    <metadata>
+        <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:dc="http://purl.org/dc/elements/1.1/">
+            <rdf:Description>
+                <dc:creator>tehw0lf</dc:creator>
+                <dc:date>2025</dc:date>
+                <dc:rights>Copyright 2025 tehw0lf. All rights reserved.</dc:rights>
+            </rdf:Description>
+        </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" />
+    <!-- A -->
+    <rect x="19" y="17.5" width="22" height="3" />
+    <!-- F -->
+    <rect x="27.5" y="40" width="15" height="5" />
+    <!-- T -->
+    <rect x="27.5" y="25" width="5" height="35" />
+    <rect x="10" y="25" width="40" height="5" />
+    <!-- cross -->
+    <path d="M5,20 L20,5" stroke="red" stroke-width="4" fill="none" />
+    <!-- check -->
+    <path d="M40.8,20.8 L30.8,10.8" stroke="green" stroke-width="4" fill="none" />
+</svg>

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@tehw0lf/yaft",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "YaFT - Feature Toggles using Go&PostgreSQL or any source!",
   "type": "commonjs",
   "scripts": {
-    "build": "tsc && npm pkg delete devDependencies && cp package.json dist/"
+    "build": "tsc && npm pkg delete devDependencies && cp package.json README.md logo.svg dist/",
+    "test": "jest"
   },
   "repository": {
     "type": "git",
@@ -24,5 +25,14 @@
   "homepage": "https://github.com/tehw0lf/yaft-ts#readme",
   "dependencies": {
     "reflect-metadata": "^0.2.2"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.14",
+    "@types/node": "^22.14.1",
+    "axios": "^1.8.4",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.3.2",
+    "ts-node": "^10.9.2",
+    "typescript": "^4.2.3"
   }
 }

package/src/FeatureToggle.ts

@@ -0,0 +1,80 @@
+import "reflect-metadata";
+
+class EmptyClass {
+  constructor() {}
+}
+
+export type Feature = {
+  key: string;
+  value: string;
+  activeAt: string;
+  disabledAt: 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");
+  }
+  const isEnabled = FeatureToggleBase.featureProvider.isEnabled(key);
+  return (
+    target: any,
+    propertyKey?: string,
+    descriptor?: PropertyDescriptor
+  ) => {
+    if (propertyKey && descriptor) {
+      // Method
+      const originalMethod = descriptor.value;
+
+      descriptor.value = function (...args: any[]) {
+        if (isEnabled) {
+          return originalMethod.apply(this, args);
+        } else {
+          return fallback !== undefined
+            ? fallback.apply(this, args)
+            : (() => {}).apply(this, args);
+        }
+      };
+      return descriptor;
+    } else {
+      // Class
+      const originalConstructor = target;
+      let newConstructor: any;
+
+      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/examples/ApiServiceBooleanProvider.ts

@@ -0,0 +1,44 @@
+import axios from "axios";
+
+import { FeatureProvider } from "../FeatureToggle";
+
+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.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);
+      this.data = response.data.value;
+    } 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;
+  }
+}

package/src/examples/ApiServiceFeatureProvider.ts

@@ -0,0 +1,49 @@
+import axios from "axios";
+
+import { Feature, FeatureProvider } from "../FeatureToggle";
+
+export class ApiServiceFeatureProvider implements FeatureProvider<Feature> {
+  apiUrl: string;
+  baseUUID: string;
+  data: Record<string, Feature> = {};
+  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.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);
+      this.data = response.data.value;
+    } 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;
+
+    if (Date.now() >= Date.parse(feature.disabledAt)) return false;
+    if (Date.now() >= Date.parse(feature.activeAt)) return true;
+
+    return JSON.parse(feature.value);
+  }
+}

package/src/examples/LocalStorageBooleanProvider.ts

@@ -0,0 +1,25 @@
+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

@@ -0,0 +1,30 @@
+import { Feature, FeatureProvider } from "../FeatureToggle";
+
+export class LocalStorageFeatureProvider implements FeatureProvider<Feature> {
+  data: Record<string, Feature> = {};
+
+  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] as Feature;
+
+    if (feature === undefined || feature === null) return false;
+
+    if (Date.now() >= Date.parse(feature.disabledAt)) return false;
+    if (Date.now() >= Date.parse(feature.activeAt)) return true;
+
+    return JSON.parse(feature.value);
+  }
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export {
+  Feature,
+  FeatureToggle,
+  FeatureToggleBase,
+  FeatureProvider,
+} from "./FeatureToggle";