@application-kit/feature-flags 0.0.0-stage → 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 application-kit
+
+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

@@ -1,3 +1,195 @@
-# Temporary Holding Version
+# @application-kit/feature-flags
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Фичефлаги из окружения: набор флагов объявляет приложение, пакет даёт порт чтения с адаптером окружения,
+SSR-состояние для Vue и фейк для спек. Флагов продукта в пакете нет.
+
+Два правила держат всё остальное:
+
+1. **Имя флага объявляется ровно один раз — в наборе приложения.** Из него выводится тип имени, из него же
+   адаптер узнаёт, какие переменные окружения существуют.
+2. **Состояния «по умолчанию» у флага нет.** Значение каждого флага приходит из окружения, а пропущенная
+   переменная роняет старт процесса. Дефолт в коде сделал бы забытую настройку окружения неотличимой от
+   сознательного выбора — а ищут как раз её, когда стенд ведёт себя не так, как договаривались.
+
+## Установка
+
+```sh
+yarn add @application-kit/feature-flags @libs-for-dev/nestjs-config-module
+```
+
+Peer: `@libs-for-dev/nestjs-config-module` (подпуть `/parse-boolean` — разбор булевых переменных, без
+зависимостей); `vue` — только для входа `/vue`.
+
+## Входы
+
+| Вход | Что внутри | Зависимости |
+|---|---|---|
+| `@application-kit/feature-flags` | `defineFeatureFlags`, реестр `FeatureFlagRegistryInterface`, порт `FeatureFlagsInterface`, токен `FEATURE_FLAGS`, адаптер `EnvironmentFeatureFlags`, ошибки | изоморфно, без Nest и DOM |
+| `@application-kit/feature-flags/vue` | `useFeatureFlag`, ключ `FEATURE_FLAG_STATE`, `parseFeatureFlagState` | `vue` |
+| `@application-kit/feature-flags/testing` | `FakeFeatureFlags` | — |
+
+Корень грузится и в клиентском бандле (набор нужен разбору SSR-состояния), поэтому связки с Nest в пакете нет:
+класс окружения и регистрацию адаптера под токеном делает приложение (пример ниже).
+
+## Набор флагов
+
+Тип и значение объявляются рядом, в одном файле приложения:
+
+```ts
+import { defineFeatureFlags } from '@application-kit/feature-flags'
+
+declare module '@application-kit/feature-flags' {
+  interface FeatureFlagRegistryInterface {
+    NEW_CHECKOUT: true
+  }
+}
+
+export const featureFlags = defineFeatureFlags({
+  NEW_CHECKOUT: { isPublic: true },
+})
+```
+
+Ключи записи проверяются против реестра в обе стороны: флаг реестра без записи и запись без флага в реестре
+не компилируются.
+
+Единственное решение в записи — **`isPublic`**: уезжает ли флаг на клиент в SSR-состоянии. Наружу идёт явный
+список, а не всё состояние: серверный флаг (доступ к интеграции, аварийный рубильник) в разметке страницы — это
+утечка плана работ.
+
+Префикс переменных — опция, по умолчанию `FEATURE_`: `defineFeatureFlags({ … }, { environmentPrefix: 'FLAG_' })`.
+Пустой префикс — `RangeError`.
+
+## Окружение
+
+Имя переменной — префикс плюс имя флага: `FEATURE_NEW_CHECKOUT`. `featureFlags.readEnvironment(source)` разбирает
+окружение в состояние:
+
+| Значение | Результат |
+|---|---|
+| `false`, `0`, пустая строка (регистр и пробелы по краям не важны) | выключен |
+| любая другая непустая строка — `true`, `1`, `on`, `yes` | **включён** |
+| переменной нет | **отказ** — `MissingFeatureFlagError` со списком недостающих переменных |
+| переменная с префиксом, которой нет в наборе | **отказ** — `UnknownFeatureFlagError` со списком |
+
+Разбор значения — `parseBoolean` конфиг-пакета: список выключающих строк один на все булевы переменные. Обе
+проверки собирают полный список до броска, чтобы отказ назвал все проблемы разом; незнакомая переменная
+проверяется первой — опечатка даёт сразу и лишнее имя, и недостающее.
+
+### Связка с Nest (в приложении)
+
+Разбор ставится в класс окружения, чтобы отказ пришёл при сборке графа конфигов, а не на первом запросе:
+
+```ts
+import { EnvironmentFeatureFlags } from '@application-kit/feature-flags'
+
+export class FeatureFlagsEnvironment {
+  @Expose()
+  @IsObject()
+  public FEATURE_FLAGS: FeatureFlagState
+
+  // Конфиг-модуль конструирует класс без аргументов: переменных столько, сколько флагов, и объявлять их
+  // по одной `@Expose()` значило бы держать вторую копию набора.
+  public constructor(source: Record<string, unknown> = process.env) {
+    this.FEATURE_FLAGS = featureFlags.readEnvironment(source)
+  }
+}
+
+export class FeatureFlagsConfig extends EnvironmentFeatureFlags {
+  public constructor(@Inject(FeatureFlagsEnvironment) environment: FeatureFlagsEnvironment) {
+    super(featureFlags, environment.FEATURE_FLAGS)
+  }
+}
+
+// провайдер модуля
+{ provide: FEATURE_FLAGS, useExisting: FeatureFlagsConfig }
+```
+
+## Чтение на сервере
+
+Через порт по токену, а не чтением `process.env`:
+
+```ts
+import type { FeatureFlagsInterface } from '@application-kit/feature-flags'
+import { FEATURE_FLAGS } from '@application-kit/feature-flags'
+
+export class SomeHandler {
+  public constructor(@Inject(FEATURE_FLAGS) private readonly featureFlags: FeatureFlagsInterface) {}
+
+  public execute(): void {
+    if (this.featureFlags.isEnabled('NEW_CHECKOUT')) { /* … */ }
+  }
+}
+```
+
+Чтение синхронное, и это решение: асинхронный `isEnabled` заставил бы ждать каждого потребителя, включая шаблон
+Vue, где `await` в разметке невозможен. Адаптер с хранением в БД остаётся возможным — он держит обновляемый
+снимок в памяти и встаёт под тот же токен без правок потребителей.
+
+## Клиент (Vue)
+
+Публичный срез уезжает на страницу SSR-состоянием:
+
+```ts
+// сервер, перед renderToString
+const state = featureFlagsPort.publicState()
+app.provide(FEATURE_FLAG_STATE, state)
+// … состояние сериализуется в страницу строкой (JSON.stringify)
+
+// клиент, до app.mount()
+app.provide(FEATURE_FLAG_STATE, parseFeatureFlagState(featureFlags, window.ssrFeatureFlags))
+```
+
+В компоненте:
+
+```vue
+<script setup lang="ts">
+import { useFeatureFlag } from '@application-kit/feature-flags/vue'
+
+const isNewCheckoutEnabled = useFeatureFlag('NEW_CHECKOUT')
+</script>
+
+<template>
+  <NewCheckout v-if="isNewCheckoutEnabled" />
+</template>
+```
+
+- Без `provide` всё выключено: до прихода SSR-состояния помеченного фрагмента на странице быть не должно —
+  показать лишнее и убрать при гидрации хуже, чем не показать.
+- Имя, которого нет в предоставленном состоянии, — `UnknownFeatureFlagNameError` со списком известных: имя из
+  данных без проверки дало бы `undefined`, и фрагмент молча исчез бы со страницы.
+- `parseFeatureFlagState` не бросает ни на какой форме испорченного провода: разбор стоит до `app.mount()`, и
+  бросок убил бы весь бутстрап клиента. Незнакомое имя на проводе игнорируется, пропущенное и не-булево —
+  выключено: страница старой версии не роняет клиент новой во время выкатки.
+
+## Тесты потребителя
+
+Через фейк порта, без `process.env` и `vi.stubEnv`. База фейка — «всё выключено», поэтому спека, которой флаг
+нужен включённым, говорит это явно:
+
+```ts
+import { FakeFeatureFlags } from '@application-kit/feature-flags/testing'
+
+const port = new FakeFeatureFlags(featureFlags, { NEW_CHECKOUT: true })
+```
+
+Снимок `publicState()` фейка строится как у адаптера: непубличные флаги в нём выключены. Для компонента —
+`provide` состояния:
+
+```ts
+mount(SomeComponent, {
+  global: { provide: { [FEATURE_FLAG_STATE]: featureFlags.stateOf((name) => name === 'NEW_CHECKOUT') } },
+})
+```
+
+## Типовые отказы
+
+| Симптом | Причина | Что делать |
+|---|---|---|
+| `MissingFeatureFlagError: Missing feature flags in environment: FEATURE_X` на старте | флаг есть в наборе, переменная в окружении не задана | дописать переменную в окружение каждого процесса |
+| `UnknownFeatureFlagError: Unknown feature flags in environment: FEATURE_X` на старте | переменная есть, флага в наборе нет — опечатка или флаг снят из кода и забыт в окружении | поправить имя или убрать переменную |
+| `UnknownFeatureFlagNameError: Unknown feature flag requested: X. Known flags: …` при рендере | опечатка в имени у `useFeatureFlag` | поправить имя по списку в тексте ошибки |
+| Переменная выставлена, а на клиенте флаг выключен | флаг непубличный (`isPublic: false`) | проверить `isPublic` в наборе |
+
+## Чего здесь нет
+
+Адаптера с хранением в БД, процента раскатки, таргетинга по пользователю, UI управления флагами.

