@application-kit/feature-flags 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @application-kit/feature-flags
 
+## 0.3.0
+
+### Minor Changes
+
+- 1032c06: Вход `/nest`: `FeatureFlagsRootModule.forRoot(featureFlags)` разбирает окружение и глобально отдаёт порт `FEATURE_FLAGS`. Класс окружения и конфиг-адаптер в приложении больше не нужны; отказы на неверном `FEATURE_*` прежние. Новый необязательный peer `@nestjs/common` — только для этого входа.
+
+## 0.2.0
+
+### Minor Changes
+
+- 2a51c82: Каналы значений «сервер → клиент». `vue-ssr`: опция `channels` у `createSsrEntry` и `hydrateSsrApplication`, контракт `SsrChannelInterface`, `PiniaPlugin`. Ломает: `describePage` заменена на `resolveLang`, значения `window.*` идут только каналами; `channels` обязательна у обеих функций, `beforeMount` стал необязательным. `i18n/vue`: `createLocaleChannel`. `feature-flags/vue`: `createFeatureFlagChannel`.
+
 ## 0.1.0
 
 ### Minor Changes

package/README.md

@@ -18,18 +18,18 @@ yarn add @application-kit/feature-flags @libs-for-dev/nestjs-config-module
 ```
 
 Peer: `@libs-for-dev/nestjs-config-module` (подпуть `/parse-boolean` — разбор булевых переменных, без
-зависимостей); `vue` — только для входа `/vue`.
+зависимостей); `vue` — только для входа `/vue`, `@nestjs/common` — только для входа `/nest`.
 
 ## Входы
 
 | Вход | Что внутри | Зависимости |
 |---|---|---|
 | `@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/nest` | `FeatureFlagsRootModule` | `@nestjs/common` |
+| `@application-kit/feature-flags/vue` | `useFeatureFlag`, ключ `FEATURE_FLAG_STATE`, `parseFeatureFlagState`, `createFeatureFlagChannel` | `vue` |
 | `@application-kit/feature-flags/testing` | `FakeFeatureFlags` | — |
 
-Корень грузится и в клиентском бандле (набор нужен разбору SSR-состояния), поэтому связки с Nest в пакете нет:
-класс окружения и регистрацию адаптера под токеном делает приложение (пример ниже).
+Корень грузится и в клиентском бандле (набор нужен разбору SSR-состояния), поэтому связка с Nest — отдельный вход.
 
 ## Набор флагов
 
@@ -75,35 +75,21 @@ export const featureFlags = defineFeatureFlags({
 проверки собирают полный список до броска, чтобы отказ назвал все проблемы разом; незнакомая переменная
 проверяется первой — опечатка даёт сразу и лишнее имя, и недостающее.
 
-### Связка с Nest (в приложении)
+### Связка с Nest
 
-Разбор ставится в класс окружения, чтобы отказ пришёл при сборке графа конфигов, а не на первом запросе:
+Корневой модуль процесса подключает порт одной строкой:
 
 ```ts
-import { EnvironmentFeatureFlags } from '@application-kit/feature-flags'
+import { FeatureFlagsRootModule } from '@application-kit/feature-flags/nest'
 
-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 }
+@Module({ imports: [FeatureFlagsRootModule.forRoot(featureFlags)] })
+export class CommonModule {}
 ```
 
+`forRoot` разбирает `process.env` сразу, на импорте модуля-носителя: отказ приходит до сборки графа, а не на первом
+запросе. Поэтому окружение обязано быть готово до импорта: правка из `beforeAll` спеки опоздает. Модуль глобальный:
+`FEATURE_FLAGS` виден всему графу без своей регистрации.
+
 ## Чтение на сервере
 
 Через порт по токену, а не чтением `process.env`:
@@ -129,6 +115,20 @@ Vue, где `await` в разметке невозможен. Адаптер с
 
 Публичный срез уезжает на страницу SSR-состоянием:
 
+С `@application-kit/vue-ssr` состояние едет каналом — ставится до рендера и уезжает на страницу одним значением:
+
+```ts
+const featureFlagChannel = createFeatureFlagChannel(featureFlags)
+
+// сервер, опция createSsrEntry
+channels: () => [featureFlagChannel.withValue(featureFlagsPort.publicState())],
+
+// клиент, опция hydrateSsrApplication
+channels: [featureFlagChannel],
+```
+
+Без него — те же шаги руками:
+
 ```ts
 // сервер, перед renderToString
 const state = featureFlagsPort.publicState()

