@breadstone/archipel-platform-feature-flags 0.0.32

package/README.md

@@ -0,0 +1,10 @@
+# @breadstone/archipel-platform-feature-flags
+
+> Provider-agnostic feature flag infrastructure for NestJS with support for Azure App Configuration and Vercel Edge Config.
+
+## Providers
+
+| Provider                | Subpath Import                                       | SDK                                                                   |
+| ----------------------- | ---------------------------------------------------- | --------------------------------------------------------------------- |
+| Azure App Configuration | `@breadstone/archipel-platform-feature-flags/azure`  | `@azure/app-configuration-provider` + `@microsoft/feature-management` |
+| Vercel Edge Config      | `@breadstone/archipel-platform-feature-flags/vercel` | `@vercel/edge-config`                                                 |

package/package.json

@@ -0,0 +1,100 @@
+{
+  "name": "@breadstone/archipel-platform-feature-flags",
+  "version": "0.0.32",
+  "description": "Provider-agnostic feature flag infrastructure for NestJS with support for Azure App Configuration and Vercel Edge Config.",
+  "type": "commonjs",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "azure": [
+        "./src/azure/index.d.ts"
+      ],
+      "vercel": [
+        "./src/vercel/index.d.ts"
+      ]
+    }
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./azure": {
+      "types": "./src/azure/index.d.ts",
+      "default": "./src/azure/index.js"
+    },
+    "./vercel": {
+      "types": "./src/vercel/index.d.ts",
+      "default": "./src/vercel/index.js"
+    },
+    "./package.json": "./package.json",
+    "./azure/index": "./src/azure/index.js",
+    "./vercel/index": "./src/vercel/index.js"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/RueDeRennes/archipel",
+    "directory": "libs/platform-feature-flags"
+  },
+  "keywords": [
+    "nestjs",
+    "feature-flags",
+    "feature-toggles",
+    "azure",
+    "azure-app-configuration",
+    "vercel",
+    "edge-config",
+    "archipel"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "src/**/*.js",
+    "src/**/*.d.ts",
+    "README.md"
+  ],
+  "dependencies": {
+    "@breadstone/archipel-platform-configuration": "0.0.32",
+    "tslib": "2.8.1"
+  },
+  "peerDependencies": {
+    "@azure/app-configuration": ">=1.8.0",
+    "@azure/app-configuration-provider": ">=2.0.0",
+    "@azure/identity": ">=4.0.0",
+    "@microsoft/feature-management": ">=2.0.0",
+    "@nestjs/common": ">=11.0.0",
+    "@nestjs/core": ">=11.0.0",
+    "@vercel/edge-config": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@azure/app-configuration": {
+      "optional": true
+    },
+    "@azure/app-configuration-provider": {
+      "optional": true
+    },
+    "@azure/identity": {
+      "optional": true
+    },
+    "@microsoft/feature-management": {
+      "optional": true
+    },
+    "@vercel/edge-config": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@azure/app-configuration": "1.11.0",
+    "@azure/app-configuration-provider": "2.4.1",
+    "@azure/identity": "4.13.1",
+    "@microsoft/feature-management": "2.3.1",
+    "@nestjs/common": "11.1.19",
+    "@nestjs/core": "11.1.19",
+    "@vercel/edge-config": "1.4.3",
+    "rxjs": "7.8.2",
+    "vitest": "4.1.5"
+  }
+}

package/src/FeatureFlagModule.d.ts

@@ -0,0 +1,20 @@
+import { type DynamicModule } from '@nestjs/common';
+import type { IFeatureFlagModuleOptions } from './models/IFeatureFlagModuleOptions';
+/**
+ * NestJS module providing feature flag infrastructure.
+ * Exposes a configurable feature flag reader and a route guard.
+ * Optionally exposes a writer port for CRUD operations when `featureFlagWriter` is provided.
+ * The specific provider (Azure App Configuration, Vercel Edge Config) is selected via the options.
+ *
+ * @public
+ */
+export declare class FeatureFlagModule {
+    /**
+     * Configures the module with the specified options.
+     *
+     * @public
+     * @param options - The module configuration options.
+     * @returns Dynamic module definition.
+     */
+    static register(options: IFeatureFlagModuleOptions): DynamicModule;
+}

package/src/FeatureFlagModule.js