package/dist/cjs/constants.d.ts

@@ -0,0 +1 @@
+export declare const FEATURE_FLAGS: unique symbol;

package/dist/cjs/constants.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FEATURE_FLAGS = void 0;
+exports.FEATURE_FLAGS = Symbol('FEATURE_FLAGS');

package/dist/cjs/define-feature-flags.d.ts

@@ -0,0 +1,13 @@
+import type { FeatureFlagDeclaration, FeatureFlagName, FeatureFlagState } from './feature-flag-registry.js';
+export interface FeatureFlagSetInterface {
+    readonly environmentPrefix: string;
+    isKnown(name: string): name is FeatureFlagName;
+    isPublic(name: FeatureFlagName): boolean;
+    readonly names: readonly FeatureFlagName[];
+    readEnvironment(source: Readonly<Record<string, unknown>>): FeatureFlagState;
+    stateOf(isEnabled: (name: FeatureFlagName) => boolean): FeatureFlagState;
+}
+export interface FeatureFlagSetOptionsInterface {
+    readonly environmentPrefix?: string;
+}
+export declare const defineFeatureFlags: (declarations: Readonly<Record<FeatureFlagName, FeatureFlagDeclaration>>, options?: FeatureFlagSetOptionsInterface) => FeatureFlagSetInterface;

