@nexusts/feature-flag 0.8.0

package/README.md

@@ -0,0 +1,50 @@
+# `@nexusts/feature-flag`
+
+Feature flags, canary deployments, and A/B testing for NexusTS.
+
+## Install
+
+```bash
+bun add @nexusts/feature-flag
+```
+
+## Quick start
+
+```ts
+import { FeatureFlagModule, FeatureFlagService, FeatureFlag } from '@nexusts/feature-flag';
+
+@Module({
+  imports: [
+    FeatureFlagModule.forRoot({
+      flags: {
+        'new-dashboard': { enabled: true, rollout: 0.5 },
+        'beta-api':      false,
+      },
+    }),
+  ],
+})
+class AppModule {}
+
+// In a controller:
+const showBeta = await flags.isEnabled('new-checkout', { userId: 'u-1' });
+
+// Or as a decorator:
+@FeatureFlag('new-dashboard')
+async index() { ... }
+```
+
+## API
+
+| Method | Description |
+| ------ | ----------- |
+| `isEnabled(flag, context?)` | `Promise<boolean>` — `true` if the flag is active |
+| `setFlag(name, definition)` | Add or update a flag at runtime |
+| `getFlag(name)` | Return the current definition |
+
+Flag evaluation order: `denylist` → `allowlist` → `enabled: false` →
+`rollout` (djb2 hash) → default.
+
+## Links
+
+- [User guide](../../docs/user-guide/feature-flags.md)
+- [NestJS comparison — feature flags](../../docs/analysis/nestjs-comparison.md)

package/dist/backends/index.d.ts

@@ -0,0 +1 @@
+export { MemoryFlagBackend } from "./memory.js";

package/dist/backends/memory.d.ts

@@ -0,0 +1,9 @@
+import type { FlagContext, FlagDefinition, FeatureFlagBackend } from "../types.js";
+/** In-process feature flag backend — no external dependencies. */
+export declare class MemoryFlagBackend implements FeatureFlagBackend {
+    #private;
+    constructor(initial?: Record<string, FlagDefinition | boolean>);
+    setFlag(flagName: string, definition: FlagDefinition | boolean): void;
+    getFlag(flagName: string): FlagDefinition | undefined;
+    isEnabled(flagName: string, context?: FlagContext): Promise<boolean>;
+}

package/dist/decorators/feature-flag.decorator.d.ts

@@ -0,0 +1,28 @@
+import "reflect-metadata";
+import type { FlagContext } from "../types.js";
+export interface FeatureFlagOptions {
+    /** Extract a `FlagContext` from the Hono `Context` object (first arg of the handler). */
+    contextFn?: (c: any) => FlagContext;
+    /** Custom response when the flag is disabled. Defaults to 404 JSON. */
+    onDisabled?: (c: any) => Response | Promise<Response>;
+}
+export interface FlagSpec {
+    propertyKey: string | symbol;
+    flagName: string;
+    contextFn?: (c: any) => FlagContext;
+    onDisabled?: (c: any) => Response | Promise<Response>;
+    original: (...args: any[]) => any;
+}
+/**
+ * Mark a route handler so `FeatureFlagService.applyDecorators()` will gate it.
+ *
+ *   @Get('/')
+ *   @FeatureFlag('new-dashboard')
+ *   async index(c: Context) { ... }
+ *
+ * When the flag is disabled the handler returns a 404 JSON response.
+ * Pass `onDisabled` to customise the response, or `contextFn` to extract
+ * a `FlagContext` (userId etc.) from the Hono `Context`.
+ */
+export declare function FeatureFlag(flagName: string, options?: FeatureFlagOptions): MethodDecorator;
+export declare function getFlagSpecs(target: any): FlagSpec[];

package/dist/decorators/index.d.ts

@@ -0,0 +1,2 @@
+export { FeatureFlag, getFlagSpecs } from "./feature-flag.decorator.js";
+export type { FlagSpec, FeatureFlagOptions } from "./feature-flag.decorator.js";

