@tehw0lf/yaft 0.0.1 → 0.0.3

package/.github/workflows/build.yml

@@ -0,0 +1,25 @@
+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"
+      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/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/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,13 +1,10 @@
 {
   "name": "@tehw0lf/yaft",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "YaFT - Feature Toggles using Go&PostgreSQL or any source!",
-  "files": [
-    "dist"
-  ],
   "type": "commonjs",
   "scripts": {
-    "build": "tsc && npm pkg delete devDependencies && cp package.json dist/yaft"
+    "build": "tsc && npm pkg delete devDependencies && cp package.json README.md logo.svg dist/"
   },
   "repository": {
     "type": "git",
@@ -27,5 +24,10 @@
   "homepage": "https://github.com/tehw0lf/yaft-ts#readme",
   "dependencies": {
     "reflect-metadata": "^0.2.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.14.1",
+    "axios": "^1.8.4",
+    "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";

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "target": "ES2022",
+    "experimentalDecorators": true,
+    "declaration": true,
+    "outDir": "./dist"
+  },
+  "include": ["src/*.ts"]
+}