package/dist/cjs/define-feature-flags.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineFeatureFlags = void 0;
+const parse_boolean_1 = require("@libs-for-dev/nestjs-config-module/parse-boolean");
+const missing_feature_flag_error_js_1 = require("./errors/missing-feature-flag.error.js");
+const unknown_feature_flag_error_js_1 = require("./errors/unknown-feature-flag.error.js");
+const DEFAULT_ENVIRONMENT_PREFIX = 'FEATURE_';
+const defineFeatureFlags = (declarations, options = {}) => {
+    const environmentPrefix = options.environmentPrefix ?? DEFAULT_ENVIRONMENT_PREFIX;
+    if (environmentPrefix === '') {
+        throw new RangeError('Префикс переменных окружения флагов не может быть пустым');
+    }
+    const isKnown = (name) => Object.hasOwn(declarations, name);
+    const names = Object.keys(declarations);
+    const variableOf = (name) => `${environmentPrefix}${name}`;
+    const publicityByName = new Map(Object.entries(declarations).map(([name, { isPublic }]) => [name, isPublic]));
+    const stateOf = (isEnabled) => Object.fromEntries(names.map((name) => [name, isEnabled(name)]));
+    const readEnvironment = (source) => {
+        const unknownVariables = Object.keys(source)
+            .filter((key) => key.startsWith(environmentPrefix) && !isKnown(key.slice(environmentPrefix.length)));
+        if (unknownVariables.length > 0) {
+            throw new unknown_feature_flag_error_js_1.UnknownFeatureFlagError(unknownVariables);
+        }
+        const missingVariables = names.map((name) => variableOf(name)).filter((variable) => source[variable] === undefined);
+        if (missingVariables.length > 0) {
+            throw new missing_feature_flag_error_js_1.MissingFeatureFlagError(missingVariables);
+        }
+        return stateOf((name) => (0, parse_boolean_1.parseBoolean)(source[variableOf(name)]) ?? false);
+    };
+    return {
+        environmentPrefix,
+        isKnown,
+        isPublic: (name) => publicityByName.get(name) === true,
+        names,
+        readEnvironment,
+        stateOf,
+    };
+};
+exports.defineFeatureFlags = defineFeatureFlags;

package/dist/cjs/environment-feature-flags.d.ts

@@ -0,0 +1,10 @@
+import type { FeatureFlagSetInterface } from './define-feature-flags.js';
+import type { FeatureFlagName, FeatureFlagState } from './feature-flag-registry.js';
+import type { FeatureFlagsInterface } from './feature-flags.interface.js';
+export declare class EnvironmentFeatureFlags implements FeatureFlagsInterface {
+    private readonly featureFlags;
+    private readonly state;
+    constructor(featureFlags: FeatureFlagSetInterface, state: FeatureFlagState);
+    isEnabled(name: FeatureFlagName): boolean;
+    publicState(): FeatureFlagState;
+}

