@velajs/feature-flags 0.1.0 → 0.1.1

package/dist/index.js

@@ -1,15 +1,114 @@
-// Public surface of @velajs/feature-flags (the `.` entry). Server-only: no
-// React, no client hooks. Runtime-specific drivers (Cloudflare Flagship / KV)
-// ship from @velajs/cloudflare against the FeatureFlagDriver contract exported
-// here.
-// --- DI: module / service / tokens ---------------------------------------
-export { FeatureFlagsModule } from "./feature-flags.module.js";
-export { FeatureFlagsService } from "./feature-flags.service.js";
-export { FEATURE_FLAG_TOKENS } from "./feature-flags.tokens.js";
-export { MemoryFlagDriver, memoryFlagDriver } from "./drivers/memory.driver.js";
-export { FeatureFlagDriverRegistry, buildDriverRegistry } from "./drivers/registry.js";
-// --- Guard + decorator ----------------------------------------------------
-export { FeatureFlagGuard } from "./guards/feature-flag.guard.js";
-export { FeatureFlag, FEATURE_FLAG_METADATA } from "./decorators/feature-flag.decorator.js";
-// --- Errors ---------------------------------------------------------------
-export { FeatureFlagError } from "./feature-flags.error.js";
+import { a as FEATURE_FLAG_TOKENS, c as MemoryFlagDriver, i as __decorateMetadata, l as memoryFlagDriver, n as __decorate, o as FeatureFlagDriverRegistry, r as __decorateParam, s as buildDriverRegistry, t as FeatureFlagsService, u as FeatureFlagError } from "./feature-flags.service-CNOZ1DhZ.js";
+import { APP_GUARD, ForbiddenException, Inject, Injectable, NotFoundException, REQUEST_CONTEXT, Reflector, Scope, SetMetadata, defineModule } from "@velajs/vela";
+//#region src/decorators/feature-flag.decorator.ts
+const FEATURE_FLAG_METADATA = "vela:feature-flags:flag";
+/**
+* Gate a route (handler) or controller behind a boolean feature flag. Pair
+* with {@link FeatureFlagGuard} (via `@UseGuards` or the module's `isGlobal`
+* app-wide registration).
+*
+* @example
+* ```ts
+* @UseGuards(FeatureFlagGuard)
+* @Controller('/checkout')
+* class CheckoutController {
+*   @FeatureFlag('new-checkout')            // 404 when off
+*   @Get('/v2') v2() { ... }
+*
+*   @FeatureFlag('beta', { onDisabled: 'forbidden' })  // 403 when off
+*   @Get('/beta') beta() { ... }
+* }
+* ```
+*/
+function FeatureFlag(key, options = {}) {
+	const meta = {
+		key,
+		onDisabled: options.onDisabled ?? "notFound"
+	};
+	return SetMetadata(FEATURE_FLAG_METADATA, meta);
+}
+//#endregion
+//#region src/guards/feature-flag.guard.ts
+let FeatureFlagGuard = class FeatureFlagGuard {
+	flags;
+	reflector = new Reflector();
+	constructor(flags) {
+		this.flags = flags;
+	}
+	async canActivate(context) {
+		const meta = this.reflector.getAllAndOverride(FEATURE_FLAG_METADATA, context);
+		if (!meta) return true;
+		const requestContext = this.requestContext(context);
+		if (await (requestContext ? this.flags.forRequest(requestContext) : this.flags).getBooleanValue(meta.key)) return true;
+		if (meta.onDisabled === "forbidden") throw new ForbiddenException(`Feature "${meta.key}" is not enabled.`);
+		throw new NotFoundException();
+	}
+	/** The current request context, via the child container on the Hono context. */
+	requestContext(context) {
+		try {
+			return context.getContext().get("container")?.resolve(REQUEST_CONTEXT);
+		} catch {
+			return;
+		}
+	}
+};
+FeatureFlagGuard = __decorate([
+	Injectable(),
+	__decorateParam(0, Inject(FEATURE_FLAG_TOKENS.Service)),
+	__decorateMetadata("design:paramtypes", [Object])
+], FeatureFlagGuard);
+//#endregion
+//#region src/feature-flags.module.ts
+/**
+* The feature-flags module. Authored on vela's public `defineModule`, so
+* `forRoot({ drivers, default?, manifest?, context?, isGlobal? })` and the
+* matching `forRootAsync({ inject, useFactory, ... })` come for free.
+*
+* `lazy: true` is valid here: every provider is sync-constructible (a factory
+* for the driver registry, a sync-constructor service, a guard) and there are
+* no async lifecycle hooks — so the module defers to first use without
+* violating the sync-seam rule (see vela `MODULE_AUTHORING.md`).
+*
+* `isGlobal: true` makes the module globally visible AND registers
+* {@link FeatureFlagGuard} app-wide (`APP_GUARD`) so every `@FeatureFlag()`
+* route is gated without a per-controller `@UseGuards`.
+*/
+const { ConfigurableModuleClass } = defineModule({
+	name: "FeatureFlags",
+	optionsToken: FEATURE_FLAG_TOKENS.Options,
+	lazy: true,
+	transform: (definition, extras) => extras.isGlobal ? {
+		...definition,
+		global: true,
+		providers: [...definition.providers ?? [], {
+			provide: APP_GUARD,
+			useExisting: FeatureFlagGuard
+		}]
+	} : definition,
+	setup: ({ OPTIONS }) => ({
+		providers: [
+			{
+				provide: FEATURE_FLAG_TOKENS.DriverRegistry,
+				useFactory: (options) => buildDriverRegistry(options),
+				inject: [OPTIONS]
+			},
+			{
+				provide: FEATURE_FLAG_TOKENS.Service,
+				useClass: FeatureFlagsService,
+				scope: Scope.TRANSIENT
+			},
+			FeatureFlagGuard
+		],
+		exports: [
+			FEATURE_FLAG_TOKENS.Service,
+			FEATURE_FLAG_TOKENS.DriverRegistry,
+			FeatureFlagGuard,
+			OPTIONS
+		]
+	})
+});
+var FeatureFlagsModule = class extends ConfigurableModuleClass {};
+//#endregion
+export { FEATURE_FLAG_METADATA, FEATURE_FLAG_TOKENS, FeatureFlag, FeatureFlagDriverRegistry, FeatureFlagError, FeatureFlagGuard, FeatureFlagsModule, FeatureFlagsService, MemoryFlagDriver, buildDriverRegistry, memoryFlagDriver };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/decorators/feature-flag.decorator.ts","../src/guards/feature-flag.guard.ts","../src/feature-flags.module.ts"],"sourcesContent":["import { SetMetadata } from '@velajs/vela';\nimport type { FlagKey } from '../feature-flags.types';\n\n/** What the {@link FeatureFlagGuard} does when a gated flag is off. */\nexport type FeatureFlagDisabledBehavior = 'notFound' | 'forbidden';\n\nexport interface FeatureFlagOptions {\n  /**\n   * Response when the flag is off. `'notFound'` (default) hides the route\n   * entirely (404); `'forbidden'` reveals it exists but denies access (403).\n   */\n  onDisabled?: FeatureFlagDisabledBehavior;\n}\n\n/** The metadata `@FeatureFlag()` attaches, read by {@link FeatureFlagGuard}. */\nexport interface FeatureFlagMetadata {\n  key: string;\n  onDisabled: FeatureFlagDisabledBehavior;\n}\n\nexport const FEATURE_FLAG_METADATA = 'vela:feature-flags:flag';\n\n/**\n * Gate a route (handler) or controller behind a boolean feature flag. Pair\n * with {@link FeatureFlagGuard} (via `@UseGuards` or the module's `isGlobal`\n * app-wide registration).\n *\n * @example\n * ```ts\n * @UseGuards(FeatureFlagGuard)\n * @Controller('/checkout')\n * class CheckoutController {\n *   @FeatureFlag('new-checkout')            // 404 when off\n *   @Get('/v2') v2() { ... }\n *\n *   @FeatureFlag('beta', { onDisabled: 'forbidden' })  // 403 when off\n *   @Get('/beta') beta() { ... }\n * }\n * ```\n */\nexport function FeatureFlag(key: FlagKey, options: FeatureFlagOptions = {}) {\n  const meta: FeatureFlagMetadata = { key, onDisabled: options.onDisabled ?? 'notFound' };\n  return SetMetadata(FEATURE_FLAG_METADATA, meta);\n}\n","import {\n  Container,\n  ForbiddenException,\n  Inject,\n  Injectable,\n  NotFoundException,\n  REQUEST_CONTEXT,\n  Reflector,\n  type CanActivate,\n  type ExecutionContext,\n  type RequestContext,\n} from '@velajs/vela';\nimport {\n  FEATURE_FLAG_METADATA,\n  type FeatureFlagMetadata,\n} from '../decorators/feature-flag.decorator';\nimport type { FeatureFlagsService } from '../feature-flags.service';\nimport { FEATURE_FLAG_TOKENS } from '../feature-flags.tokens';\n\n/**\n * Route gate for `@FeatureFlag()`. Reads the handler/controller metadata, then\n * `getBooleanValue(key)`; when the flag is off it throws `NotFoundException`\n * (the route appears hidden) or `ForbiddenException` per the decorator option.\n * Handlers with no `@FeatureFlag()` metadata pass through untouched, so the\n * guard is safe to register app-wide (`FeatureFlagsModule.forRoot({ isGlobal:\n * true })`) or per-route via `@UseGuards(FeatureFlagGuard)`.\n *\n * It does NOT inject `REQUEST_CONTEXT` — that would make the guard request-\n * scoped and break lazy-module materialization (which constructs every provider\n * once, at first use, possibly outside a request). Instead it reads the request\n * context off the per-request child container carried on the Hono context, so\n * the module's `context` resolver still runs for the gate decision.\n */\n@Injectable()\nexport class FeatureFlagGuard implements CanActivate {\n  private readonly reflector = new Reflector();\n\n  constructor(@Inject(FEATURE_FLAG_TOKENS.Service) private readonly flags: FeatureFlagsService) {}\n\n  async canActivate(context: ExecutionContext): Promise<boolean> {\n    const meta = this.reflector.getAllAndOverride<FeatureFlagMetadata>(\n      FEATURE_FLAG_METADATA,\n      context,\n    );\n    if (!meta) return true;\n\n    const requestContext = this.requestContext(context);\n    const flags = requestContext ? this.flags.forRequest(requestContext) : this.flags;\n    const enabled = await flags.getBooleanValue(meta.key);\n    if (enabled) return true;\n\n    if (meta.onDisabled === 'forbidden') {\n      throw new ForbiddenException(`Feature \"${meta.key}\" is not enabled.`);\n    }\n    throw new NotFoundException();\n  }\n\n  /** The current request context, via the child container on the Hono context. */\n  private requestContext(context: ExecutionContext): RequestContext | undefined {\n    try {\n      const container = context.getContext().get('container') as Container | undefined;\n      return container?.resolve(REQUEST_CONTEXT);\n    } catch {\n      return undefined;\n    }\n  }\n}\n","import { APP_GUARD, Scope, defineModule } from '@velajs/vela';\nimport { buildDriverRegistry } from './drivers/registry';\nimport { FeatureFlagGuard } from './guards/feature-flag.guard';\nimport { FeatureFlagsService } from './feature-flags.service';\nimport { FEATURE_FLAG_TOKENS } from './feature-flags.tokens';\nimport type { FeatureFlagsOptions } from './feature-flags.types';\n\n/**\n * The feature-flags module. Authored on vela's public `defineModule`, so\n * `forRoot({ drivers, default?, manifest?, context?, isGlobal? })` and the\n * matching `forRootAsync({ inject, useFactory, ... })` come for free.\n *\n * `lazy: true` is valid here: every provider is sync-constructible (a factory\n * for the driver registry, a sync-constructor service, a guard) and there are\n * no async lifecycle hooks — so the module defers to first use without\n * violating the sync-seam rule (see vela `MODULE_AUTHORING.md`).\n *\n * `isGlobal: true` makes the module globally visible AND registers\n * {@link FeatureFlagGuard} app-wide (`APP_GUARD`) so every `@FeatureFlag()`\n * route is gated without a per-controller `@UseGuards`.\n */\nconst { ConfigurableModuleClass } = defineModule<FeatureFlagsOptions>({\n  name: 'FeatureFlags',\n  optionsToken: FEATURE_FLAG_TOKENS.Options,\n  lazy: true,\n  transform: (definition, extras) =>\n    (extras as { isGlobal?: boolean }).isGlobal\n      ? {\n          ...definition,\n          global: true,\n          providers: [\n            ...(definition.providers ?? []),\n            { provide: APP_GUARD, useExisting: FeatureFlagGuard },\n          ],\n        }\n      : definition,\n  setup: ({ OPTIONS }) => ({\n    providers: [\n      {\n        provide: FEATURE_FLAG_TOKENS.DriverRegistry,\n        useFactory: (options: FeatureFlagsOptions) => buildDriverRegistry(options),\n        inject: [OPTIONS],\n      },\n      // Transient: a fresh service per injection, so `use()`/`forRequest()`\n      // clones and per-request context stay isolated. The service never injects\n      // REQUEST_CONTEXT, so it does not bubble to request scope and remains\n      // resolvable in queue / scheduled / global scope.\n      {\n        provide: FEATURE_FLAG_TOKENS.Service,\n        useClass: FeatureFlagsService,\n        scope: Scope.TRANSIENT,\n      },\n      FeatureFlagGuard,\n    ],\n    exports: [\n      FEATURE_FLAG_TOKENS.Service,\n      FEATURE_FLAG_TOKENS.DriverRegistry,\n      FeatureFlagGuard,\n      OPTIONS,\n    ],\n  }),\n});\n\nexport class FeatureFlagsModule extends ConfigurableModuleClass {}\n"],"mappings":";;;AAoBA,MAAa,wBAAwB;;;;;;;;;;;;;;;;;;;AAoBrC,SAAgB,YAAY,KAAc,UAA8B,CAAC,GAAG;CAC1E,MAAM,OAA4B;EAAE;EAAK,YAAY,QAAQ,cAAc;CAAW;CACtF,OAAO,YAAY,uBAAuB,IAAI;AAChD;;;ACTO,IAAA,mBAAA,MAAM,iBAAwC;CAGe;CAFlE,YAA6B,IAAI,UAAU;CAE3C,YAAY,OAAkF;EAA5B,KAAA,QAAA;CAA6B;CAE/F,MAAM,YAAY,SAA6C;EAC7D,MAAM,OAAO,KAAK,UAAU,kBAC1B,uBACA,OACF;EACA,IAAI,CAAC,MAAM,OAAO;EAElB,MAAM,iBAAiB,KAAK,eAAe,OAAO;EAGlD,IAAI,OAFU,iBAAiB,KAAK,MAAM,WAAW,cAAc,IAAI,KAAK,MAAA,CAChD,gBAAgB,KAAK,GAAG,GACvC,OAAO;EAEpB,IAAI,KAAK,eAAe,aACtB,MAAM,IAAI,mBAAmB,YAAY,KAAK,IAAI,kBAAkB;EAEtE,MAAM,IAAI,kBAAkB;CAC9B;;CAGA,eAAuB,SAAuD;EAC5E,IAAI;GAEF,OADkB,QAAQ,WAAW,CAAC,CAAC,IAAI,WAC5B,CAAC,EAAE,QAAQ,eAAe;EAC3C,QAAQ;GACN;EACF;CACF;AACF;;CAjCC,WAAW;oBAIG,OAAO,oBAAoB,OAAO,CAAA;;;;;;;;;;;;;;;;;;;AChBjD,MAAM,EAAE,4BAA4B,aAAkC;CACpE,MAAM;CACN,cAAc,oBAAoB;CAClC,MAAM;CACN,YAAY,YAAY,WACrB,OAAkC,WAC/B;EACE,GAAG;EACH,QAAQ;EACR,WAAW,CACT,GAAI,WAAW,aAAa,CAAC,GAC7B;GAAE,SAAS;GAAW,aAAa;EAAiB,CACtD;CACF,IACA;CACN,QAAQ,EAAE,eAAe;EACvB,WAAW;GACT;IACE,SAAS,oBAAoB;IAC7B,aAAa,YAAiC,oBAAoB,OAAO;IACzE,QAAQ,CAAC,OAAO;GAClB;GAKA;IACE,SAAS,oBAAoB;IAC7B,UAAU;IACV,OAAO,MAAM;GACf;GACA;EACF;EACA,SAAS;GACP,oBAAoB;GACpB,oBAAoB;GACpB;GACA;EACF;CACF;AACF,CAAC;AAED,IAAa,qBAAb,cAAwC,wBAAwB,CAAC"}

package/dist/memory.driver-C-5Y2b7_.d.ts

@@ -0,0 +1,235 @@
+import { LoggerService, RequestContext } from "@velajs/vela";
+//#region src/drivers/driver.d.ts
+/**
+ * The cross-package contract every feature-flag backend implements.
+ *
+ * This is the seam that platform packages plug into: `@velajs/cloudflare`
+ * ships a Flagship-binding driver and a KV-backed driver against this exact
+ * interface, `@velajs/feature-flags` ships {@link MemoryFlagDriver}. A driver
+ * maps a key + fallback (+ optional targeting context) onto a typed value and
+ * MUST return the `fallback` — never throw — when it cannot resolve the key.
+ *
+ * Evaluation *details* (`FlagEvaluationDetails`) are synthesized by
+ * `FeatureFlagsService` around these four value methods; drivers may
+ * optionally override that synthesis, but the value methods are the contract.
+ */
+interface FeatureFlagDriver {
+  readonly name: string;
+  getBoolean(key: string, fallback: boolean, ctx?: FlagContext): Promise<boolean>;
+  getString(key: string, fallback: string, ctx?: FlagContext): Promise<string>;
+  getNumber(key: string, fallback: number, ctx?: FlagContext): Promise<number>;
+  getObject<T extends object>(key: string, fallback: T, ctx?: FlagContext): Promise<T>;
+}
+//#endregion
+//#region src/feature-flags.types.d.ts
+/**
+ * A value a feature flag can resolve to. Mirrors the four evaluation methods
+ * on {@link FeatureFlagDriver}.
+ */
+type FlagValue = boolean | string | number | object;
+/**
+ * A free-form evaluation context handed to a driver (for targeting: user id,
+ * plan, country, …). Drivers that don't do targeting ignore it.
+ */
+type FlagContext = Record<string, unknown>;
+/**
+ * Augment this interface to get typed flag keys on the service and the
+ * `@FeatureFlag()` decorator.
+ *
+ * @example
+ * ```ts
+ * declare module '@velajs/feature-flags' {
+ *   interface FeatureFlagRegistry {
+ *     'new-checkout': boolean;
+ *     'checkout-flow': string;
+ *   }
+ * }
+ * ```
+ */
+interface FeatureFlagRegistry {}
+/**
+ * A flag key. Narrows to the declared {@link FeatureFlagRegistry} keys when the
+ * app augments it; falls back to `string` otherwise.
+ */
+type FlagKey = keyof FeatureFlagRegistry extends never ? string : keyof FeatureFlagRegistry & string;
+/**
+ * A declared set of flags and their default values.
+ *
+ * Drivers have no enumeration API, so the flags you intend to evaluate as a
+ * batch (via {@link FeatureFlagsService.all}) must be declared once here. Each
+ * default also doubles as the type hint used to pick the evaluation method.
+ */
+type FlagManifest = Record<string, FlagValue>;
+/** Why an evaluation returned the value it did. */
+type FlagEvaluationReason = 'STATIC' | 'DEFAULT' | 'ERROR';
+/** A flag value plus the metadata the service synthesizes around a driver read. */
+interface FlagEvaluationDetails<T extends FlagValue = FlagValue> {
+  flagKey: string;
+  value: T;
+  reason: FlagEvaluationReason;
+  errorMessage?: string;
+}
+/**
+ * Feature-flags module configuration.
+ */
+interface FeatureFlagsOptions {
+  /**
+   * The drivers this app can evaluate against. When omitted, a single
+   * in-memory {@link MemoryFlagDriver} named `"memory"` is used (all flags
+   * resolve to their declared defaults).
+   */
+  drivers?: FeatureFlagDriver[];
+  /** Name of the driver the injected service targets. Defaults to `drivers[0].name`. */
+  default?: string;
+  /** Declared flags + defaults. Powers manifest defaults and {@link FeatureFlagsService.all}. */
+  manifest?: FlagManifest;
+  /**
+   * Resolves a per-request evaluation context (for example `{ userId }`) merged
+   * into every evaluation. Per-call context passed to a method overrides these.
+   * Receives the current request context; skipped outside request scope.
+   */
+  context?: (ctx: RequestContext) => FlagContext | Promise<FlagContext>;
+}
+//#endregion
+//#region src/drivers/registry.d.ts
+/**
+ * The set of registered {@link FeatureFlagDriver}s plus the default selection.
+ * Built once per module instance ({@link buildDriverRegistry}) and injected
+ * into {@link FeatureFlagsService}; `use(name)` looks a driver up here.
+ */
+declare class FeatureFlagDriverRegistry {
+  private readonly drivers;
+  readonly defaultName: string;
+  constructor(drivers: readonly FeatureFlagDriver[], defaultName?: string);
+  /** Look a driver up by name; throws {@link FeatureFlagError} when unknown. */
+  get(name: string): FeatureFlagDriver;
+  /** Resolve a named driver, or the default when `name` is omitted. */
+  resolve(name?: string): FeatureFlagDriver;
+  /** All registered driver names. */
+  names(): string[];
+}
+/**
+ * Build the driver registry from module options. Falls back to a single
+ * in-memory driver when none are configured, so `FeatureFlagsModule.forRoot({})`
+ * yields a working (all-defaults) flags service for local development.
+ */
+declare function buildDriverRegistry(options: FeatureFlagsOptions): FeatureFlagDriverRegistry;
+//#endregion
+//#region src/feature-flags.service.d.ts
+/**
+ * The injectable consumers reach for. A thin, type-safe, never-throw wrapper
+ * over a {@link FeatureFlagDriver}, with two ergonomic additions:
+ *
+ * - **Manifest defaults** — omit a default and the value declared in the app's
+ *   `manifest` is used (an explicit argument always wins).
+ * - **Default context** — the module's `context` resolver is merged into every
+ *   evaluation (per-call context overrides it), resolved from the current
+ *   request and skipped automatically outside request scope.
+ *
+ * Switch drivers with {@link use}; bind a request with {@link forRequest} (the
+ * guard does this). Evaluation NEVER throws — the driver returns the fallback
+ * on evaluation errors, and the service additionally absorbs any thrown error
+ * into the same fallback with a logged warning.
+ *
+ * `@Transient`: constructed synchronously (lazy-module-safe), a fresh instance
+ * per injection, and resolvable in and out of request scope — it never
+ * DI-injects `REQUEST_CONTEXT`, so it does not bubble to request scope.
+ */
+declare class FeatureFlagsService {
+  private readonly registry;
+  private readonly options;
+  private readonly boundContext?;
+  private readonly logger;
+  private readonly manifest;
+  private readonly driver;
+  constructor(registry: FeatureFlagDriverRegistry, options: FeatureFlagsOptions, logger?: LoggerService, boundContext?: RequestContext | undefined, boundDriver?: FeatureFlagDriver);
+  /** The name of the driver this instance targets. */
+  get driverName(): string;
+  /**
+   * Switch to a different registered driver. Returns a NEW immutable instance
+   * bound to `name`; the original is unchanged. Throws if `name` is unknown.
+   */
+  use(name: string): FeatureFlagsService;
+  /**
+   * Bind a request context. Returns a NEW immutable instance whose evaluations
+   * merge `options.context(ctx)`. Used by {@link FeatureFlagGuard}; consumers
+   * resolved in request scope can also call it explicitly.
+   */
+  forRequest(ctx: RequestContext): FeatureFlagsService;
+  /** Evaluate a flag as a `boolean`. */
+  getBooleanValue(flagKey: FlagKey, defaultValue?: boolean, context?: FlagContext): Promise<boolean>;
+  /** Evaluate a flag as a `string`. */
+  getStringValue(flagKey: FlagKey, defaultValue?: string, context?: FlagContext): Promise<string>;
+  /** Evaluate a flag as a `number`. */
+  getNumberValue(flagKey: FlagKey, defaultValue?: number, context?: FlagContext): Promise<number>;
+  /** Evaluate a flag as a typed object. */
+  getObjectValue<T extends object>(flagKey: FlagKey, defaultValue?: T, context?: FlagContext): Promise<T>;
+  /** Evaluate a `boolean` flag with synthesized evaluation metadata. */
+  getBooleanDetails(flagKey: FlagKey, defaultValue?: boolean, context?: FlagContext): Promise<FlagEvaluationDetails<boolean>>;
+  /** Evaluate a `string` flag with synthesized evaluation metadata. */
+  getStringDetails(flagKey: FlagKey, defaultValue?: string, context?: FlagContext): Promise<FlagEvaluationDetails<string>>;
+  /** Evaluate a `number` flag with synthesized evaluation metadata. */
+  getNumberDetails(flagKey: FlagKey, defaultValue?: number, context?: FlagContext): Promise<FlagEvaluationDetails<number>>;
+  /** Evaluate a typed object flag with synthesized evaluation metadata. */
+  getObjectDetails<T extends object>(flagKey: FlagKey, defaultValue?: T, context?: FlagContext): Promise<FlagEvaluationDetails<T>>;
+  /**
+   * Evaluate every flag declared in the manifest and return a `{ key: value }`
+   * map. The evaluation method is chosen from each declared default's type.
+   * A throwing context resolver falls back to the manifest defaults rather than
+   * taking the batch down.
+   */
+  all(context?: FlagContext): Promise<Record<string, FlagValue>>;
+  /** Immutable clone with a different driver and/or bound context. */
+  private clone;
+  /** Resolve the merged evaluation context (default context + per-call override). */
+  private context;
+  /** Pick the default: explicit arg, then manifest, then the type's zero value. */
+  private fallback;
+  /** Evaluate a single flag, choosing the method from the declared default's type. */
+  private evaluate;
+  /**
+   * Run an evaluation and absorb any failure into the fallback. A flag lookup
+   * must never take the caller down with it.
+   */
+  private safe;
+  private details;
+  private errorDetails;
+}
+//#endregion
+//#region src/drivers/memory.driver.d.ts
+interface MemoryFlagDriverOptions {
+  /** Driver name used for `use(name)` / the default-driver selection. Default `"memory"`. */
+  name?: string;
+  /** Initial flag values. */
+  values?: FlagManifest;
+}
+/**
+ * In-memory {@link FeatureFlagDriver}: the default driver shipped in-package
+ * and the test fake in one. Reads from an internal `Map` seeded from options
+ * or mutated with {@link set}/{@link reset} — the memory driver ignores the
+ * evaluation context (it does no targeting). An unknown key returns the
+ * caller's `fallback`, exactly like a remote driver that can't resolve it.
+ */
+declare class MemoryFlagDriver implements FeatureFlagDriver {
+  readonly name: string;
+  private readonly store;
+  constructor(options?: MemoryFlagDriverOptions);
+  /** Set a flag value. Chainable. */
+  set(key: string, value: FlagValue): this;
+  /** Remove a flag (subsequent reads return the caller's fallback). Chainable. */
+  delete(key: string): this;
+  /** True when `key` has a stored value. */
+  has(key: string): boolean;
+  /** Clear all flags, then optionally seed a fresh set. Chainable. */
+  reset(values?: FlagManifest): this;
+  getBoolean(key: string, fallback: boolean, _ctx?: FlagContext): Promise<boolean>;
+  getString(key: string, fallback: string, _ctx?: FlagContext): Promise<string>;
+  getNumber(key: string, fallback: number, _ctx?: FlagContext): Promise<number>;
+  getObject<T extends object>(key: string, fallback: T, _ctx?: FlagContext): Promise<T>;
+  private read;
+}
+/** Convenience factory for {@link MemoryFlagDriver}. */
+declare function memoryFlagDriver(options?: MemoryFlagDriverOptions): MemoryFlagDriver;
+//#endregion
+export { FeatureFlagDriverRegistry as a, FeatureFlagsOptions as c, FlagEvaluationReason as d, FlagKey as f, FeatureFlagDriver as h, FeatureFlagsService as i, FlagContext as l, FlagValue as m, MemoryFlagDriverOptions as n, buildDriverRegistry as o, FlagManifest as p, memoryFlagDriver as r, FeatureFlagRegistry as s, MemoryFlagDriver as t, FlagEvaluationDetails as u };
+//# sourceMappingURL=memory.driver-C-5Y2b7_.d.ts.map

package/dist/testing/index.d.ts

@@ -1,13 +1,10 @@
-import { MemoryFlagDriver } from '../drivers/memory.driver';
-import { FeatureFlagsService } from '../feature-flags.service';
-import type { FeatureFlagsOptions, FlagManifest } from '../feature-flags.types';
-export { MemoryFlagDriver, memoryFlagDriver } from '../drivers/memory.driver';
-export type { MemoryFlagDriverOptions } from '../drivers/memory.driver';
-export interface TestFeatureFlags {
-    /** A real service bound to the memory driver below. */
-    service: FeatureFlagsService;
-    /** The backing memory driver — mutate flags with `.set()`/`.reset()`. */
-    driver: MemoryFlagDriver;
+import { c as FeatureFlagsOptions, i as FeatureFlagsService, n as MemoryFlagDriverOptions, p as FlagManifest, r as memoryFlagDriver, t as MemoryFlagDriver } from "../memory.driver-C-5Y2b7_.js";
+//#region src/testing/index.d.ts
+interface TestFeatureFlags {
+  /** A real service bound to the memory driver below. */
+  service: FeatureFlagsService;
+  /** The backing memory driver — mutate flags with `.set()`/`.reset()`. */
+  driver: MemoryFlagDriver;
 }
 /**
  * Build a real {@link FeatureFlagsService} over an in-memory driver, no DI /
@@ -22,4 +19,7 @@ export interface TestFeatureFlags {
  * expect(await service.getBooleanValue('new-checkout')).toBe(false);
  * ```
  */
-export declare function createTestFeatureFlags(values?: FlagManifest, options?: Pick<FeatureFlagsOptions, 'manifest' | 'context'>): TestFeatureFlags;
+declare function createTestFeatureFlags(values?: FlagManifest, options?: Pick<FeatureFlagsOptions, 'manifest' | 'context'>): TestFeatureFlags;
+//#endregion
+export { MemoryFlagDriver, type MemoryFlagDriverOptions, TestFeatureFlags, createTestFeatureFlags, memoryFlagDriver };
+//# sourceMappingURL=index.d.ts.map

package/dist/testing/index.js

@@ -1,36 +1,30 @@
-// @velajs/feature-flags/testing — the memory driver IS the fake. This subpath
-// re-exports it plus a zero-DI helper for unit tests that want a real
-// FeatureFlagsService over an in-memory driver without bootstrapping a module.
-import { FeatureFlagDriverRegistry } from "../drivers/registry.js";
-import { MemoryFlagDriver } from "../drivers/memory.driver.js";
-import { FeatureFlagsService } from "../feature-flags.service.js";
-export { MemoryFlagDriver, memoryFlagDriver } from "../drivers/memory.driver.js";
+import { c as MemoryFlagDriver, l as memoryFlagDriver, o as FeatureFlagDriverRegistry, t as FeatureFlagsService } from "../feature-flags.service-CNOZ1DhZ.js";
+//#region src/testing/index.ts
 /**
- * Build a real {@link FeatureFlagsService} over an in-memory driver, no DI /
- * app bootstrap required. Flip flags on the returned `driver` and assert on the
- * `service`.
- *
- * @example
- * ```ts
- * const { service, driver } = createTestFeatureFlags({ 'new-checkout': true });
- * expect(await service.getBooleanValue('new-checkout')).toBe(true);
- * driver.set('new-checkout', false);
- * expect(await service.getBooleanValue('new-checkout')).toBe(false);
- * ```
- */ export function createTestFeatureFlags(values = {}, options = {}) {
-    const driver = new MemoryFlagDriver({
-        values
-    });
-    const registry = new FeatureFlagDriverRegistry([
-        driver
-    ], driver.name);
-    const service = new FeatureFlagsService(registry, {
-        default: driver.name,
-        manifest: options.manifest,
-        context: options.context
-    });
-    return {
-        service,
-        driver
-    };
+* Build a real {@link FeatureFlagsService} over an in-memory driver, no DI /
+* app bootstrap required. Flip flags on the returned `driver` and assert on the
+* `service`.
+*
+* @example
+* ```ts
+* const { service, driver } = createTestFeatureFlags({ 'new-checkout': true });
+* expect(await service.getBooleanValue('new-checkout')).toBe(true);
+* driver.set('new-checkout', false);
+* expect(await service.getBooleanValue('new-checkout')).toBe(false);
+* ```
+*/
+function createTestFeatureFlags(values = {}, options = {}) {
+	const driver = new MemoryFlagDriver({ values });
+	return {
+		service: new FeatureFlagsService(new FeatureFlagDriverRegistry([driver], driver.name), {
+			default: driver.name,
+			manifest: options.manifest,
+			context: options.context
+		}),
+		driver
+	};
 }
+//#endregion
+export { MemoryFlagDriver, createTestFeatureFlags, memoryFlagDriver };
+
+//# sourceMappingURL=index.js.map

package/dist/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/testing/index.ts"],"sourcesContent":["// @velajs/feature-flags/testing — the memory driver IS the fake. This subpath\n// re-exports it plus a zero-DI helper for unit tests that want a real\n// FeatureFlagsService over an in-memory driver without bootstrapping a module.\n\nimport { FeatureFlagDriverRegistry } from '../drivers/registry';\nimport { MemoryFlagDriver } from '../drivers/memory.driver';\nimport { FeatureFlagsService } from '../feature-flags.service';\nimport type { FeatureFlagsOptions, FlagManifest } from '../feature-flags.types';\n\nexport { MemoryFlagDriver, memoryFlagDriver } from '../drivers/memory.driver';\nexport type { MemoryFlagDriverOptions } from '../drivers/memory.driver';\n\nexport interface TestFeatureFlags {\n  /** A real service bound to the memory driver below. */\n  service: FeatureFlagsService;\n  /** The backing memory driver — mutate flags with `.set()`/`.reset()`. */\n  driver: MemoryFlagDriver;\n}\n\n/**\n * Build a real {@link FeatureFlagsService} over an in-memory driver, no DI /\n * app bootstrap required. Flip flags on the returned `driver` and assert on the\n * `service`.\n *\n * @example\n * ```ts\n * const { service, driver } = createTestFeatureFlags({ 'new-checkout': true });\n * expect(await service.getBooleanValue('new-checkout')).toBe(true);\n * driver.set('new-checkout', false);\n * expect(await service.getBooleanValue('new-checkout')).toBe(false);\n * ```\n */\nexport function createTestFeatureFlags(\n  values: FlagManifest = {},\n  options: Pick<FeatureFlagsOptions, 'manifest' | 'context'> = {},\n): TestFeatureFlags {\n  const driver = new MemoryFlagDriver({ values });\n  const registry = new FeatureFlagDriverRegistry([driver], driver.name);\n  const service = new FeatureFlagsService(registry, {\n    default: driver.name,\n    manifest: options.manifest,\n    context: options.context,\n  });\n  return { service, driver };\n}\n"],"mappings":";;;;;;;;;;;;;;;AAgCA,SAAgB,uBACd,SAAuB,CAAC,GACxB,UAA6D,CAAC,GAC5C;CAClB,MAAM,SAAS,IAAI,iBAAiB,EAAE,OAAO,CAAC;CAO9C,OAAO;EAAE,SAAA,IALW,oBAAoB,IADnB,0BAA0B,CAAC,MAAM,GAAG,OAAO,IACjB,GAAG;GAChD,SAAS,OAAO;GAChB,UAAU,QAAQ;GAClB,SAAS,QAAQ;EACnB,CACe;EAAG;CAAO;AAC3B"}

package/package.json

@@ -1,8 +1,34 @@
 {
   "name": "@velajs/feature-flags",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Edge-first, driver-based feature flags for the Vela framework",
+  "keywords": [
+    "cloudflare-workers",
+    "driver",
+    "edge",
+    "feature-flags",
+    "feature-toggles",
+    "framework",
+    "vela"
+  ],
+  "homepage": "https://github.com/velajs/feature-flags#readme",
+  "bugs": {
+    "url": "https://github.com/velajs/feature-flags/issues"
+  },
+  "license": "MIT",
+  "author": "ksh",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/velajs/feature-flags.git"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
   "type": "module",
+  "sideEffects": false,
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -15,52 +41,40 @@
       "import": "./dist/testing/index.js"
     }
   },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE",
-    "CHANGELOG.md"
-  ],
-  "sideEffects": false,
-  "keywords": [
-    "vela",
-    "feature-flags",
-    "feature-toggles",
-    "driver",
-    "edge",
-    "cloudflare-workers",
-    "framework"
-  ],
-  "author": "ksh",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/velajs/feature-flags.git"
-  },
-  "homepage": "https://github.com/velajs/feature-flags#readme",
-  "bugs": {
-    "url": "https://github.com/velajs/feature-flags/issues"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "peerDependencies": {
-    "@velajs/vela": ">=1.11.0",
-    "hono": ">=4"
-  },
   "devDependencies": {
-    "@swc/cli": "^0.8.1",
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@changesets/cli": "^2.31.0",
     "@swc/core": "^1.15.43",
     "@velajs/testing": "^0.4.0",
     "@velajs/vela": "^1.12.0",
     "hono": "^4.12.27",
-    "typescript": "^6.0.3",
+    "oxfmt": "^0.58.0",
+    "oxlint": "^1.73.0",
+    "publint": "^0.3.21",
+    "tsdown": "^0.22.4",
+    "typescript": "^7.0.2",
     "unplugin-swc": "^1.5.9",
-    "vitest": "^4.1.9"
+    "vitest": "^4.1.10"
+  },
+  "peerDependencies": {
+    "@velajs/vela": ">=1.11.0",
+    "hono": ">=4"
+  },
+  "engines": {
+    "node": ">=24"
   },
   "scripts": {
-    "build": "rm -rf dist && swc src -d dist --strip-leading-paths && tsc --emitDeclarationOnly",
+    "build": "tsdown",
     "test": "vitest run",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint .",
+    "format": "oxfmt .",
+    "format:check": "oxfmt --check .",
+    "publint": "publint",
+    "attw": "attw --pack . --profile esm-only",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "release": "pnpm build && changeset publish",
+    "verify": "pnpm lint && pnpm format:check && pnpm build && pnpm typecheck && pnpm test && pnpm publint && pnpm attw"
   }
 }

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

@@ -1,35 +0,0 @@
-import type { FlagKey } from '../feature-flags.types';
-/** What the {@link FeatureFlagGuard} does when a gated flag is off. */
-export type FeatureFlagDisabledBehavior = 'notFound' | 'forbidden';
-export interface FeatureFlagOptions {
-    /**
-     * Response when the flag is off. `'notFound'` (default) hides the route
-     * entirely (404); `'forbidden'` reveals it exists but denies access (403).
-     */
-    onDisabled?: FeatureFlagDisabledBehavior;
-}
-/** The metadata `@FeatureFlag()` attaches, read by {@link FeatureFlagGuard}. */
-export interface FeatureFlagMetadata {
-    key: string;
-    onDisabled: FeatureFlagDisabledBehavior;
-}
-export declare const FEATURE_FLAG_METADATA = "vela:feature-flags:flag";
-/**
- * Gate a route (handler) or controller behind a boolean feature flag. Pair
- * with {@link FeatureFlagGuard} (via `@UseGuards` or the module's `isGlobal`
- * app-wide registration).
- *
- * @example
- * ```ts
- * @UseGuards(FeatureFlagGuard)
- * @Controller('/checkout')
- * class CheckoutController {
- *   @FeatureFlag('new-checkout')            // 404 when off
- *   @Get('/v2') v2() { ... }
- *
- *   @FeatureFlag('beta', { onDisabled: 'forbidden' })  // 403 when off
- *   @Get('/beta') beta() { ... }
- * }
- * ```
- */
-export declare function FeatureFlag(key: FlagKey, options?: FeatureFlagOptions): (target: object, propertyKey?: string | symbol) => void;