@@ -0,0 +1,59 @@
+"use strict";
+// #region Imports
+var FeatureFlagModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FeatureFlagModule = void 0;
+const tslib_1 = require("tslib");
+const archipel_platform_configuration_1 = require("@breadstone/archipel-platform-configuration");
+const common_1 = require("@nestjs/common");
+const FeatureFlagReaderPort_1 = require("./contracts/FeatureFlagReaderPort");
+const FeatureFlagWriterPort_1 = require("./contracts/FeatureFlagWriterPort");
+const FeatureFlagGuard_1 = require("./guards/FeatureFlagGuard");
+// #endregion
+/**
+ * NestJS module providing feature flag infrastructure.
+ * Exposes a configurable feature flag reader and a route guard.
+ * Optionally exposes a writer port for CRUD operations when `featureFlagWriter` is provided.
+ * The specific provider (Azure App Configuration, Vercel Edge Config) is selected via the options.
+ *
+ * @public
+ */
+let FeatureFlagModule = FeatureFlagModule_1 = class FeatureFlagModule {
+    // #region Methods
+    /**
+     * Configures the module with the specified options.
+     *
+     * @public
+     * @param options - The module configuration options.
+     * @returns Dynamic module definition.
+     */
+    static register(options) {
+        const providers = [
+            {
+                provide: FeatureFlagReaderPort_1.FeatureFlagReaderPort,
+                useClass: options.featureFlagReader,
+            },
+            FeatureFlagGuard_1.FeatureFlagGuard,
+        ];
+        const exports = [FeatureFlagReaderPort_1.FeatureFlagReaderPort, FeatureFlagGuard_1.FeatureFlagGuard];
+        if (options.featureFlagWriter) {
+            providers.push({
+                provide: FeatureFlagWriterPort_1.FeatureFlagWriterPort,
+                useClass: options.featureFlagWriter,
+            });
+            exports.push(FeatureFlagWriterPort_1.FeatureFlagWriterPort);
+        }
+        return {
+            global: options.isGlobal ?? true,
+            module: FeatureFlagModule_1,
+            imports: [archipel_platform_configuration_1.ConfigModule.register('platform-feature-flags', options.configEntries ?? [])],
+            providers,
+            exports,
+        };
+    }
+};
+exports.FeatureFlagModule = FeatureFlagModule;
+exports.FeatureFlagModule = FeatureFlagModule = FeatureFlagModule_1 = tslib_1.__decorate([
+    (0, common_1.Module)({})
+], FeatureFlagModule);
+//# sourceMappingURL=FeatureFlagModule.js.map

package/src/azure/AzureFeatureFlagReader.d.ts

@@ -0,0 +1,46 @@
+import { ConfigService } from '@breadstone/archipel-platform-configuration';
+import { type OnModuleDestroy, type OnModuleInit } from '@nestjs/common';
+import { FeatureFlagReaderPort } from '../contracts/FeatureFlagReaderPort';
+import type { IFeatureFlagContext } from '../models/IFeatureFlagContext';
+import type { IFeatureFlagEvaluation } from '../models/IFeatureFlagEvaluation';
+/**
+ * Azure App Configuration implementation of the {@link FeatureFlagReaderPort}.
+ * Uses `@azure/app-configuration-provider` for connecting to Azure App Configuration
+ * and `@microsoft/feature-management` for evaluating feature flags.
+ *
+ * @public
+ */
+export declare class AzureFeatureFlagReader extends FeatureFlagReaderPort implements OnModuleInit, OnModuleDestroy {
+    private readonly _configService;
+    private readonly _logger;
+    private _appConfig;
+    private _featureManager;
+    private _refreshInterval;
+    constructor(configService: ConfigService);
+    /**
+     * Initializes the Azure App Configuration connection and feature manager.
+     *
+     * @public
+     */
+    onModuleInit(): Promise<void>;
+    /**
+     * Cleans up the refresh interval on module destruction.
+     *
+     * @public
+     */
+    onModuleDestroy(): void;
+    /** @inheritdoc */
+    isEnabled(key: string, _context?: IFeatureFlagContext): Promise<boolean>;
+    /** @inheritdoc */
+    getVariant<T = unknown>(key: string, defaultValue: T, _context?: IFeatureFlagContext): Promise<T>;
+    /** @inheritdoc */
+    getAllFlags(_context?: IFeatureFlagContext): Promise<ReadonlyArray<IFeatureFlagEvaluation>>;
+    /** @inheritdoc */
+    refresh(): Promise<void>;
+    /** @inheritdoc */
+    ping(): Promise<boolean>;
+    /**
+     * Ensures the feature manager and app config have been initialized.
+     */
+    private ensureInitialized;
+}

package/src/azure/AzureFeatureFlagReader.js