package/dist/cjs/environment-feature-flags.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnvironmentFeatureFlags = void 0;
+class EnvironmentFeatureFlags {
+    featureFlags;
+    state;
+    constructor(featureFlags, state) {
+        this.featureFlags = featureFlags;
+        this.state = state;
+    }
+    isEnabled(name) {
+        return this.state[name];
+    }
+    publicState() {
+        return this.featureFlags.stateOf((name) => this.featureFlags.isPublic(name) && this.state[name]);
+    }
+}
+exports.EnvironmentFeatureFlags = EnvironmentFeatureFlags;

package/dist/cjs/errors/index.d.ts

@@ -0,0 +1,3 @@
+export * from './missing-feature-flag.error.js';
+export * from './unknown-feature-flag-name.error.js';
+export * from './unknown-feature-flag.error.js';

package/dist/cjs/errors/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./missing-feature-flag.error.js"), exports);
+__exportStar(require("./unknown-feature-flag-name.error.js"), exports);
+__exportStar(require("./unknown-feature-flag.error.js"), exports);

package/dist/cjs/errors/missing-feature-flag.error.d.ts

@@ -0,0 +1,3 @@
+export declare class MissingFeatureFlagError extends Error {
+    constructor(missingVariables: readonly string[], options?: ErrorOptions);
+}

package/dist/cjs/errors/missing-feature-flag.error.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MissingFeatureFlagError = void 0;
+class MissingFeatureFlagError extends Error {
+    constructor(missingVariables, options) {
+        super(`Missing feature flags in environment: ${missingVariables.join(', ')}`, options);
+        this.name = 'MissingFeatureFlagError';
+    }
+}
+exports.MissingFeatureFlagError = MissingFeatureFlagError;

package/dist/cjs/errors/unknown-feature-flag-name.error.d.ts

@@ -0,0 +1,3 @@
+export declare class UnknownFeatureFlagNameError extends Error {
+    constructor(requestedName: string, knownNames: readonly string[], options?: ErrorOptions);
+}

package/dist/cjs/errors/unknown-feature-flag-name.error.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnknownFeatureFlagNameError = void 0;
+class UnknownFeatureFlagNameError extends Error {
+    constructor(requestedName, knownNames, options) {
+        super(`Unknown feature flag requested: ${requestedName}. Known flags: ${knownNames.join(', ')}`, options);
+        this.name = 'UnknownFeatureFlagNameError';
+    }
+}
+exports.UnknownFeatureFlagNameError = UnknownFeatureFlagNameError;

package/dist/cjs/errors/unknown-feature-flag.error.d.ts

@@ -0,0 +1,3 @@
+export declare class UnknownFeatureFlagError extends Error {
+    constructor(unknownVariables: readonly string[], options?: ErrorOptions);
+}

package/dist/cjs/errors/unknown-feature-flag.error.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnknownFeatureFlagError = void 0;
+class UnknownFeatureFlagError extends Error {
+    constructor(unknownVariables, options) {
+        super(`Unknown feature flags in environment: ${unknownVariables.join(', ')}`, options);
+        this.name = 'UnknownFeatureFlagError';
+    }
+}
+exports.UnknownFeatureFlagError = UnknownFeatureFlagError;

package/dist/cjs/feature-flag-registry.d.ts

@@ -0,0 +1,7 @@
+export type FeatureFlagDeclaration = Readonly<{
+    isPublic: boolean;
+}>;
+export type FeatureFlagName = Extract<keyof FeatureFlagRegistryInterface, string>;
+export interface FeatureFlagRegistryInterface {
+}
+export type FeatureFlagState = Readonly<Record<FeatureFlagName, boolean>>;

package/dist/cjs/feature-flag-registry.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/feature-flags.interface.d.ts

@@ -0,0 +1,5 @@
+import type { FeatureFlagName, FeatureFlagState } from './feature-flag-registry.js';
+export interface FeatureFlagsInterface {
+    isEnabled(name: FeatureFlagName): boolean;
+    publicState(): FeatureFlagState;
+}

package/dist/cjs/feature-flags.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/index.d.ts

@@ -0,0 +1,6 @@
+export * from './errors/index.js';
+export * from './constants.js';
+export * from './define-feature-flags.js';
+export * from './environment-feature-flags.js';
+export * from './feature-flag-registry.js';
+export * from './feature-flags.interface.js';