package/dist/cjs/nest/feature-flags-root.module.d.ts

@@ -0,0 +1,5 @@
+import type { DynamicModule } from '@nestjs/common';
+import type { FeatureFlagSetInterface } from '../define-feature-flags.js';
+export declare class FeatureFlagsRootModule {
+    static forRoot(featureFlags: FeatureFlagSetInterface): DynamicModule;
+}

package/dist/cjs/nest/feature-flags-root.module.js

@@ -0,0 +1,27 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FeatureFlagsRootModule = void 0;
+const common_1 = require("@nestjs/common");
+const constants_js_1 = require("../constants.js");
+const environment_feature_flags_js_1 = require("../environment-feature-flags.js");
+let FeatureFlagsRootModule = class FeatureFlagsRootModule {
+    static forRoot(featureFlags) {
+        const state = featureFlags.readEnvironment(process.env);
+        return {
+            exports: [constants_js_1.FEATURE_FLAGS],
+            global: true,
+            module: this,
+            providers: [{ provide: constants_js_1.FEATURE_FLAGS, useValue: new environment_feature_flags_js_1.EnvironmentFeatureFlags(featureFlags, state) }],
+        };
+    }
+};
+exports.FeatureFlagsRootModule = FeatureFlagsRootModule;
+exports.FeatureFlagsRootModule = FeatureFlagsRootModule = __decorate([
+    (0, common_1.Module)({})
+], FeatureFlagsRootModule);

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

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

package/dist/cjs/nest/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("./feature-flags-root.module.js"), exports);

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

@@ -0,0 +1,14 @@
+import type { App } from 'vue';
+import type { FeatureFlagSetInterface } from '../define-feature-flags.js';
+import type { FeatureFlagState } from '../feature-flag-registry.js';
+export interface FeatureFlagChannelInterface {
+    readonly key: string;
+    restore(app: App, serialized: string | undefined): void;
+    withValue(state: FeatureFlagState): FeatureFlagChannelValueInterface;
+}
+export interface FeatureFlagChannelValueInterface {
+    apply(app: App): void;
+    readonly key: string;
+    readonly serialized: string;
+}
+export declare const createFeatureFlagChannel: (featureFlags: FeatureFlagSetInterface) => FeatureFlagChannelInterface;

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

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createFeatureFlagChannel = void 0;
+const parse_feature_flag_state_js_1 = require("./parse-feature-flag-state.js");
+const use_feature_flag_js_1 = require("./use-feature-flag.js");
+const FEATURE_FLAG_CHANNEL_KEY = 'ssrFeatureFlags';
+const createFeatureFlagChannel = (featureFlags) => ({
+    key: FEATURE_FLAG_CHANNEL_KEY,
+    restore: (app, serialized) => {
+        app.provide(use_feature_flag_js_1.FEATURE_FLAG_STATE, (0, parse_feature_flag_state_js_1.parseFeatureFlagState)(featureFlags, serialized));
+    },
+    withValue: (state) => ({
+        apply: (app) => {
+            app.provide(use_feature_flag_js_1.FEATURE_FLAG_STATE, state);
+        },
+        key: FEATURE_FLAG_CHANNEL_KEY,
+        serialized: JSON.stringify(state),
+    }),
+});
+exports.createFeatureFlagChannel = createFeatureFlagChannel;

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

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

package/dist/cjs/vue/index.js

@@ -14,5 +14,6 @@ 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("./feature-flag-channel.js"), exports);
 __exportStar(require("./parse-feature-flag-state.js"), exports);
 __exportStar(require("./use-feature-flag.js"), exports);

package/dist/esm/nest/feature-flags-root.module.d.ts

