@tehw0lf/yaft 0.0.3 → 0.0.4

package/.github/workflows/build.yml

@@ -16,6 +16,7 @@ jobs:
       packages: write
     with:
       tool: "npm"
+      test: "run test"
       build_branch: "run build"
       build_main: "run build"
       event_name: ${{ github.event_name }}

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/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

@@ -23,5 +23,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" />
+    <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.3",
+  "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 README.md logo.svg dist/"
+    "build": "tsc && npm pkg delete devDependencies && cp package.json README.md logo.svg dist/",
+    "test": "jest"
   },
   "repository": {
     "type": "git",
@@ -26,8 +27,12 @@
     "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/test/decorator-behavior.spec.ts

@@ -0,0 +1,359 @@
+import { FeatureToggle, FeatureToggleBase, FeatureProvider } from '../FeatureToggle';
+
+describe('FeatureToggle Decorator Behavior', () => {
+  let mockProvider: FeatureProvider<boolean>;
+
+  beforeEach(() => {
+    mockProvider = {
+      data: {},
+      getConfig: jest.fn(),
+      isEnabled: jest.fn()
+    };
+    FeatureToggleBase.featureProvider = mockProvider;
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe('Method Decoration', () => {
+    it('should execute original method when feature is enabled', () => {
+      (mockProvider.isEnabled as jest.Mock).mockReturnValue(true);
+      let executionResult = '';
+
+      class TestClass {
+        @FeatureToggle('enabledFeature')
+        testMethod() {
+          executionResult = 'original method executed';
+          return 'original result';
+        }
+      }
+
+      const instance = new TestClass();
+      const result = instance.testMethod();
+
+      expect(executionResult).toBe('original method executed');
+      expect(result).toBe('original result');
+      expect(mockProvider.isEnabled).toHaveBeenCalledWith('enabledFeature');
+    });
+
+    it('should execute fallback method when feature is disabled', () => {
+      (mockProvider.isEnabled as jest.Mock).mockReturnValue(false);
+      let executionResult = '';
+
+      function fallbackMethod() {
+        executionResult = 'fallback method executed';
+        return 'fallback result';
+      }
+
+      class TestClass {
+        @FeatureToggle('disabledFeature', fallbackMethod)
+        testMethod() {
+          executionResult = 'original method executed';
+          return 'original result';
+        }
+      }
+
+      const instance = new TestClass();
+      const result = instance.testMethod();
+
+      expect(executionResult).toBe('fallback method executed');
+      expect(result).toBe('fallback result');
+      expect(mockProvider.isEnabled).toHaveBeenCalledWith('disabledFeature');
+    });
+
+    it('should execute empty function when feature is disabled and no fallback provided', () => {
+      (mockProvider.isEnabled as jest.Mock).mockReturnValue(false);
+      let executionResult = '';
+
+      class TestClass {
+        @FeatureToggle('disabledFeature')
+        testMethod() {
+          executionResult = 'original method executed';
+          return 'original result';
+        }
+      }
+
+      const instance = new TestClass();
+      const result = instance.testMethod();
+
+      expect(executionResult).toBe('');
+      expect(result).toBeUndefined();
+    });
+
+    it('should preserve method context (this binding)', () => {
+      (mockProvider.isEnabled as jest.Mock).mockReturnValue(true);
+
+      class TestClass {
+        value = 'test value';
+
+        @FeatureToggle('enabledFeature')
+        getValue() {
+          return this.value;
+        }
+      }
+
+      const instance = new TestClass();
+      const result = instance.getValue();
+
+      expect(result).toBe('test value');
+    });
+
+    it('should handle method arguments correctly', () => {
+      (mockProvider.isEnabled as jest.Mock).mockReturnValue(true);
+
+      class TestClass {
+        @FeatureToggle('enabledFeature')
+        add(a: number, b: number) {
+          return a + b;
+        }
+      }
+
+      const instance = new TestClass();
+      const result = instance.add(5, 3);
+
+      expect(result).toBe(8);
+    });
+
+    it('should handle async methods', async () => {
+      (mockProvider.isEnabled as jest.Mock).mockReturnValue(true);
+
+      class TestClass {
+        @FeatureToggle('enabledFeature')
+        async asyncMethod() {
+          return Promise.resolve('async result');
+        }
+      }
+
+      const instance = new TestClass();
+      const result = await instance.asyncMethod();
+
+      expect(result).toBe('async result');
+    });
+
+    it('should handle async fallback methods', async () => {
+      (mockProvider.isEnabled as jest.Mock).mockReturnValue(false);
+
+      async function asyncFallback() {
+        return Promise.resolve('async fallback result');
+      }
+
+      class TestClass {
+        @FeatureToggle('disabledFeature', asyncFallback)
+        async asyncMethod() {
+          return Promise.resolve('async original result');
+        }
+      }
+
+      const instance = new TestClass();
+      const result = await instance.asyncMethod();
+
+      expect(result).toBe('async fallback result');
+    });
+  });
+
+  describe('Class Decoration', () => {
+    it('should use original class when feature is enabled', () => {
+      (mockProvider.isEnabled as jest.Mock).mockReturnValue(true);
+
+      @FeatureToggle('enabledFeature')
+      class TestClass {
+        value = 'original class';
+        
+        getValue() {
+          return this.value;
+        }
+      }
+
+      const instance = new TestClass();
+      expect(instance.getValue()).toBe('original class');
+      expect(instance instanceof TestClass).toBe(true);
+    });
+
+    it('should use fallback class when feature is disabled', () => {
+      (mockProvider.isEnabled as jest.Mock).mockReturnValue(false);
+
+      class FallbackClass {
+        value = 'fallback class';
+        
+        getValue() {
+          return this.value;
+        }
+      }
+
+      @FeatureToggle('disabledFeature', FallbackClass)
+      class TestClass {
+        value = 'original class';
+        
+        getValue() {
+          return this.value;
+        }
+      }
+
+      const instance = new TestClass();
+      expect(instance.getValue()).toBe('fallback class');
+    });
+
+    it('should use EmptyClass when feature is disabled and no fallback provided', () => {
+      (mockProvider.isEnabled as jest.Mock).mockReturnValue(false);
+
+      @FeatureToggle('disabledFeature')
+      class TestClass {
+        value = 'original class';
+        
+        getValue() {
+          return this.value;
+        }
+
+        async getAsyncValue() {
+          return Promise.resolve(this.value);
+        }
+      }
+
+      const instance = new TestClass();
+      
+      // Should have empty methods
+      expect(instance.getValue()).toBeUndefined();
+      
+      // Should handle async methods
+      expect(instance.getAsyncValue()).toBeInstanceOf(Promise);
+    });
+
+    it('should preserve constructor arguments in fallback class', () => {
+      (mockProvider.isEnabled as jest.Mock).mockReturnValue(false);
+
+      class FallbackClass {
+        constructor(public name: string, public age: number) {}
+        
+        getInfo() {
+          return `${this.name} is ${this.age}`;
+        }
+      }
+
+      @FeatureToggle('disabledFeature', FallbackClass)
+      class TestClass {
+        constructor(public name: string, public age: number) {}
+        
+        getInfo() {
+          return `Original: ${this.name} is ${this.age}`;
+        }
+      }
+
+      const instance = new TestClass('John', 30);
+      expect(instance.getInfo()).toBe('John is 30');
+    });
+
+    it('should handle inheritance in fallback classes', () => {
+      (mockProvider.isEnabled as jest.Mock).mockReturnValue(false);
+
+      class BaseClass {
+        baseMethod() {
+          return 'base method';
+        }
+      }
+
+      class FallbackClass extends BaseClass {
+        fallbackMethod() {
+          return 'fallback method';
+        }
+      }
+
+      @FeatureToggle('disabledFeature', FallbackClass)
+      class TestClass {
+        originalMethod() {
+          return 'original method';
+        }
+      }
+
+      const instance = new TestClass();
+      expect((instance as any).baseMethod()).toBe('base method');
+      expect((instance as any).fallbackMethod()).toBe('fallback method');
+    });
+  });
+
+  describe('Edge Cases and Error Conditions', () => {
+    it('should throw error when FeatureToggleProvider is not set', () => {
+      FeatureToggleBase.featureProvider = null as any;
+
+      expect(() => {
+        class TestClass {
+          @FeatureToggle('anyFeature')
+          testMethod() {}
+        }
+      }).toThrow('FeatureToggleProvider not set');
+    });
+
+    it('should handle provider throwing errors gracefully', () => {
+      (mockProvider.isEnabled as jest.Mock).mockImplementation(() => {
+        throw new Error('Provider error');
+      });
+
+      expect(() => {
+        class TestClass {
+          @FeatureToggle('errorFeature')
+          testMethod() {}
+        }
+      }).toThrow('Provider error');
+    });
+
+    it('should handle undefined/null feature keys', () => {
+      (mockProvider.isEnabled as jest.Mock).mockReturnValue(false);
+
+      class TestClass {
+        @FeatureToggle(undefined as any)
+        testMethod() {
+          return 'should not execute';
+        }
+      }
+
+      const instance = new TestClass();
+      const result = instance.testMethod();
+      
+      expect(result).toBeUndefined();
+      expect(mockProvider.isEnabled).toHaveBeenCalledWith(undefined);
+    });
+
+    it('should handle empty string feature keys', () => {
+      (mockProvider.isEnabled as jest.Mock).mockReturnValue(false);
+
+      class TestClass {
+        @FeatureToggle('')
+        testMethod() {
+          return 'should not execute';
+        }
+      }
+
+      const instance = new TestClass();
+      const result = instance.testMethod();
+      
+      expect(result).toBeUndefined();
+      expect(mockProvider.isEnabled).toHaveBeenCalledWith('');
+    });
+  });
+
+  describe('Multiple Decorators on Same Class/Method', () => {
+    it('should handle multiple method decorators', () => {
+      (mockProvider.isEnabled as jest.Mock)
+        .mockReturnValueOnce(true)  // First feature enabled
+        .mockReturnValueOnce(false); // Second feature disabled
+
+      function fallback() {
+        return 'fallback executed';
+      }
+
+      class TestClass {
+        @FeatureToggle('feature1')
+        @FeatureToggle('feature2', fallback)
+        testMethod() {
+          return 'original executed';
+        }
+      }
+
+      const instance = new TestClass();
+      const result = instance.testMethod();
+
+      // The behavior depends on decorator execution order
+      expect(mockProvider.isEnabled).toHaveBeenCalledTimes(2);
+    });
+  });
+});