package/dist/cjs/index.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./errors/index.js"), exports);
+__exportStar(require("./constants.js"), exports);
+__exportStar(require("./define-feature-flags.js"), exports);
+__exportStar(require("./environment-feature-flags.js"), exports);
+__exportStar(require("./feature-flag-registry.js"), exports);
+__exportStar(require("./feature-flags.interface.js"), exports);

package/dist/cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/dist/cjs/testing/fake-feature-flags.d.ts

@@ -0,0 +1,6 @@
+import type { FeatureFlagSetInterface } from '../define-feature-flags.js';
+import type { FeatureFlagName } from '../feature-flag-registry.js';
+import { EnvironmentFeatureFlags } from '../environment-feature-flags.js';
+export declare class FakeFeatureFlags extends EnvironmentFeatureFlags {
+    constructor(featureFlags: FeatureFlagSetInterface, overrides?: Partial<Record<FeatureFlagName, boolean>>);
+}

package/dist/cjs/testing/fake-feature-flags.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FakeFeatureFlags = void 0;
+const environment_feature_flags_js_1 = require("../environment-feature-flags.js");
+class FakeFeatureFlags extends environment_feature_flags_js_1.EnvironmentFeatureFlags {
+    constructor(featureFlags, overrides = {}) {
+        super(featureFlags, { ...featureFlags.stateOf(() => false), ...overrides });
+    }
+}
+exports.FakeFeatureFlags = FakeFeatureFlags;

package/dist/cjs/testing/index.d.ts

@@ -0,0 +1 @@
+export * from './fake-feature-flags.js';

package/dist/cjs/testing/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./fake-feature-flags.js"), exports);

package/dist/cjs/vue/index.d.ts

@@ -0,0 +1,2 @@
+export * from './parse-feature-flag-state.js';
+export * from './use-feature-flag.js';

package/dist/cjs/vue/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./parse-feature-flag-state.js"), exports);
+__exportStar(require("./use-feature-flag.js"), exports);

package/dist/cjs/vue/parse-feature-flag-state.d.ts

@@ -0,0 +1,3 @@
+import type { FeatureFlagSetInterface } from '../define-feature-flags.js';
+import type { FeatureFlagState } from '../feature-flag-registry.js';
+export declare const parseFeatureFlagState: (featureFlags: FeatureFlagSetInterface, raw: unknown) => FeatureFlagState;

package/dist/cjs/vue/parse-feature-flag-state.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseFeatureFlagState = void 0;
+const parseFeatureFlagState = (featureFlags, raw) => {
+    if (typeof raw !== 'string') {
+        return featureFlags.stateOf(() => false);
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        const state = new Map(Object.entries(parsed ?? {}));
+        return featureFlags.stateOf((name) => state.get(name) === true);
+    }
+    catch {
+        return featureFlags.stateOf(() => false);
+    }
+};
+exports.parseFeatureFlagState = parseFeatureFlagState;

package/dist/cjs/vue/use-feature-flag.d.ts

@@ -0,0 +1,4 @@
+import type { ComputedRef, InjectionKey } from 'vue';
+import type { FeatureFlagName, FeatureFlagState } from '../feature-flag-registry.js';
+export declare const FEATURE_FLAG_STATE: InjectionKey<FeatureFlagState>;
+export declare const useFeatureFlag: (name: FeatureFlagName) => ComputedRef<boolean>;

package/dist/cjs/vue/use-feature-flag.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useFeatureFlag = exports.FEATURE_FLAG_STATE = void 0;
+const vue_1 = require("vue");
+const unknown_feature_flag_name_error_js_1 = require("../errors/unknown-feature-flag-name.error.js");
+exports.FEATURE_FLAG_STATE = Symbol('FEATURE_FLAG_STATE');
+const useFeatureFlag = (name) => {
+    const state = (0, vue_1.inject)(exports.FEATURE_FLAG_STATE, undefined);
+    if (state !== undefined && !Object.hasOwn(state, name)) {
+        throw new unknown_feature_flag_name_error_js_1.UnknownFeatureFlagNameError(name, Object.keys(state));
+    }
+    return (0, vue_1.computed)(() => state?.[name] === true);
+};
+exports.useFeatureFlag = useFeatureFlag;

package/dist/esm/constants.d.ts

@@ -0,0 +1 @@
+export declare const FEATURE_FLAGS: unique symbol;

package/dist/esm/constants.js

@@ -0,0 +1 @@
+export const FEATURE_FLAGS = Symbol('FEATURE_FLAGS');

package/dist/esm/define-feature-flags.d.ts