@@ -0,0 +1,5 @@
+import type { DynamicModule } from '@nestjs/common';
+import type { FeatureFlagSetInterface } from '../define-feature-flags.js';
+export declare class FeatureFlagsRootModule {
+    static forRoot(featureFlags: FeatureFlagSetInterface): DynamicModule;
+}

package/dist/esm/nest/feature-flags-root.module.js

@@ -0,0 +1,24 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { Module } from '@nestjs/common';
+import { FEATURE_FLAGS } from '../constants.js';
+import { EnvironmentFeatureFlags } from '../environment-feature-flags.js';
+let FeatureFlagsRootModule = class FeatureFlagsRootModule {
+    static forRoot(featureFlags) {
+        const state = featureFlags.readEnvironment(process.env);
+        return {
+            exports: [FEATURE_FLAGS],
+            global: true,
+            module: this,
+            providers: [{ provide: FEATURE_FLAGS, useValue: new EnvironmentFeatureFlags(featureFlags, state) }],
+        };
+    }
+};
+FeatureFlagsRootModule = __decorate([
+    Module({})
+], FeatureFlagsRootModule);
+export { FeatureFlagsRootModule };

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

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

package/dist/esm/nest/index.js

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

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

@@ -0,0 +1,14 @@
+import type { App } from 'vue';
+import type { FeatureFlagSetInterface } from '../define-feature-flags.js';
+import type { FeatureFlagState } from '../feature-flag-registry.js';
+export interface FeatureFlagChannelInterface {
+    readonly key: string;
+    restore(app: App, serialized: string | undefined): void;
+    withValue(state: FeatureFlagState): FeatureFlagChannelValueInterface;
+}
+export interface FeatureFlagChannelValueInterface {
+    apply(app: App): void;
+    readonly key: string;
+    readonly serialized: string;
+}
+export declare const createFeatureFlagChannel: (featureFlags: FeatureFlagSetInterface) => FeatureFlagChannelInterface;

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

@@ -0,0 +1,16 @@
+import { parseFeatureFlagState } from './parse-feature-flag-state.js';
+import { FEATURE_FLAG_STATE } from './use-feature-flag.js';
+const FEATURE_FLAG_CHANNEL_KEY = 'ssrFeatureFlags';
+export const createFeatureFlagChannel = (featureFlags) => ({
+    key: FEATURE_FLAG_CHANNEL_KEY,
+    restore: (app, serialized) => {
+        app.provide(FEATURE_FLAG_STATE, parseFeatureFlagState(featureFlags, serialized));
+    },
+    withValue: (state) => ({
+        apply: (app) => {
+            app.provide(FEATURE_FLAG_STATE, state);
+        },
+        key: FEATURE_FLAG_CHANNEL_KEY,
+        serialized: JSON.stringify(state),
+    }),
+});

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

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

package/dist/esm/vue/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@application-kit/feature-flags",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Фичефлаги из окружения: набор флагов параметром, порт с адаптером окружения, SSR-состояние для Vue и фейк для спек",
   "keywords": [
     "feature-flags",
@@ -32,6 +32,16 @@
         "default": "./dist/cjs/index.js"
       }
     },
+    "./nest": {
+      "import": {
+        "types": "./dist/esm/nest/index.d.ts",
+        "default": "./dist/esm/nest/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/nest/index.d.ts",
+        "default": "./dist/cjs/nest/index.js"
+      }
+    },
     "./package.json": "./package.json",
     "./testing": {
       "import": {
@@ -61,13 +71,15 @@
     "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",
+    "build": "rm -rf ./dist && node ../../scripts/barrels.mjs create ./src --entry-only=nest,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",
+    "@nestjs/common": "^11.2.7",
+    "@nestjs/testing": "^11.2.7",
     "@stryker-mutator/core": "^10.0.0",
     "@stryker-mutator/vitest-runner": "^10.0.0",
     "@types/node": "^26.2.0",
@@ -78,9 +90,13 @@
   },
   "peerDependencies": {
     "@libs-for-dev/nestjs-config-module": "^3.0.0",
+    "@nestjs/common": "^11.0.0",
     "vue": "^3.5.0"
   },
   "peerDependenciesMeta": {
+    "@nestjs/common": {
+      "optional": true
+    },
     "vue": {
       "optional": true
     }