package/dist/feature-flag.module.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `FeatureFlagModule` — drop-in feature flags.
+ *
+ *   @Module({
+ *     imports: [
+ *       FeatureFlagModule.forRoot({
+ *         flags: {
+ *           'new-dashboard': { enabled: true, rollout: 0.5 },
+ *           'beta-api':      false,
+ *         },
+ *       }),
+ *     ],
+ *   })
+ *   export class AppModule {}
+ */
+import "reflect-metadata";
+import type { FeatureFlagConfig } from "./types.js";
+export declare class FeatureFlagModule {
+    static forRoot(config?: FeatureFlagConfig): {
+        new (): {};
+    };
+}

package/dist/feature-flag.service.d.ts

@@ -0,0 +1,22 @@
+import type { FlagContext, FlagDefinition, FeatureFlagConfig } from "./types.js";
+export declare class FeatureFlagService {
+    #private;
+    /** DI token. */
+    static readonly TOKEN: unique symbol;
+    constructor(config?: FeatureFlagConfig);
+    /** Returns `true` if the flag is enabled for the given context. */
+    isEnabled(flagName: string, context?: FlagContext): Promise<boolean>;
+    /** Create or update a flag at runtime. */
+    setFlag(flagName: string, definition: FlagDefinition | boolean): void;
+    /** Return the raw definition (or `undefined` if unknown). */
+    getFlag(flagName: string): FlagDefinition | undefined;
+    /**
+     * Wire `@FeatureFlag` decorators onto a controller or service instance.
+     * Each decorated route handler is wrapped so it returns a 404 JSON
+     * response when the flag is disabled.
+     *
+     * The DI container calls this automatically when FeatureFlagModule is
+     * imported; you can also call it manually in tests.
+     */
+    applyDecorators(target: any): void;
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Public entry point for `@nexusts/feature-flag`.
+ */
+export { FeatureFlagModule } from "./feature-flag.module.js";
+export { FeatureFlagService } from "./feature-flag.service.js";
+export { MemoryFlagBackend } from "./backends/index.js";
+export { FeatureFlag, getFlagSpecs } from "./decorators/index.js";
+export type { FlagSpec, FeatureFlagOptions } from "./decorators/index.js";
+export type { FlagContext, FlagDefinition, FeatureFlagConfig, FeatureFlagBackend, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,167 @@
+// @bun
+var __legacyDecorateClassTS = 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;
+};
+var __legacyDecorateParamTS = (index, decorator) => (target, key) => decorator(target, key, index);
+var __legacyMetadataTS = (k, v) => {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function")
+    return Reflect.metadata(k, v);
+};
+
+// packages/feature-flag/src/feature-flag.module.ts
+import"reflect-metadata";
+import { Module } from "@nexusts/core";
+
+// packages/feature-flag/src/feature-flag.service.ts
+import { Inject, Injectable } from "@nexusts/core";
+
+// packages/feature-flag/src/backends/memory.ts
+function hashFloat(s) {
+  let h = 5381;
+  for (let i = 0;i < s.length; i++) {
+    h = Math.imul(h, 33) ^ s.charCodeAt(i);
+  }
+  return (h >>> 0) / 4294967295;
+}
+
+class MemoryFlagBackend {
+  #flags = new Map;
+  constructor(initial = {}) {
+    for (const [k, v] of Object.entries(initial)) {
+      this.#flags.set(k, typeof v === "boolean" ? { enabled: v } : v);
+    }
+  }
+  setFlag(flagName, definition) {
+    this.#flags.set(flagName, typeof definition === "boolean" ? { enabled: definition } : definition);
+  }
+  getFlag(flagName) {
+    return this.#flags.get(flagName);
+  }
+  async isEnabled(flagName, context) {
+    const def = this.#flags.get(flagName);
+    if (!def)
+      return false;
+    const id = context?.userId ?? context?.tenantId ?? context?.key ?? "";
+    if (id && def.denylist?.includes(id))
+      return false;
+    if (id && def.allowlist?.includes(id))
+      return true;
+    if (def.enabled === false)
+      return false;
+    if (def.rollout !== undefined && def.rollout < 1) {
+      if (!id)
+        return def.rollout > 0;
+      return hashFloat(`${flagName}:${id}`) < def.rollout;
+    }
+    return def.enabled !== false;
+  }
+}
+
+// packages/feature-flag/src/decorators/feature-flag.decorator.ts
+import"reflect-metadata";
+var FLAG_META = Symbol.for("nexus:FeatureFlag");
+function FeatureFlag(flagName, options = {}) {
+  return (target, propertyKey, descriptor) => {
+    const specs = Reflect.getMetadata(FLAG_META, target.constructor) ?? [];
+    specs.push({
+      propertyKey,
+      flagName,
+      contextFn: options.contextFn,
+      onDisabled: options.onDisabled,
+      original: descriptor.value
+    });
+    Reflect.defineMetadata(FLAG_META, specs, target.constructor);
+  };
+}
+function getFlagSpecs(target) {
+  return Reflect.getMetadata(FLAG_META, target) ?? [];
+}
+
+// packages/feature-flag/src/feature-flag.service.ts
+class FeatureFlagService {
+  static TOKEN = Symbol.for("nexus:FeatureFlagService");
+  #backend;
+  constructor(config = {}) {
+    this.#backend = new MemoryFlagBackend(config.flags ?? {});
+  }
+  async isEnabled(flagName, context) {
+    return this.#backend.isEnabled(flagName, context);
+  }
+  setFlag(flagName, definition) {
+    this.#backend.setFlag(flagName, definition);
+  }
+  getFlag(flagName) {
+    return this.#backend.getFlag(flagName);
+  }
+  applyDecorators(target) {
+    const specs = getFlagSpecs(target.constructor);
+    for (const spec of specs) {
+      const original = spec.original;
+      target[spec.propertyKey] = async (c, ...rest) => {
+        const ctx = spec.contextFn ? spec.contextFn(c) : undefined;
+        const enabled = await this.isEnabled(spec.flagName, ctx);
+        if (!enabled) {
+          if (spec.onDisabled)
+            return spec.onDisabled(c);
+          return c.json({ message: "Feature not available", code: "FEATURE_DISABLED" }, 404);
+        }
+        return original.apply(target, [c, ...rest]);
+      };
+    }
+  }
+}
+FeatureFlagService = __legacyDecorateClassTS([
+  Injectable(),
+  __legacyDecorateParamTS(0, Inject("FEATURE_FLAG_CONFIG")),
+  __legacyMetadataTS("design:paramtypes", [
+    typeof FeatureFlagConfig === "undefined" ? Object : FeatureFlagConfig
+  ])
+], FeatureFlagService);
+
+// packages/feature-flag/src/feature-flag.module.ts
+class FeatureFlagModule {
+  static forRoot(config = {}) {
+    class ConfiguredFeatureFlagModule {
+    }
+    ConfiguredFeatureFlagModule = __legacyDecorateClassTS([
+      Module({
+        providers: [
+          FeatureFlagService,
+          { provide: FeatureFlagService.TOKEN, useExisting: FeatureFlagService },
+          { provide: "FEATURE_FLAG_CONFIG", useValue: config }
+        ],
+        exports: [FeatureFlagService, FeatureFlagService.TOKEN]
+      })
+    ], ConfiguredFeatureFlagModule);
+    Object.defineProperty(ConfiguredFeatureFlagModule, "name", {
+      value: "ConfiguredFeatureFlagModule"
+    });
+    return ConfiguredFeatureFlagModule;
+  }
+}
+FeatureFlagModule = __legacyDecorateClassTS([
+  Module({
+    providers: [
+      FeatureFlagService,
+      { provide: FeatureFlagService.TOKEN, useExisting: FeatureFlagService }
+    ],
+    exports: [FeatureFlagService, FeatureFlagService.TOKEN]
+  })
+], FeatureFlagModule);
+export {
+  getFlagSpecs,
+  MemoryFlagBackend,
+  FeatureFlagService,
+  FeatureFlagModule,
+  FeatureFlag
+};
+
+//# debugId=4B9056D725A21D8664756E2164756E21
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,13 @@
+{
+  "version": 3,
+  "sources": ["../src/feature-flag.module.ts", "../src/feature-flag.service.ts", "../src/backends/memory.ts", "../src/decorators/feature-flag.decorator.ts"],
+  "sourcesContent": [
+    "/**\n * `FeatureFlagModule` — drop-in feature flags.\n *\n *   @Module({\n *     imports: [\n *       FeatureFlagModule.forRoot({\n *         flags: {\n *           'new-dashboard': { enabled: true, rollout: 0.5 },\n *           'beta-api':      false,\n *         },\n *       }),\n *     ],\n *   })\n *   export class AppModule {}\n */\nimport \"reflect-metadata\";\nimport { Module } from \"@nexusts/core\";\nimport { FeatureFlagService } from \"./feature-flag.service.js\";\nimport type { FeatureFlagConfig } from \"./types.js\";\n\n@Module({\n\tproviders: [\n\t\tFeatureFlagService,\n\t\t{ provide: FeatureFlagService.TOKEN, useExisting: FeatureFlagService },\n\t],\n\texports: [FeatureFlagService, FeatureFlagService.TOKEN],\n})\nexport class FeatureFlagModule {\n\tstatic forRoot(config: FeatureFlagConfig = {}) {\n\t\t@Module({\n\t\t\tproviders: [\n\t\t\t\tFeatureFlagService,\n\t\t\t\t{ provide: FeatureFlagService.TOKEN, useExisting: FeatureFlagService },\n\t\t\t\t{ provide: \"FEATURE_FLAG_CONFIG\", useValue: config },\n\t\t\t],\n\t\t\texports: [FeatureFlagService, FeatureFlagService.TOKEN],\n\t\t})\n\t\tclass ConfiguredFeatureFlagModule {}\n\t\tObject.defineProperty(ConfiguredFeatureFlagModule, \"name\", {\n\t\t\tvalue: \"ConfiguredFeatureFlagModule\",\n\t\t});\n\t\treturn ConfiguredFeatureFlagModule;\n\t}\n}\n",
+    "/**\n * `FeatureFlagService` — isEnabled / setFlag / getFlag + decorator wiring.\n *\n *   const flags = new FeatureFlagService({\n *     flags: {\n *       'new-ui':   { enabled: true,  rollout: 0.5 },\n *       'beta-api': { enabled: false },\n *     },\n *   });\n *\n *   await flags.isEnabled('new-ui', { userId: 'u1' }); // true or false by hash\n */\nimport { Inject, Injectable } from \"@nexusts/core\";\nimport type { FlagContext, FlagDefinition, FeatureFlagBackend, FeatureFlagConfig } from \"./types.js\";\nimport { MemoryFlagBackend } from \"./backends/memory.js\";\nimport { getFlagSpecs } from \"./decorators/feature-flag.decorator.js\";\n\n@Injectable()\nexport class FeatureFlagService {\n\t/** DI token. */\n\tstatic readonly TOKEN = Symbol.for(\"nexus:FeatureFlagService\");\n\n\t#backend: FeatureFlagBackend;\n\n\tconstructor(@Inject(\"FEATURE_FLAG_CONFIG\") config: FeatureFlagConfig = {}) {\n\t\tthis.#backend = new MemoryFlagBackend(config.flags ?? {});\n\t}\n\n\t/** Returns `true` if the flag is enabled for the given context. */\n\tasync isEnabled(flagName: string, context?: FlagContext): Promise<boolean> {\n\t\treturn this.#backend.isEnabled(flagName, context);\n\t}\n\n\t/** Create or update a flag at runtime. */\n\tsetFlag(flagName: string, definition: FlagDefinition | boolean): void {\n\t\tthis.#backend.setFlag(flagName, definition);\n\t}\n\n\t/** Return the raw definition (or `undefined` if unknown). */\n\tgetFlag(flagName: string): FlagDefinition | undefined {\n\t\treturn this.#backend.getFlag(flagName);\n\t}\n\n\t/**\n\t * Wire `@FeatureFlag` decorators onto a controller or service instance.\n\t * Each decorated route handler is wrapped so it returns a 404 JSON\n\t * response when the flag is disabled.\n\t *\n\t * The DI container calls this automatically when FeatureFlagModule is\n\t * imported; you can also call it manually in tests.\n\t */\n\tapplyDecorators(target: any): void {\n\t\tconst specs = getFlagSpecs(target.constructor);\n\t\tfor (const spec of specs) {\n\t\t\tconst original = spec.original;\n\t\t\t(target as any)[spec.propertyKey] = async (c: any, ...rest: any[]) => {\n\t\t\t\tconst ctx = spec.contextFn ? spec.contextFn(c) : undefined;\n\t\t\t\tconst enabled = await this.isEnabled(spec.flagName, ctx);\n\t\t\t\tif (!enabled) {\n\t\t\t\t\tif (spec.onDisabled) return spec.onDisabled(c);\n\t\t\t\t\treturn c.json({ message: \"Feature not available\", code: \"FEATURE_DISABLED\" }, 404);\n\t\t\t\t}\n\t\t\t\treturn original.apply(target, [c, ...rest]);\n\t\t\t};\n\t\t}\n\t}\n}\n",
+    "import type { FlagContext, FlagDefinition, FeatureFlagBackend } from \"../types.js\";\n\n/** djb2 hash → deterministic 0-1 float for rollout bucketing. */\nfunction hashFloat(s: string): number {\n\tlet h = 5381;\n\tfor (let i = 0; i < s.length; i++) {\n\t\th = Math.imul(h, 33) ^ s.charCodeAt(i);\n\t}\n\treturn (h >>> 0) / 0xffffffff;\n}\n\n/** In-process feature flag backend — no external dependencies. */\nexport class MemoryFlagBackend implements FeatureFlagBackend {\n\t#flags = new Map<string, FlagDefinition>();\n\n\tconstructor(initial: Record<string, FlagDefinition | boolean> = {}) {\n\t\tfor (const [k, v] of Object.entries(initial)) {\n\t\t\tthis.#flags.set(k, typeof v === \"boolean\" ? { enabled: v } : v);\n\t\t}\n\t}\n\n\tsetFlag(flagName: string, definition: FlagDefinition | boolean): void {\n\t\tthis.#flags.set(\n\t\t\tflagName,\n\t\t\ttypeof definition === \"boolean\" ? { enabled: definition } : definition,\n\t\t);\n\t}\n\n\tgetFlag(flagName: string): FlagDefinition | undefined {\n\t\treturn this.#flags.get(flagName);\n\t}\n\n\tasync isEnabled(flagName: string, context?: FlagContext): Promise<boolean> {\n\t\tconst def = this.#flags.get(flagName);\n\t\tif (!def) return false;\n\n\t\tconst id = context?.userId ?? context?.tenantId ?? context?.key ?? \"\";\n\n\t\t// Denylist has highest priority\n\t\tif (id && def.denylist?.includes(id)) return false;\n\n\t\t// Allowlist always wins after denylist\n\t\tif (id && def.allowlist?.includes(id)) return true;\n\n\t\t// Base enabled gate\n\t\tif (def.enabled === false) return false;\n\n\t\t// Rollout: deterministic hash bucketing\n\t\tif (def.rollout !== undefined && def.rollout < 1) {\n\t\t\tif (!id) return def.rollout > 0;\n\t\t\treturn hashFloat(`${flagName}:${id}`) < def.rollout;\n\t\t}\n\n\t\treturn def.enabled !== false;\n\t}\n}\n",
+    "import \"reflect-metadata\";\nimport type { FlagContext } from \"../types.js\";\n\nconst FLAG_META = Symbol.for(\"nexus:FeatureFlag\");\n\nexport interface FeatureFlagOptions {\n\t/** Extract a `FlagContext` from the Hono `Context` object (first arg of the handler). */\n\tcontextFn?: (c: any) => FlagContext;\n\t/** Custom response when the flag is disabled. Defaults to 404 JSON. */\n\tonDisabled?: (c: any) => Response | Promise<Response>;\n}\n\nexport interface FlagSpec {\n\tpropertyKey: string | symbol;\n\tflagName: string;\n\tcontextFn?: (c: any) => FlagContext;\n\tonDisabled?: (c: any) => Response | Promise<Response>;\n\toriginal: (...args: any[]) => any;\n}\n\n/**\n * Mark a route handler so `FeatureFlagService.applyDecorators()` will gate it.\n *\n *   @Get('/')\n *   @FeatureFlag('new-dashboard')\n *   async index(c: Context) { ... }\n *\n * When the flag is disabled the handler returns a 404 JSON response.\n * Pass `onDisabled` to customise the response, or `contextFn` to extract\n * a `FlagContext` (userId etc.) from the Hono `Context`.\n */\nexport function FeatureFlag(\n\tflagName: string,\n\toptions: FeatureFlagOptions = {},\n): MethodDecorator {\n\treturn (target: any, propertyKey: string | symbol, descriptor: PropertyDescriptor) => {\n\t\tconst specs: FlagSpec[] = Reflect.getMetadata(FLAG_META, target.constructor) ?? [];\n\t\tspecs.push({\n\t\t\tpropertyKey,\n\t\t\tflagName,\n\t\t\tcontextFn: options.contextFn,\n\t\t\tonDisabled: options.onDisabled,\n\t\t\toriginal: descriptor.value,\n\t\t});\n\t\tReflect.defineMetadata(FLAG_META, specs, target.constructor);\n\t};\n}\n\nexport function getFlagSpecs(target: any): FlagSpec[] {\n\treturn Reflect.getMetadata(FLAG_META, target) ?? [];\n}\n"
+  ],
+  "mappings": "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",
+  "debugId": "4B9056D725A21D8664756E2164756E21",
+  "names": []
+}

package/dist/types.d.ts

@@ -0,0 +1,35 @@
+/** Targeting context passed to `isEnabled()`. */
+export interface FlagContext {
+    /** User identifier — used for allowlist/denylist and rollout hash. */
+    userId?: string;
+    /** Tenant identifier — fallback when userId is absent. */
+    tenantId?: string;
+    /** Arbitrary key used as the rollout hash seed when userId/tenantId are absent. */
+    key?: string;
+    /** Additional attributes available to custom backends. */
+    attributes?: Record<string, unknown>;
+}
+/** Per-flag definition stored in the backend. */
+export interface FlagDefinition {
+    /** Whether the flag is on. Defaults to `false`. */
+    enabled?: boolean;
+    /** Fractional rollout: 0 = nobody, 1 = everybody, 0.5 = 50% of traffic. */
+    rollout?: number;
+    /** User/tenant IDs that are always enabled regardless of `rollout`. */
+    allowlist?: string[];
+    /** User/tenant IDs that are always disabled regardless of other rules. */
+    denylist?: string[];
+}
+/** Config passed to `FeatureFlagModule.forRoot()`. */
+export interface FeatureFlagConfig {
+    /** Storage backend. Default: `'memory'`. */
+    backend?: "memory";
+    /** Initial flag definitions. Values may be `true/false` shorthand or full `FlagDefinition`. */
+    flags?: Record<string, FlagDefinition | boolean>;
+}
+/** Interface that any backend must implement. */
+export interface FeatureFlagBackend {
+    isEnabled(flagName: string, context?: FlagContext): Promise<boolean>;
+    setFlag(flagName: string, definition: FlagDefinition | boolean): void;
+    getFlag(flagName: string): FlagDefinition | undefined;
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@nexusts/feature-flag",
+  "version": "0.8.0",
+  "description": "Feature flags, canary deployments, and A/B testing for NexusTS",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "bun run ../../build.ts"
+  },
+  "keywords": [
+    "nexusts",
+    "framework",
+    "bun",
+    "feature-flag",
+    "ab-testing",
+    "canary"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@nexusts/core": "file:../core"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nexus-ts/nexusts.git",
+    "directory": "packages/feature-flag"
+  },
+  "homepage": "https://github.com/nexus-ts/nexusts#readme",
+  "bugs": {
+    "url": "https://github.com/nexus-ts/nexusts/issues"
+  }
+}