@@ -0,0 +1,13 @@
+import type { FeatureFlagDeclaration, FeatureFlagName, FeatureFlagState } from './feature-flag-registry.js';
+export interface FeatureFlagSetInterface {
+    readonly environmentPrefix: string;
+    isKnown(name: string): name is FeatureFlagName;
+    isPublic(name: FeatureFlagName): boolean;
+    readonly names: readonly FeatureFlagName[];
+    readEnvironment(source: Readonly<Record<string, unknown>>): FeatureFlagState;
+    stateOf(isEnabled: (name: FeatureFlagName) => boolean): FeatureFlagState;
+}
+export interface FeatureFlagSetOptionsInterface {
+    readonly environmentPrefix?: string;
+}
+export declare const defineFeatureFlags: (declarations: Readonly<Record<FeatureFlagName, FeatureFlagDeclaration>>, options?: FeatureFlagSetOptionsInterface) => FeatureFlagSetInterface;

package/dist/esm/define-feature-flags.js

@@ -0,0 +1,35 @@
+import { parseBoolean } from '@libs-for-dev/nestjs-config-module/parse-boolean';
+import { MissingFeatureFlagError } from './errors/missing-feature-flag.error.js';
+import { UnknownFeatureFlagError } from './errors/unknown-feature-flag.error.js';
+const DEFAULT_ENVIRONMENT_PREFIX = 'FEATURE_';
+export const defineFeatureFlags = (declarations, options = {}) => {
+    const environmentPrefix = options.environmentPrefix ?? DEFAULT_ENVIRONMENT_PREFIX;
+    if (environmentPrefix === '') {
+        throw new RangeError('Префикс переменных окружения флагов не может быть пустым');
+    }
+    const isKnown = (name) => Object.hasOwn(declarations, name);
+    const names = Object.keys(declarations);
+    const variableOf = (name) => `${environmentPrefix}${name}`;
+    const publicityByName = new Map(Object.entries(declarations).map(([name, { isPublic }]) => [name, isPublic]));
+    const stateOf = (isEnabled) => Object.fromEntries(names.map((name) => [name, isEnabled(name)]));
+    const readEnvironment = (source) => {
+        const unknownVariables = Object.keys(source)
+            .filter((key) => key.startsWith(environmentPrefix) && !isKnown(key.slice(environmentPrefix.length)));
+        if (unknownVariables.length > 0) {
+            throw new UnknownFeatureFlagError(unknownVariables);
+        }
+        const missingVariables = names.map((name) => variableOf(name)).filter((variable) => source[variable] === undefined);
+        if (missingVariables.length > 0) {
+            throw new MissingFeatureFlagError(missingVariables);
+        }
+        return stateOf((name) => parseBoolean(source[variableOf(name)]) ?? false);
+    };
+    return {
+        environmentPrefix,
+        isKnown,
+        isPublic: (name) => publicityByName.get(name) === true,
+        names,
+        readEnvironment,
+        stateOf,
+    };
+};

package/dist/esm/environment-feature-flags.d.ts

@@ -0,0 +1,10 @@
+import type { FeatureFlagSetInterface } from './define-feature-flags.js';
+import type { FeatureFlagName, FeatureFlagState } from './feature-flag-registry.js';
+import type { FeatureFlagsInterface } from './feature-flags.interface.js';
+export declare class EnvironmentFeatureFlags implements FeatureFlagsInterface {
+    private readonly featureFlags;
+    private readonly state;
+    constructor(featureFlags: FeatureFlagSetInterface, state: FeatureFlagState);
+    isEnabled(name: FeatureFlagName): boolean;
+    publicState(): FeatureFlagState;
+}

package/dist/esm/environment-feature-flags.js

@@ -0,0 +1,14 @@
+export class EnvironmentFeatureFlags {
+    featureFlags;
+    state;
+    constructor(featureFlags, state) {
+        this.featureFlags = featureFlags;
+        this.state = state;
+    }
+    isEnabled(name) {
+        return this.state[name];
+    }
+    publicState() {
+        return this.featureFlags.stateOf((name) => this.featureFlags.isPublic(name) && this.state[name]);
+    }
+}

package/dist/esm/errors/index.d.ts

@@ -0,0 +1,3 @@
+export * from './missing-feature-flag.error.js';
+export * from './unknown-feature-flag-name.error.js';
+export * from './unknown-feature-flag.error.js';

package/dist/esm/errors/index.js

@@ -0,0 +1,3 @@
+export * from './missing-feature-flag.error.js';
+export * from './unknown-feature-flag-name.error.js';
+export * from './unknown-feature-flag.error.js';