@@ -0,0 +1,190 @@
+"use strict";
+// #region Imports
+var AzureFeatureFlagReader_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AzureFeatureFlagReader = void 0;
+const tslib_1 = require("tslib");
+const app_configuration_provider_1 = require("@azure/app-configuration-provider");
+const identity_1 = require("@azure/identity");
+const archipel_platform_configuration_1 = require("@breadstone/archipel-platform-configuration");
+const feature_management_1 = require("@microsoft/feature-management");
+const common_1 = require("@nestjs/common");
+const FeatureFlagReaderPort_1 = require("../contracts/FeatureFlagReaderPort");
+const FeatureFlagError_1 = require("../errors/FeatureFlagError");
+const env_1 = require("./env");
+// #endregion
+/** Default refresh interval in milliseconds. */
+const DEFAULT_REFRESH_INTERVAL = 30_000;
+/** Default key filter for feature flags. */
+const DEFAULT_KEY_FILTER = '*';
+/**
+ * Azure App Configuration implementation of the {@link FeatureFlagReaderPort}.
+ * Uses `@azure/app-configuration-provider` for connecting to Azure App Configuration
+ * and `@microsoft/feature-management` for evaluating feature flags.
+ *
+ * @public
+ */
+let AzureFeatureFlagReader = AzureFeatureFlagReader_1 = class AzureFeatureFlagReader extends FeatureFlagReaderPort_1.FeatureFlagReaderPort {
+    // #endregion
+    // #region Ctor
+    constructor(configService) {
+        super();
+        this._logger = new common_1.Logger(AzureFeatureFlagReader_1.name);
+        this._configService = configService;
+    }
+    // #endregion
+    // #region Methods
+    /**
+     * Initializes the Azure App Configuration connection and feature manager.
+     *
+     * @public
+     */
+    async onModuleInit() {
+        try {
+            const endpoint = this._configService.get(env_1.AZURE_APPCONFIG_ENDPOINT.key);
+            const connectionString = this._configService.get(env_1.AZURE_APPCONFIG_CONNECTION_STRING.key);
+            const refreshIntervalInMs = this._configService.get(env_1.AZURE_FEATURE_FLAG_REFRESH_INTERVAL.key) ?? DEFAULT_REFRESH_INTERVAL;
+            const keyFilter = this._configService.get(env_1.AZURE_FEATURE_FLAG_KEY_FILTER.key) ?? DEFAULT_KEY_FILTER;
+            if (!endpoint && !connectionString) {
+                throw new FeatureFlagError_1.FeatureFlagError('azure', 'Either AZURE_APPCONFIG_ENDPOINT or AZURE_APPCONFIG_CONNECTION_STRING must be configured.');
+            }
+            const featureFlagOptions = {
+                enabled: true,
+                selectors: [{ keyFilter }],
+                refresh: {
+                    enabled: true,
+                    refreshIntervalInMs,
+                },
+            };
+            let appConfig;
+            if (endpoint) {
+                const credential = new identity_1.DefaultAzureCredential();
+                appConfig = await (0, app_configuration_provider_1.load)(endpoint, credential, { featureFlagOptions });
+            }
+            else {
+                appConfig = await (0, app_configuration_provider_1.load)(connectionString, { featureFlagOptions });
+            }
+            this._appConfig = appConfig;
+            this._featureManager = new feature_management_1.FeatureManager(new feature_management_1.ConfigurationMapFeatureFlagProvider(appConfig));
+            this._refreshInterval = setInterval(async () => {
+                try {
+                    await this.refresh();
+                }
+                catch (error) {
+                    this._logger.warn('[AzureFeatureFlagReader] Background refresh failed', {
+                        error: error.message,
+                    });
+                }
+            }, refreshIntervalInMs);
+            this._logger.log('[AzureFeatureFlagReader] Initialized successfully');
+        }
+        catch (error) {
+            if (error instanceof FeatureFlagError_1.FeatureFlagError) {
+                throw error;
+            }
+            throw new FeatureFlagError_1.FeatureFlagError('azure', 'Failed to initialize Azure App Configuration', error);
+        }
+    }
+    /**
+     * Cleans up the refresh interval on module destruction.
+     *
+     * @public
+     */
+    onModuleDestroy() {
+        if (this._refreshInterval) {
+            clearInterval(this._refreshInterval);
+            this._refreshInterval = undefined;
+        }
+    }
+    /** @inheritdoc */
+    async isEnabled(key, _context) {
+        this.ensureInitialized();
+        try {
+            return await this._featureManager.isEnabled(key);
+        }
+        catch (error) {
+            this._logger.error(`[AzureFeatureFlagReader] isEnabled failed for flag "${key}"`, {
+                key,
+                error: error.message,
+            });
+            throw new FeatureFlagError_1.FeatureFlagError('azure', `Failed to evaluate feature flag "${key}"`, error);
+        }
+    }
+    /** @inheritdoc */
+    async getVariant(key, defaultValue, _context) {
+        this.ensureInitialized();
+        try {
+            const variant = await this._featureManager.getVariant(key);
+            if (!variant) {
+                return defaultValue;
+            }
+            return variant.configuration ?? defaultValue;
+        }
+        catch (error) {
+            this._logger.error(`[AzureFeatureFlagReader] getVariant failed for flag "${key}"`, {
+                key,
+                error: error.message,
+            });
+            throw new FeatureFlagError_1.FeatureFlagError('azure', `Failed to get variant for feature flag "${key}"`, error);
+        }
+    }
+    /** @inheritdoc */
+    async getAllFlags(_context) {
+        this.ensureInitialized();
+        try {
+            const flags = [];
+            for (const [rawKey] of this._appConfig) {
+                if (!rawKey.startsWith('.appconfig.featureflag/')) {
+                    continue;
+                }
+                const key = rawKey.replace('.appconfig.featureflag/', '');
+                const enabled = await this._featureManager.isEnabled(key);
+                flags.push({ key, enabled });
+            }
+            return flags;
+        }
+        catch (error) {
+            this._logger.error('[AzureFeatureFlagReader] getAllFlags failed', {
+                error: error.message,
+            });
+            throw new FeatureFlagError_1.FeatureFlagError('azure', 'Failed to retrieve all feature flags', error);
+        }
+    }
+    /** @inheritdoc */
+    async refresh() {
+        this.ensureInitialized();
+        try {
+            await this._appConfig.refresh();
+        }
+        catch (error) {
+            this._logger.error('[AzureFeatureFlagReader] refresh failed', {
+                error: error.message,
+            });
+            throw new FeatureFlagError_1.FeatureFlagError('azure', 'Failed to refresh feature flags from Azure App Configuration', error);
+        }
+    }
+    /** @inheritdoc */
+    async ping() {
+        try {
+            await this.refresh();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Ensures the feature manager and app config have been initialized.
+     */
+    ensureInitialized() {
+        if (!this._featureManager || !this._appConfig) {
+            throw new FeatureFlagError_1.FeatureFlagError('azure', 'AzureFeatureFlagReader has not been initialized. Ensure onModuleInit() ran.');
+        }
+    }
+};
+exports.AzureFeatureFlagReader = AzureFeatureFlagReader;
+exports.AzureFeatureFlagReader = AzureFeatureFlagReader = AzureFeatureFlagReader_1 = tslib_1.__decorate([
+    (0, common_1.Injectable)(),
+    tslib_1.__metadata("design:paramtypes", [archipel_platform_configuration_1.ConfigService])
+], AzureFeatureFlagReader);
+//# sourceMappingURL=AzureFeatureFlagReader.js.map

package/src/azure/AzureFeatureFlagWriter.d.ts

@@ -0,0 +1,43 @@
+import { ConfigService } from '@breadstone/archipel-platform-configuration';
+import { type OnModuleInit } from '@nestjs/common';
+import { FeatureFlagWriterPort } from '../contracts/FeatureFlagWriterPort';
+import type { IFeatureFlagDefinition } from '../models/IFeatureFlagDefinition';
+/**
+ * Azure App Configuration implementation of the {@link FeatureFlagWriterPort}.
+ * Uses `@azure/app-configuration` (`AppConfigurationClient`) for CRUD operations
+ * on feature flags stored in Azure App Configuration.
+ *
+ * @public
+ */
+export declare class AzureFeatureFlagWriter extends FeatureFlagWriterPort implements OnModuleInit {
+    private readonly _configService;
+    private readonly _logger;
+    private _client;
+    constructor(configService: ConfigService);
+    /**
+     * Initializes the Azure App Configuration management client.
+     *
+     * @public
+     */
+    onModuleInit(): Promise<void>;
+    /** @inheritdoc */
+    getFlag(key: string): Promise<IFeatureFlagDefinition | undefined>;
+    /** @inheritdoc */
+    listFlags(): Promise<ReadonlyArray<IFeatureFlagDefinition>>;
+    /** @inheritdoc */
+    createFlag(definition: IFeatureFlagDefinition): Promise<void>;
+    /** @inheritdoc */
+    updateFlag(key: string, updates: Partial<Omit<IFeatureFlagDefinition, 'key'>>): Promise<void>;
+    /** @inheritdoc */
+    deleteFlag(key: string): Promise<void>;
+    /** @inheritdoc */
+    ping(): Promise<boolean>;
+    /**
+     * Checks whether the error is a 404 (resource not found).
+     */
+    private isNotFoundError;
+    /**
+     * Ensures the management client has been initialized.
+     */
+    private ensureInitialized;
+}