@velajs/feature-flags 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.1.1
+
+### Patch Changes
+
+- 2b92134: Modernize the package build, validation, and release toolchain.
+
 ## 0.1.0
 
 Initial release.

package/dist/feature-flags.service-CNOZ1DhZ.js

@@ -0,0 +1,343 @@
+import { Inject, Injectable, Logger, Optional, Scope, getCurrentRequestContext, moduleToken } from "@velajs/vela";
+//#region src/feature-flags.error.ts
+/**
+* The single error type for `@velajs/feature-flags`.
+*
+* Note: flag *evaluation* never throws — the service absorbs driver failures
+* into the fallback value (see {@link FeatureFlagsService}). `FeatureFlagError`
+* is reserved for *configuration* faults surfaced at wiring time: an unknown
+* driver name, a duplicate driver, or an empty driver set.
+*/
+var FeatureFlagError = class extends Error {
+	name = "FeatureFlagError";
+	constructor(message, options) {
+		super(message, options?.cause !== void 0 ? { cause: options.cause } : void 0);
+	}
+};
+//#endregion
+//#region src/drivers/memory.driver.ts
+/**
+* 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.
+*/
+var MemoryFlagDriver = class {
+	name;
+	store;
+	constructor(options = {}) {
+		this.name = options.name ?? "memory";
+		this.store = new Map(Object.entries(options.values ?? {}));
+	}
+	/** Set a flag value. Chainable. */
+	set(key, value) {
+		this.store.set(key, value);
+		return this;
+	}
+	/** Remove a flag (subsequent reads return the caller's fallback). Chainable. */
+	delete(key) {
+		this.store.delete(key);
+		return this;
+	}
+	/** True when `key` has a stored value. */
+	has(key) {
+		return this.store.has(key);
+	}
+	/** Clear all flags, then optionally seed a fresh set. Chainable. */
+	reset(values) {
+		this.store.clear();
+		if (values) for (const [key, value] of Object.entries(values)) this.store.set(key, value);
+		return this;
+	}
+	getBoolean(key, fallback, _ctx) {
+		return Promise.resolve(this.read(key, fallback));
+	}
+	getString(key, fallback, _ctx) {
+		return Promise.resolve(this.read(key, fallback));
+	}
+	getNumber(key, fallback, _ctx) {
+		return Promise.resolve(this.read(key, fallback));
+	}
+	getObject(key, fallback, _ctx) {
+		return Promise.resolve(this.read(key, fallback));
+	}
+	read(key, fallback) {
+		return this.store.has(key) ? this.store.get(key) : fallback;
+	}
+};
+/** Convenience factory for {@link MemoryFlagDriver}. */
+function memoryFlagDriver(options) {
+	return new MemoryFlagDriver(options);
+}
+//#endregion
+//#region src/drivers/registry.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.
+*/
+var FeatureFlagDriverRegistry = class {
+	drivers = /* @__PURE__ */ new Map();
+	defaultName;
+	constructor(drivers, defaultName) {
+		if (drivers.length === 0) throw new FeatureFlagError("No feature flag drivers registered. Provide at least one driver to FeatureFlagsModule.forRoot({ drivers: [...] }).");
+		for (const driver of drivers) {
+			if (this.drivers.has(driver.name)) throw new FeatureFlagError(`Duplicate feature flag driver "${driver.name}".`);
+			this.drivers.set(driver.name, driver);
+		}
+		const requested = defaultName ?? drivers[0].name;
+		if (!this.drivers.has(requested)) throw new FeatureFlagError(`Default feature flag driver "${requested}" is not registered.`);
+		this.defaultName = requested;
+	}
+	/** Look a driver up by name; throws {@link FeatureFlagError} when unknown. */
+	get(name) {
+		const driver = this.drivers.get(name);
+		if (!driver) throw new FeatureFlagError(`Feature flag driver "${name}" is not registered.`);
+		return driver;
+	}
+	/** Resolve a named driver, or the default when `name` is omitted. */
+	resolve(name) {
+		return this.get(name ?? this.defaultName);
+	}
+	/** All registered driver names. */
+	names() {
+		return [...this.drivers.keys()];
+	}
+};
+/**
+* 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.
+*/
+function buildDriverRegistry(options) {
+	return new FeatureFlagDriverRegistry(options.drivers && options.drivers.length > 0 ? options.drivers : [new MemoryFlagDriver()], options.default);
+}
+//#endregion
+//#region src/feature-flags.tokens.ts
+/**
+* Injection tokens for the feature-flags module. Named on the
+* `vela:feature-flags:<thing>` convention so identity is stable across
+* refactors and consumers can `@Inject(FEATURE_FLAG_TOKENS.Service)`.
+*/
+const FEATURE_FLAG_TOKENS = {
+	/** The resolved {@link FeatureFlagsOptions} (module options token). */
+	Options: moduleToken("vela:feature-flags:options"),
+	/** The injectable {@link FeatureFlagsService}. */
+	Service: moduleToken("vela:feature-flags:service"),
+	/** The {@link FeatureFlagDriverRegistry} built from the options' drivers. */
+	DriverRegistry: moduleToken("vela:feature-flags:driver-registry")
+};
+//#endregion
+//#region \0@oxc-project+runtime@0.139.0/helpers/esm/decorateMetadata.js
+function __decorateMetadata(k, v) {
+	if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+//#endregion
+//#region \0@oxc-project+runtime@0.139.0/helpers/esm/decorateParam.js
+function __decorateParam(paramIndex, decorator) {
+	return function(target, key) {
+		decorator(target, key, paramIndex);
+	};
+}
+//#endregion
+//#region \0@oxc-project+runtime@0.139.0/helpers/esm/decorate.js
+function __decorate(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;
+}
+//#endregion
+//#region src/feature-flags.service.ts
+var _FeatureFlagsService;
+/**
+* Safely read the current request context. Returns `undefined` outside a
+* request or when ambient access isn't enabled — never throws — so the service
+* resolves and evaluates in queue / scheduled / global scope too.
+*/
+function ambientRequestContext() {
+	try {
+		return getCurrentRequestContext();
+	} catch {
+		return;
+	}
+}
+let FeatureFlagsService = _FeatureFlagsService = class FeatureFlagsService {
+	registry;
+	options;
+	boundContext;
+	logger;
+	manifest;
+	driver;
+	constructor(registry, options, logger, boundContext, boundDriver) {
+		this.registry = registry;
+		this.options = options;
+		this.boundContext = boundContext;
+		this.logger = logger ?? new Logger("FeatureFlags");
+		this.manifest = options.manifest ?? {};
+		this.driver = boundDriver ?? registry.resolve(options.default);
+	}
+	/** The name of the driver this instance targets. */
+	get driverName() {
+		return this.driver.name;
+	}
+	/**
+	* 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) {
+		if (name === this.driver.name) return this;
+		return this.clone({ driver: this.registry.get(name) });
+	}
+	/**
+	* 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) {
+		return this.clone({ context: ctx });
+	}
+	/** Evaluate a flag as a `boolean`. */
+	async getBooleanValue(flagKey, defaultValue, context) {
+		const fallback = this.fallback(flagKey, defaultValue, false);
+		return this.safe(flagKey, async () => this.driver.getBoolean(flagKey, fallback, await this.context(context)), () => fallback);
+	}
+	/** Evaluate a flag as a `string`. */
+	async getStringValue(flagKey, defaultValue, context) {
+		const fallback = this.fallback(flagKey, defaultValue, "");
+		return this.safe(flagKey, async () => this.driver.getString(flagKey, fallback, await this.context(context)), () => fallback);
+	}
+	/** Evaluate a flag as a `number`. */
+	async getNumberValue(flagKey, defaultValue, context) {
+		const fallback = this.fallback(flagKey, defaultValue, 0);
+		return this.safe(flagKey, async () => this.driver.getNumber(flagKey, fallback, await this.context(context)), () => fallback);
+	}
+	/** Evaluate a flag as a typed object. */
+	async getObjectValue(flagKey, defaultValue, context) {
+		const fallback = this.fallback(flagKey, defaultValue, {});
+		return this.safe(flagKey, async () => this.driver.getObject(flagKey, fallback, await this.context(context)), () => fallback);
+	}
+	/** Evaluate a `boolean` flag with synthesized evaluation metadata. */
+	async getBooleanDetails(flagKey, defaultValue, context) {
+		const fallback = this.fallback(flagKey, defaultValue, false);
+		return this.safe(flagKey, async () => this.details(flagKey, await this.driver.getBoolean(flagKey, fallback, await this.context(context))), (error) => this.errorDetails(flagKey, fallback, error));
+	}
+	/** Evaluate a `string` flag with synthesized evaluation metadata. */
+	async getStringDetails(flagKey, defaultValue, context) {
+		const fallback = this.fallback(flagKey, defaultValue, "");
+		return this.safe(flagKey, async () => this.details(flagKey, await this.driver.getString(flagKey, fallback, await this.context(context))), (error) => this.errorDetails(flagKey, fallback, error));
+	}
+	/** Evaluate a `number` flag with synthesized evaluation metadata. */
+	async getNumberDetails(flagKey, defaultValue, context) {
+		const fallback = this.fallback(flagKey, defaultValue, 0);
+		return this.safe(flagKey, async () => this.details(flagKey, await this.driver.getNumber(flagKey, fallback, await this.context(context))), (error) => this.errorDetails(flagKey, fallback, error));
+	}
+	/** Evaluate a typed object flag with synthesized evaluation metadata. */
+	async getObjectDetails(flagKey, defaultValue, context) {
+		const fallback = this.fallback(flagKey, defaultValue, {});
+		return this.safe(flagKey, async () => this.details(flagKey, await this.driver.getObject(flagKey, fallback, await this.context(context))), (error) => this.errorDetails(flagKey, fallback, error));
+	}
+	/**
+	* 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.
+	*/
+	async all(context) {
+		const keys = Object.keys(this.manifest);
+		let merged;
+		try {
+			merged = await this.context(context);
+		} catch (error) {
+			this.logger.warn(`Feature flag context resolution failed on driver "${this.driver.name}"; returning manifest defaults.`, { error: message(error) });
+			return { ...this.manifest };
+		}
+		const values = await Promise.all(keys.map((key) => this.evaluate(key, this.manifest[key], merged)));
+		const result = {};
+		keys.forEach((key, i) => {
+			result[key] = values[i];
+		});
+		return result;
+	}
+	/** Immutable clone with a different driver and/or bound context. */
+	clone(overrides) {
+		return new _FeatureFlagsService(this.registry, this.options, this.logger, overrides.context ?? this.boundContext, overrides.driver ?? this.driver);
+	}
+	/** Resolve the merged evaluation context (default context + per-call override). */
+	async context(callContext) {
+		const base = this.boundContext ?? ambientRequestContext();
+		if (!this.options.context || !base) return callContext;
+		const resolved = await this.options.context(base);
+		return callContext ? {
+			...resolved,
+			...callContext
+		} : resolved;
+	}
+	/** Pick the default: explicit arg, then manifest, then the type's zero value. */
+	fallback(flagKey, provided, zero) {
+		if (provided !== void 0) return provided;
+		if (flagKey in this.manifest) return this.manifest[flagKey];
+		return zero;
+	}
+	/** Evaluate a single flag, choosing the method from the declared default's type. */
+	evaluate(flagKey, declared, context) {
+		switch (typeof declared) {
+			case "boolean": return this.safe(flagKey, () => this.driver.getBoolean(flagKey, declared, context), () => declared);
+			case "number": return this.safe(flagKey, () => this.driver.getNumber(flagKey, declared, context), () => declared);
+			case "string": return this.safe(flagKey, () => this.driver.getString(flagKey, declared, context), () => declared);
+			default: return this.safe(flagKey, () => this.driver.getObject(flagKey, declared, context), () => declared);
+		}
+	}
+	/**
+	* Run an evaluation and absorb any failure into the fallback. A flag lookup
+	* must never take the caller down with it.
+	*/
+	async safe(flagKey, evaluate, onError) {
+		try {
+			return await evaluate();
+		} catch (error) {
+			this.logger.warn(`Feature flag evaluation failed for "${flagKey}" on driver "${this.driver.name}"; returning the fallback value.`, { error: message(error) });
+			return onError(error);
+		}
+	}
+	details(flagKey, value) {
+		return {
+			flagKey,
+			value,
+			reason: "STATIC"
+		};
+	}
+	errorDetails(flagKey, value, error) {
+		return {
+			flagKey,
+			value,
+			reason: "ERROR",
+			errorMessage: message(error)
+		};
+	}
+};
+FeatureFlagsService = _FeatureFlagsService = __decorate([
+	Injectable({ scope: Scope.TRANSIENT }),
+	__decorateParam(0, Inject(FEATURE_FLAG_TOKENS.DriverRegistry)),
+	__decorateParam(1, Inject(FEATURE_FLAG_TOKENS.Options)),
+	__decorateParam(2, Optional()),
+	__decorateParam(2, Inject(Logger)),
+	__decorateParam(3, Optional()),
+	__decorateParam(4, Optional()),
+	__decorateMetadata("design:paramtypes", [
+		Object,
+		Object,
+		Object,
+		Object,
+		Object
+	])
+], FeatureFlagsService);
+/** Extract a human-readable message from an unknown thrown value. */
+function message(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+//#endregion
+export { FEATURE_FLAG_TOKENS as a, MemoryFlagDriver as c, __decorateMetadata as i, memoryFlagDriver as l, __decorate as n, FeatureFlagDriverRegistry as o, __decorateParam as r, buildDriverRegistry as s, FeatureFlagsService as t, FeatureFlagError as u };
+
+//# sourceMappingURL=feature-flags.service-CNOZ1DhZ.js.map

package/dist/feature-flags.service-CNOZ1DhZ.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-flags.service-CNOZ1DhZ.js","names":[],"sources":["../src/feature-flags.error.ts","../src/drivers/memory.driver.ts","../src/drivers/registry.ts","../src/feature-flags.tokens.ts","../src/feature-flags.service.ts"],"sourcesContent":["/**\n * The single error type for `@velajs/feature-flags`.\n *\n * Note: flag *evaluation* never throws — the service absorbs driver failures\n * into the fallback value (see {@link FeatureFlagsService}). `FeatureFlagError`\n * is reserved for *configuration* faults surfaced at wiring time: an unknown\n * driver name, a duplicate driver, or an empty driver set.\n */\nexport class FeatureFlagError extends Error {\n  override name = 'FeatureFlagError';\n\n  constructor(message: string, options?: { cause?: unknown }) {\n    super(message, options?.cause !== undefined ? { cause: options.cause } : undefined);\n  }\n}\n","import type { FeatureFlagDriver } from './driver';\nimport type { FlagContext, FlagManifest, FlagValue } from '../feature-flags.types';\n\nexport interface MemoryFlagDriverOptions {\n  /** Driver name used for `use(name)` / the default-driver selection. Default `\"memory\"`. */\n  name?: string;\n  /** Initial flag values. */\n  values?: FlagManifest;\n}\n\n/**\n * In-memory {@link FeatureFlagDriver}: the default driver shipped in-package\n * and the test fake in one. Reads from an internal `Map` seeded from options\n * or mutated with {@link set}/{@link reset} — the memory driver ignores the\n * evaluation context (it does no targeting). An unknown key returns the\n * caller's `fallback`, exactly like a remote driver that can't resolve it.\n */\nexport class MemoryFlagDriver implements FeatureFlagDriver {\n  readonly name: string;\n  private readonly store: Map<string, FlagValue>;\n\n  constructor(options: MemoryFlagDriverOptions = {}) {\n    this.name = options.name ?? 'memory';\n    this.store = new Map(Object.entries(options.values ?? {}));\n  }\n\n  /** Set a flag value. Chainable. */\n  set(key: string, value: FlagValue): this {\n    this.store.set(key, value);\n    return this;\n  }\n\n  /** Remove a flag (subsequent reads return the caller's fallback). Chainable. */\n  delete(key: string): this {\n    this.store.delete(key);\n    return this;\n  }\n\n  /** True when `key` has a stored value. */\n  has(key: string): boolean {\n    return this.store.has(key);\n  }\n\n  /** Clear all flags, then optionally seed a fresh set. Chainable. */\n  reset(values?: FlagManifest): this {\n    this.store.clear();\n    if (values) {\n      for (const [key, value] of Object.entries(values)) this.store.set(key, value);\n    }\n    return this;\n  }\n\n  getBoolean(key: string, fallback: boolean, _ctx?: FlagContext): Promise<boolean> {\n    return Promise.resolve(this.read(key, fallback));\n  }\n\n  getString(key: string, fallback: string, _ctx?: FlagContext): Promise<string> {\n    return Promise.resolve(this.read(key, fallback));\n  }\n\n  getNumber(key: string, fallback: number, _ctx?: FlagContext): Promise<number> {\n    return Promise.resolve(this.read(key, fallback));\n  }\n\n  getObject<T extends object>(key: string, fallback: T, _ctx?: FlagContext): Promise<T> {\n    return Promise.resolve(this.read(key, fallback));\n  }\n\n  private read<T extends FlagValue>(key: string, fallback: T): T {\n    return this.store.has(key) ? (this.store.get(key) as T) : fallback;\n  }\n}\n\n/** Convenience factory for {@link MemoryFlagDriver}. */\nexport function memoryFlagDriver(options?: MemoryFlagDriverOptions): MemoryFlagDriver {\n  return new MemoryFlagDriver(options);\n}\n","import { FeatureFlagError } from '../feature-flags.error';\nimport type { FeatureFlagsOptions } from '../feature-flags.types';\nimport type { FeatureFlagDriver } from './driver';\nimport { MemoryFlagDriver } from './memory.driver';\n\n/**\n * The set of registered {@link FeatureFlagDriver}s plus the default selection.\n * Built once per module instance ({@link buildDriverRegistry}) and injected\n * into {@link FeatureFlagsService}; `use(name)` looks a driver up here.\n */\nexport class FeatureFlagDriverRegistry {\n  private readonly drivers = new Map<string, FeatureFlagDriver>();\n  readonly defaultName: string;\n\n  constructor(drivers: readonly FeatureFlagDriver[], defaultName?: string) {\n    if (drivers.length === 0) {\n      throw new FeatureFlagError(\n        'No feature flag drivers registered. Provide at least one driver to FeatureFlagsModule.forRoot({ drivers: [...] }).',\n      );\n    }\n    for (const driver of drivers) {\n      if (this.drivers.has(driver.name)) {\n        throw new FeatureFlagError(`Duplicate feature flag driver \"${driver.name}\".`);\n      }\n      this.drivers.set(driver.name, driver);\n    }\n    const requested = defaultName ?? drivers[0]!.name;\n    if (!this.drivers.has(requested)) {\n      throw new FeatureFlagError(`Default feature flag driver \"${requested}\" is not registered.`);\n    }\n    this.defaultName = requested;\n  }\n\n  /** Look a driver up by name; throws {@link FeatureFlagError} when unknown. */\n  get(name: string): FeatureFlagDriver {\n    const driver = this.drivers.get(name);\n    if (!driver) {\n      throw new FeatureFlagError(`Feature flag driver \"${name}\" is not registered.`);\n    }\n    return driver;\n  }\n\n  /** Resolve a named driver, or the default when `name` is omitted. */\n  resolve(name?: string): FeatureFlagDriver {\n    return this.get(name ?? this.defaultName);\n  }\n\n  /** All registered driver names. */\n  names(): string[] {\n    return [...this.drivers.keys()];\n  }\n}\n\n/**\n * Build the driver registry from module options. Falls back to a single\n * in-memory driver when none are configured, so `FeatureFlagsModule.forRoot({})`\n * yields a working (all-defaults) flags service for local development.\n */\nexport function buildDriverRegistry(options: FeatureFlagsOptions): FeatureFlagDriverRegistry {\n  const drivers =\n    options.drivers && options.drivers.length > 0 ? options.drivers : [new MemoryFlagDriver()];\n  return new FeatureFlagDriverRegistry(drivers, options.default);\n}\n","import { moduleToken } from '@velajs/vela';\nimport type { FeatureFlagDriverRegistry } from './drivers/registry';\nimport type { FeatureFlagsService } from './feature-flags.service';\nimport type { FeatureFlagsOptions } from './feature-flags.types';\n\n/**\n * Injection tokens for the feature-flags module. Named on the\n * `vela:feature-flags:<thing>` convention so identity is stable across\n * refactors and consumers can `@Inject(FEATURE_FLAG_TOKENS.Service)`.\n */\nexport const FEATURE_FLAG_TOKENS = {\n  /** The resolved {@link FeatureFlagsOptions} (module options token). */\n  Options: moduleToken<FeatureFlagsOptions>('vela:feature-flags:options'),\n  /** The injectable {@link FeatureFlagsService}. */\n  Service: moduleToken<FeatureFlagsService>('vela:feature-flags:service'),\n  /** The {@link FeatureFlagDriverRegistry} built from the options' drivers. */\n  DriverRegistry: moduleToken<FeatureFlagDriverRegistry>('vela:feature-flags:driver-registry'),\n} as const;\n","// Never-throw + manifest-default ergonomics adapted from\n// @stratal/feature-flags (MIT, © Temitayo Fadojutimi), reshaped from a single\n// Cloudflare-binding service into this driver-based, edge-pure form.\nimport {\n  Inject,\n  Injectable,\n  Logger,\n  Optional,\n  Scope,\n  getCurrentRequestContext,\n  type LoggerService,\n  type RequestContext,\n} from '@velajs/vela';\nimport type { FeatureFlagDriver } from './drivers/driver';\nimport type { FeatureFlagDriverRegistry } from './drivers/registry';\nimport { FEATURE_FLAG_TOKENS } from './feature-flags.tokens';\nimport type {\n  FeatureFlagsOptions,\n  FlagContext,\n  FlagEvaluationDetails,\n  FlagKey,\n  FlagManifest,\n  FlagValue,\n} from './feature-flags.types';\n\n/**\n * Safely read the current request context. Returns `undefined` outside a\n * request or when ambient access isn't enabled — never throws — so the service\n * resolves and evaluates in queue / scheduled / global scope too.\n */\nfunction ambientRequestContext(): RequestContext | undefined {\n  try {\n    return getCurrentRequestContext();\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * The injectable consumers reach for. A thin, type-safe, never-throw wrapper\n * over a {@link FeatureFlagDriver}, with two ergonomic additions:\n *\n * - **Manifest defaults** — omit a default and the value declared in the app's\n *   `manifest` is used (an explicit argument always wins).\n * - **Default context** — the module's `context` resolver is merged into every\n *   evaluation (per-call context overrides it), resolved from the current\n *   request and skipped automatically outside request scope.\n *\n * Switch drivers with {@link use}; bind a request with {@link forRequest} (the\n * guard does this). Evaluation NEVER throws — the driver returns the fallback\n * on evaluation errors, and the service additionally absorbs any thrown error\n * into the same fallback with a logged warning.\n *\n * `@Transient`: constructed synchronously (lazy-module-safe), a fresh instance\n * per injection, and resolvable in and out of request scope — it never\n * DI-injects `REQUEST_CONTEXT`, so it does not bubble to request scope.\n */\n@Injectable({ scope: Scope.TRANSIENT })\nexport class FeatureFlagsService {\n  private readonly logger: LoggerService;\n  private readonly manifest: FlagManifest;\n  private readonly driver: FeatureFlagDriver;\n\n  constructor(\n    @Inject(FEATURE_FLAG_TOKENS.DriverRegistry)\n    private readonly registry: FeatureFlagDriverRegistry,\n    @Inject(FEATURE_FLAG_TOKENS.Options) private readonly options: FeatureFlagsOptions,\n    @Optional() @Inject(Logger) logger?: LoggerService,\n    // The next two are never provided by DI (they carry `@Optional()` so the\n    // container leaves them `undefined`). `forRequest()` and `use()` set them\n    // when cloning; tests may pass them directly.\n    @Optional() private readonly boundContext?: RequestContext,\n    @Optional() boundDriver?: FeatureFlagDriver,\n  ) {\n    this.logger = logger ?? new Logger('FeatureFlags');\n    this.manifest = options.manifest ?? {};\n    this.driver = boundDriver ?? registry.resolve(options.default);\n  }\n\n  /** The name of the driver this instance targets. */\n  get driverName(): string {\n    return this.driver.name;\n  }\n\n  /**\n   * Switch to a different registered driver. Returns a NEW immutable instance\n   * bound to `name`; the original is unchanged. Throws if `name` is unknown.\n   */\n  use(name: string): FeatureFlagsService {\n    if (name === this.driver.name) return this;\n    return this.clone({ driver: this.registry.get(name) });\n  }\n\n  /**\n   * Bind a request context. Returns a NEW immutable instance whose evaluations\n   * merge `options.context(ctx)`. Used by {@link FeatureFlagGuard}; consumers\n   * resolved in request scope can also call it explicitly.\n   */\n  forRequest(ctx: RequestContext): FeatureFlagsService {\n    return this.clone({ context: ctx });\n  }\n\n  // ==================== EVALUATION ====================\n\n  /** Evaluate a flag as a `boolean`. */\n  async getBooleanValue(\n    flagKey: FlagKey,\n    defaultValue?: boolean,\n    context?: FlagContext,\n  ): Promise<boolean> {\n    const fallback = this.fallback(flagKey, defaultValue, false);\n    return this.safe(\n      flagKey,\n      async () => this.driver.getBoolean(flagKey, fallback, await this.context(context)),\n      () => fallback,\n    );\n  }\n\n  /** Evaluate a flag as a `string`. */\n  async getStringValue(\n    flagKey: FlagKey,\n    defaultValue?: string,\n    context?: FlagContext,\n  ): Promise<string> {\n    const fallback = this.fallback(flagKey, defaultValue, '');\n    return this.safe(\n      flagKey,\n      async () => this.driver.getString(flagKey, fallback, await this.context(context)),\n      () => fallback,\n    );\n  }\n\n  /** Evaluate a flag as a `number`. */\n  async getNumberValue(\n    flagKey: FlagKey,\n    defaultValue?: number,\n    context?: FlagContext,\n  ): Promise<number> {\n    const fallback = this.fallback(flagKey, defaultValue, 0);\n    return this.safe(\n      flagKey,\n      async () => this.driver.getNumber(flagKey, fallback, await this.context(context)),\n      () => fallback,\n    );\n  }\n\n  /** Evaluate a flag as a typed object. */\n  async getObjectValue<T extends object>(\n    flagKey: FlagKey,\n    defaultValue?: T,\n    context?: FlagContext,\n  ): Promise<T> {\n    const fallback = this.fallback(flagKey, defaultValue, {} as T);\n    return this.safe(\n      flagKey,\n      async () => this.driver.getObject<T>(flagKey, fallback, await this.context(context)),\n      () => fallback,\n    );\n  }\n\n  /** Evaluate a `boolean` flag with synthesized evaluation metadata. */\n  async getBooleanDetails(\n    flagKey: FlagKey,\n    defaultValue?: boolean,\n    context?: FlagContext,\n  ): Promise<FlagEvaluationDetails<boolean>> {\n    const fallback = this.fallback(flagKey, defaultValue, false);\n    return this.safe(\n      flagKey,\n      async () =>\n        this.details(\n          flagKey,\n          await this.driver.getBoolean(flagKey, fallback, await this.context(context)),\n        ),\n      (error) => this.errorDetails(flagKey, fallback, error),\n    );\n  }\n\n  /** Evaluate a `string` flag with synthesized evaluation metadata. */\n  async getStringDetails(\n    flagKey: FlagKey,\n    defaultValue?: string,\n    context?: FlagContext,\n  ): Promise<FlagEvaluationDetails<string>> {\n    const fallback = this.fallback(flagKey, defaultValue, '');\n    return this.safe(\n      flagKey,\n      async () =>\n        this.details(\n          flagKey,\n          await this.driver.getString(flagKey, fallback, await this.context(context)),\n        ),\n      (error) => this.errorDetails(flagKey, fallback, error),\n    );\n  }\n\n  /** Evaluate a `number` flag with synthesized evaluation metadata. */\n  async getNumberDetails(\n    flagKey: FlagKey,\n    defaultValue?: number,\n    context?: FlagContext,\n  ): Promise<FlagEvaluationDetails<number>> {\n    const fallback = this.fallback(flagKey, defaultValue, 0);\n    return this.safe(\n      flagKey,\n      async () =>\n        this.details(\n          flagKey,\n          await this.driver.getNumber(flagKey, fallback, await this.context(context)),\n        ),\n      (error) => this.errorDetails(flagKey, fallback, error),\n    );\n  }\n\n  /** Evaluate a typed object flag with synthesized evaluation metadata. */\n  async getObjectDetails<T extends object>(\n    flagKey: FlagKey,\n    defaultValue?: T,\n    context?: FlagContext,\n  ): Promise<FlagEvaluationDetails<T>> {\n    const fallback = this.fallback(flagKey, defaultValue, {} as T);\n    return this.safe(\n      flagKey,\n      async () =>\n        this.details(\n          flagKey,\n          await this.driver.getObject<T>(flagKey, fallback, await this.context(context)),\n        ),\n      (error) => this.errorDetails(flagKey, fallback, error),\n    );\n  }\n\n  /**\n   * Evaluate every flag declared in the manifest and return a `{ key: value }`\n   * map. The evaluation method is chosen from each declared default's type.\n   * A throwing context resolver falls back to the manifest defaults rather than\n   * taking the batch down.\n   */\n  async all(context?: FlagContext): Promise<Record<string, FlagValue>> {\n    const keys = Object.keys(this.manifest);\n    let merged: FlagContext | undefined;\n    try {\n      merged = await this.context(context);\n    } catch (error) {\n      this.logger.warn(\n        `Feature flag context resolution failed on driver \"${this.driver.name}\"; returning manifest defaults.`,\n        { error: message(error) },\n      );\n      return { ...this.manifest };\n    }\n    const values = await Promise.all(\n      keys.map((key) => this.evaluate(key, this.manifest[key]!, merged)),\n    );\n    const result: Record<string, FlagValue> = {};\n    keys.forEach((key, i) => {\n      result[key] = values[i]!;\n    });\n    return result;\n  }\n\n  // ==================== INTERNAL ====================\n\n  /** Immutable clone with a different driver and/or bound context. */\n  private clone(overrides: {\n    driver?: FeatureFlagDriver;\n    context?: RequestContext;\n  }): FeatureFlagsService {\n    return new FeatureFlagsService(\n      this.registry,\n      this.options,\n      this.logger,\n      overrides.context ?? this.boundContext,\n      overrides.driver ?? this.driver,\n    );\n  }\n\n  /** Resolve the merged evaluation context (default context + per-call override). */\n  private async context(callContext?: FlagContext): Promise<FlagContext | undefined> {\n    const base = this.boundContext ?? ambientRequestContext();\n    if (!this.options.context || !base) return callContext;\n    const resolved = await this.options.context(base);\n    return callContext ? { ...resolved, ...callContext } : resolved;\n  }\n\n  /** Pick the default: explicit arg, then manifest, then the type's zero value. */\n  private fallback<T extends FlagValue>(flagKey: string, provided: T | undefined, zero: T): T {\n    if (provided !== undefined) return provided;\n    if (flagKey in this.manifest) return this.manifest[flagKey] as T;\n    return zero;\n  }\n\n  /** Evaluate a single flag, choosing the method from the declared default's type. */\n  private evaluate(\n    flagKey: string,\n    declared: FlagValue,\n    context?: FlagContext,\n  ): Promise<FlagValue> {\n    switch (typeof declared) {\n      case 'boolean':\n        return this.safe(\n          flagKey,\n          () => this.driver.getBoolean(flagKey, declared, context),\n          () => declared,\n        );\n      case 'number':\n        return this.safe(\n          flagKey,\n          () => this.driver.getNumber(flagKey, declared, context),\n          () => declared,\n        );\n      case 'string':\n        return this.safe(\n          flagKey,\n          () => this.driver.getString(flagKey, declared, context),\n          () => declared,\n        );\n      default:\n        return this.safe(\n          flagKey,\n          () => this.driver.getObject(flagKey, declared as object, context),\n          () => declared,\n        );\n    }\n  }\n\n  /**\n   * Run an evaluation and absorb any failure into the fallback. A flag lookup\n   * must never take the caller down with it.\n   */\n  private async safe<T>(\n    flagKey: string,\n    evaluate: () => Promise<T>,\n    onError: (error: unknown) => T,\n  ): Promise<T> {\n    try {\n      return await evaluate();\n    } catch (error) {\n      this.logger.warn(\n        `Feature flag evaluation failed for \"${flagKey}\" on driver \"${this.driver.name}\"; returning the fallback value.`,\n        { error: message(error) },\n      );\n      return onError(error);\n    }\n  }\n\n  private details<T extends FlagValue>(flagKey: string, value: T): FlagEvaluationDetails<T> {\n    return { flagKey, value, reason: 'STATIC' };\n  }\n\n  private errorDetails<T extends FlagValue>(\n    flagKey: string,\n    value: T,\n    error: unknown,\n  ): FlagEvaluationDetails<T> {\n    return { flagKey, value, reason: 'ERROR', errorMessage: message(error) };\n  }\n}\n\n/** Extract a human-readable message from an unknown thrown value. */\nfunction message(error: unknown): string {\n  return error instanceof Error ? error.message : String(error);\n}\n"],"mappings":"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"}

package/dist/index.d.ts

@@ -1,12 +1,115 @@
-export { FeatureFlagsModule } from './feature-flags.module';
-export { FeatureFlagsService } from './feature-flags.service';
-export { FEATURE_FLAG_TOKENS } from './feature-flags.tokens';
-export type { FeatureFlagDriver } from './drivers/driver';
-export { MemoryFlagDriver, memoryFlagDriver } from './drivers/memory.driver';
-export type { MemoryFlagDriverOptions } from './drivers/memory.driver';
-export { FeatureFlagDriverRegistry, buildDriverRegistry } from './drivers/registry';
-export { FeatureFlagGuard } from './guards/feature-flag.guard';
-export { FeatureFlag, FEATURE_FLAG_METADATA } from './decorators/feature-flag.decorator';
-export type { FeatureFlagOptions, FeatureFlagMetadata, FeatureFlagDisabledBehavior, } from './decorators/feature-flag.decorator';
-export { FeatureFlagError } from './feature-flags.error';
-export type { FeatureFlagsOptions, FeatureFlagRegistry, FlagContext, FlagKey, FlagManifest, FlagValue, FlagEvaluationDetails, FlagEvaluationReason, } from './feature-flags.types';
+import { a as FeatureFlagDriverRegistry, c as FeatureFlagsOptions, d as FlagEvaluationReason, f as FlagKey, h as FeatureFlagDriver, i as FeatureFlagsService, l as FlagContext, m as FlagValue, n as MemoryFlagDriverOptions, o as buildDriverRegistry, p as FlagManifest, r as memoryFlagDriver, s as FeatureFlagRegistry, t as MemoryFlagDriver, u as FlagEvaluationDetails } from "./memory.driver-C-5Y2b7_.js";
+import { CanActivate, ExecutionContext } from "@velajs/vela";
+//#region src/feature-flags.module.d.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`.
+ */
+declare const ConfigurableModuleClass: import("@velajs/vela").ConfigurableModuleClassType<FeatureFlagsOptions, "forRoot", "create", {
+  isGlobal?: boolean;
+}>;
+declare class FeatureFlagsModule extends ConfigurableModuleClass {}
+//#endregion
+//#region src/feature-flags.tokens.d.ts
+/**
+ * Injection tokens for the feature-flags module. Named on the
+ * `vela:feature-flags:<thing>` convention so identity is stable across
+ * refactors and consumers can `@Inject(FEATURE_FLAG_TOKENS.Service)`.
+ */
+declare const FEATURE_FLAG_TOKENS: {
+  /** The resolved {@link FeatureFlagsOptions} (module options token). */
+  readonly Options: import("@velajs/vela").InjectionToken<FeatureFlagsOptions>;
+  /** The injectable {@link FeatureFlagsService}. */
+  readonly Service: import("@velajs/vela").InjectionToken<FeatureFlagsService>;
+  /** The {@link FeatureFlagDriverRegistry} built from the options' drivers. */
+  readonly DriverRegistry: import("@velajs/vela").InjectionToken<FeatureFlagDriverRegistry>;
+};
+//#endregion
+//#region src/guards/feature-flag.guard.d.ts
+/**
+ * Route gate for `@FeatureFlag()`. Reads the handler/controller metadata, then
+ * `getBooleanValue(key)`; when the flag is off it throws `NotFoundException`
+ * (the route appears hidden) or `ForbiddenException` per the decorator option.
+ * Handlers with no `@FeatureFlag()` metadata pass through untouched, so the
+ * guard is safe to register app-wide (`FeatureFlagsModule.forRoot({ isGlobal:
+ * true })`) or per-route via `@UseGuards(FeatureFlagGuard)`.
+ *
+ * It does NOT inject `REQUEST_CONTEXT` — that would make the guard request-
+ * scoped and break lazy-module materialization (which constructs every provider
+ * once, at first use, possibly outside a request). Instead it reads the request
+ * context off the per-request child container carried on the Hono context, so
+ * the module's `context` resolver still runs for the gate decision.
+ */
+declare class FeatureFlagGuard implements CanActivate {
+  private readonly flags;
+  private readonly reflector;
+  constructor(flags: FeatureFlagsService);
+  canActivate(context: ExecutionContext): Promise<boolean>;
+  /** The current request context, via the child container on the Hono context. */
+  private requestContext;
+}
+//#endregion
+//#region src/decorators/feature-flag.decorator.d.ts
+/** What the {@link FeatureFlagGuard} does when a gated flag is off. */
+type FeatureFlagDisabledBehavior = 'notFound' | 'forbidden';
+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}. */
+interface FeatureFlagMetadata {
+  key: string;
+  onDisabled: FeatureFlagDisabledBehavior;
+}
+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() { ... }
+ * }
+ * ```
+ */
+declare function FeatureFlag(key: FlagKey, options?: FeatureFlagOptions): (target: object, propertyKey?: string | symbol) => void;
+//#endregion
+//#region src/feature-flags.error.d.ts
+/**
+ * The single error type for `@velajs/feature-flags`.
+ *
+ * Note: flag *evaluation* never throws — the service absorbs driver failures
+ * into the fallback value (see {@link FeatureFlagsService}). `FeatureFlagError`
+ * is reserved for *configuration* faults surfaced at wiring time: an unknown
+ * driver name, a duplicate driver, or an empty driver set.
+ */
+declare class FeatureFlagError extends Error {
+  name: string;
+  constructor(message: string, options?: {
+    cause?: unknown;
+  });
+}
+//#endregion
+export { FEATURE_FLAG_METADATA, FEATURE_FLAG_TOKENS, FeatureFlag, type FeatureFlagDisabledBehavior, type FeatureFlagDriver, FeatureFlagDriverRegistry, FeatureFlagError, FeatureFlagGuard, type FeatureFlagMetadata, type FeatureFlagOptions, type FeatureFlagRegistry, FeatureFlagsModule, type FeatureFlagsOptions, FeatureFlagsService, type FlagContext, type FlagEvaluationDetails, type FlagEvaluationReason, type FlagKey, type FlagManifest, type FlagValue, MemoryFlagDriver, type MemoryFlagDriverOptions, buildDriverRegistry, memoryFlagDriver };
+//# sourceMappingURL=index.d.ts.map