package/dist/esm/errors/missing-feature-flag.error.d.ts

@@ -0,0 +1,3 @@
+export declare class MissingFeatureFlagError extends Error {
+    constructor(missingVariables: readonly string[], options?: ErrorOptions);
+}

package/dist/esm/errors/missing-feature-flag.error.js

@@ -0,0 +1,6 @@
+export class MissingFeatureFlagError extends Error {
+    constructor(missingVariables, options) {
+        super(`Missing feature flags in environment: ${missingVariables.join(', ')}`, options);
+        this.name = 'MissingFeatureFlagError';
+    }
+}

package/dist/esm/errors/unknown-feature-flag-name.error.d.ts

@@ -0,0 +1,3 @@
+export declare class UnknownFeatureFlagNameError extends Error {
+    constructor(requestedName: string, knownNames: readonly string[], options?: ErrorOptions);
+}

package/dist/esm/errors/unknown-feature-flag-name.error.js

@@ -0,0 +1,6 @@
+export class UnknownFeatureFlagNameError extends Error {
+    constructor(requestedName, knownNames, options) {
+        super(`Unknown feature flag requested: ${requestedName}. Known flags: ${knownNames.join(', ')}`, options);
+        this.name = 'UnknownFeatureFlagNameError';
+    }
+}

package/dist/esm/errors/unknown-feature-flag.error.d.ts

@@ -0,0 +1,3 @@
+export declare class UnknownFeatureFlagError extends Error {
+    constructor(unknownVariables: readonly string[], options?: ErrorOptions);
+}

package/dist/esm/errors/unknown-feature-flag.error.js

@@ -0,0 +1,6 @@
+export class UnknownFeatureFlagError extends Error {
+    constructor(unknownVariables, options) {
+        super(`Unknown feature flags in environment: ${unknownVariables.join(', ')}`, options);
+        this.name = 'UnknownFeatureFlagError';
+    }
+}

package/dist/esm/feature-flag-registry.d.ts

@@ -0,0 +1,7 @@
+export type FeatureFlagDeclaration = Readonly<{
+    isPublic: boolean;
+}>;
+export type FeatureFlagName = Extract<keyof FeatureFlagRegistryInterface, string>;
+export interface FeatureFlagRegistryInterface {
+}
+export type FeatureFlagState = Readonly<Record<FeatureFlagName, boolean>>;

package/dist/esm/feature-flag-registry.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/feature-flags.interface.d.ts

@@ -0,0 +1,5 @@
+import type { FeatureFlagName, FeatureFlagState } from './feature-flag-registry.js';
+export interface FeatureFlagsInterface {
+    isEnabled(name: FeatureFlagName): boolean;
+    publicState(): FeatureFlagState;
+}

package/dist/esm/feature-flags.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/index.d.ts

@@ -0,0 +1,6 @@
+export * from './errors/index.js';
+export * from './constants.js';
+export * from './define-feature-flags.js';
+export * from './environment-feature-flags.js';
+export * from './feature-flag-registry.js';
+export * from './feature-flags.interface.js';

package/dist/esm/index.js

@@ -0,0 +1,6 @@
+export * from './errors/index.js';
+export * from './constants.js';
+export * from './define-feature-flags.js';
+export * from './environment-feature-flags.js';
+export * from './feature-flag-registry.js';
+export * from './feature-flags.interface.js';

package/dist/esm/testing/fake-feature-flags.d.ts

@@ -0,0 +1,6 @@
+import type { FeatureFlagSetInterface } from '../define-feature-flags.js';
+import type { FeatureFlagName } from '../feature-flag-registry.js';
+import { EnvironmentFeatureFlags } from '../environment-feature-flags.js';
+export declare class FakeFeatureFlags extends EnvironmentFeatureFlags {
+    constructor(featureFlags: FeatureFlagSetInterface, overrides?: Partial<Record<FeatureFlagName, boolean>>);
+}

package/dist/esm/testing/fake-feature-flags.js

@@ -0,0 +1,6 @@
+import { EnvironmentFeatureFlags } from '../environment-feature-flags.js';
+export class FakeFeatureFlags extends EnvironmentFeatureFlags {
+    constructor(featureFlags, overrides = {}) {
+        super(featureFlags, { ...featureFlags.stateOf(() => false), ...overrides });
+    }
+}

package/dist/esm/testing/index.d.ts

@@ -0,0 +1 @@
+export * from './fake-feature-flags.js';

package/dist/esm/testing/index.js

@@ -0,0 +1 @@
+export * from './fake-feature-flags.js';

package/dist/esm/vue/index.d.ts

@@ -0,0 +1,2 @@
+export * from './parse-feature-flag-state.js';
+export * from './use-feature-flag.js';

package/dist/esm/vue/index.js

@@ -0,0 +1,2 @@
+export * from './parse-feature-flag-state.js';
+export * from './use-feature-flag.js';

package/dist/esm/vue/parse-feature-flag-state.d.ts

@@ -0,0 +1,3 @@
+import type { FeatureFlagSetInterface } from '../define-feature-flags.js';
+import type { FeatureFlagState } from '../feature-flag-registry.js';
+export declare const parseFeatureFlagState: (featureFlags: FeatureFlagSetInterface, raw: unknown) => FeatureFlagState;

package/dist/esm/vue/parse-feature-flag-state.js

@@ -0,0 +1,13 @@
+export const parseFeatureFlagState = (featureFlags, raw) => {
+    if (typeof raw !== 'string') {
+        return featureFlags.stateOf(() => false);
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        const state = new Map(Object.entries(parsed ?? {}));
+        return featureFlags.stateOf((name) => state.get(name) === true);
+    }
+    catch {
+        return featureFlags.stateOf(() => false);
+    }
+};

package/dist/esm/vue/use-feature-flag.d.ts

@@ -0,0 +1,4 @@
+import type { ComputedRef, InjectionKey } from 'vue';
+import type { FeatureFlagName, FeatureFlagState } from '../feature-flag-registry.js';
+export declare const FEATURE_FLAG_STATE: InjectionKey<FeatureFlagState>;
+export declare const useFeatureFlag: (name: FeatureFlagName) => ComputedRef<boolean>;

package/dist/esm/vue/use-feature-flag.js

@@ -0,0 +1,10 @@
+import { computed, inject } from 'vue';
+import { UnknownFeatureFlagNameError } from '../errors/unknown-feature-flag-name.error.js';
+export const FEATURE_FLAG_STATE = Symbol('FEATURE_FLAG_STATE');
+export const useFeatureFlag = (name) => {
+    const state = inject(FEATURE_FLAG_STATE, undefined);
+    if (state !== undefined && !Object.hasOwn(state, name)) {
+        throw new UnknownFeatureFlagNameError(name, Object.keys(state));
+    }
+    return computed(() => state?.[name] === true);
+};

package/package.json

@@ -1,6 +1,94 @@
 {
   "name": "@application-kit/feature-flags",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.0",
+  "description": "Фичефлаги из окружения: набор флагов параметром, порт с адаптером окружения, SSR-состояние для Vue и фейк для спек",
+  "keywords": [
+    "feature-flags",
+    "feature-toggles",
+    "ssr",
+    "vue"
+  ],
+  "homepage": "https://gitlab.com/application-kit/application-kit/-/tree/main/packages/feature-flags",
+  "bugs": "https://gitlab.com/application-kit/application-kit/-/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.com/application-kit/application-kit.git",
+    "directory": "packages/feature-flags"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "application-kit"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./package.json": "./package.json",
+    "./testing": {
+      "import": {
+        "types": "./dist/esm/testing/index.d.ts",
+        "default": "./dist/esm/testing/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/testing/index.d.ts",
+        "default": "./dist/cjs/testing/index.js"
+      }
+    },
+    "./vue": {
+      "import": {
+        "types": "./dist/esm/vue/index.d.ts",
+        "default": "./dist/esm/vue/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/vue/index.d.ts",
+        "default": "./dist/cjs/vue/index.js"
+      }
+    }
+  },
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/cjs/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "rm -rf ./dist && node ../../scripts/barrels.mjs create ./src --entry-only=testing,vue && tsc --project tsconfig.build.json && tsc --project tsconfig.build.cjs.json && node ../../scripts/barrels.mjs clean ./src && node ../../scripts/mark-cjs.mjs ./dist/cjs",
+    "lint:tsc": "tsc --noEmit --pretty --project .",
+    "test:mutation": "stryker run",
+    "test:unit": "vitest run"
+  },
+  "devDependencies": {
+    "@libs-for-dev/nestjs-config-module": "3.0.0",
+    "@stryker-mutator/core": "^10.0.0",
+    "@stryker-mutator/vitest-runner": "^10.0.0",
+    "@types/node": "^26.2.0",
+    "jsdom": "^30.0.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.11",
+    "vue": "^3.5.41"
+  },
+  "peerDependencies": {
+    "@libs-for-dev/nestjs-config-module": "^3.0.0",
+    "vue": "^3.5.0"
+  },
+  "peerDependenciesMeta": {
+    "vue": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
 }