@velajs/feature-flags 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.0
+
+Initial release.
+
+- Driver-based feature flags for Vela, authored purely on the public API
+  (`defineModule`, `Reflector`, guards) — edge-pure, no `node:*`/`Buffer`/`process`.
+- `FeatureFlagDriver` contract + in-package `MemoryFlagDriver` (default driver and test fake).
+- `FeatureFlagsService`: manifest defaults, never-throw evaluation (`getBoolean/String/Number/Object`
+  Value/Details), immutable `use(driver)`, `all()`, and a per-request `context` merge.
+- `FeatureFlagsModule` (`defineModule`, `lazy: true`) with `forRoot`/`forRootAsync` and an
+  `isGlobal` app-wide guard option.
+- `@FeatureFlag(key, { onDisabled })` + `FeatureFlagGuard` to hide routes (404) or forbid them (403).
+- `@velajs/feature-flags/testing` subpath: memory driver helpers + `createTestFeatureFlags()`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kauan Guesser
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,103 @@
+# @velajs/feature-flags
+
+Edge-first, driver-based feature flags for the [Vela](https://github.com/velajs/vela) framework.
+
+Runs on Cloudflare Workers, Deno, Bun, Node 20+, and Vercel Edge — the package source is
+edge-pure (no `node:*`, `Buffer`, or `process`). Backends plug in through one small
+`FeatureFlagDriver` contract; an in-memory driver ships in the box and doubles as the test fake.
+
+## Install
+
+```sh
+pnpm add @velajs/feature-flags
+```
+
+## Quick start
+
+```ts
+import { FeatureFlagsModule, FeatureFlagsService, memoryFlagDriver } from '@velajs/feature-flags';
+
+@Module({
+  imports: [
+    FeatureFlagsModule.forRoot({
+      drivers: [memoryFlagDriver({ values: { 'new-checkout': false } })],
+      manifest: { 'new-checkout': false, layout: 'v1' },
+      context: (ctx) => ({ userId: ctx.get('userId') }), // merged into every evaluation
+    }),
+  ],
+})
+class AppModule {}
+
+// Inject and evaluate — evaluation never throws.
+class CheckoutService {
+  constructor(@Inject(FEATURE_FLAG_TOKENS.Service) private readonly flags: FeatureFlagsService) {}
+
+  async run() {
+    if (await this.flags.getBooleanValue('new-checkout')) { /* … */ }
+    const layout = await this.flags.getStringValue('layout'); // manifest default when unset
+  }
+}
+```
+
+`forRootAsync({ inject, useFactory })` is also generated for you.
+
+## Hiding routes behind a flag
+
+```ts
+import { FeatureFlag, FeatureFlagGuard } from '@velajs/feature-flags';
+
+@UseGuards(FeatureFlagGuard)
+@Controller('/checkout')
+class CheckoutController {
+  @FeatureFlag('new-checkout')                       // 404 when off (route looks hidden)
+  @Get('/v2') v2() { /* … */ }
+
+  @FeatureFlag('beta', { onDisabled: 'forbidden' })  // 403 when off
+  @Get('/beta') beta() { /* … */ }
+}
+```
+
+Or gate every `@FeatureFlag()` route app-wide with `FeatureFlagsModule.forRoot({ isGlobal: true })`.
+
+## Drivers
+
+The in-memory driver ships here; runtime-specific drivers live in their platform packages
+(`@velajs/cloudflare` ships Flagship-binding and KV drivers), all implementing the same contract:
+
+```ts
+export 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>;
+}
+```
+
+A driver returns the caller's `fallback` (never throws) when it can't resolve a key; the service
+additionally absorbs any thrown error into the same fallback and logs a warning.
+
+## Typed flag keys
+
+Augment `FeatureFlagRegistry` to type the service methods and the `@FeatureFlag()` decorator:
+
+```ts
+declare module '@velajs/feature-flags' {
+  interface FeatureFlagRegistry {
+    'new-checkout': boolean;
+    layout: string;
+  }
+}
+```
+
+## Testing
+
+`@velajs/feature-flags/testing` re-exports the memory driver (the fake) plus a zero-DI helper:
+
+```ts
+import { createTestFeatureFlags } from '@velajs/feature-flags/testing';
+
+const { service, driver } = createTestFeatureFlags({ 'new-checkout': true });
+expect(await service.getBooleanValue('new-checkout')).toBe(true);
+driver.set('new-checkout', false);
+```

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

@@ -0,0 +1,35 @@
+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;

package/dist/decorators/feature-flag.decorator.js

@@ -0,0 +1,26 @@
+import { SetMetadata } from "@velajs/vela";
+export 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 function FeatureFlag(key, options = {}) {
+    const meta = {
+        key,
+        onDisabled: options.onDisabled ?? 'notFound'
+    };
+    return SetMetadata(FEATURE_FLAG_METADATA, meta);
+}

package/dist/drivers/driver.d.ts

@@ -0,0 +1,21 @@
+import type { FlagContext } from '../feature-flags.types';
+/**
+ * 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.
+ */
+export 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>;
+}

package/dist/drivers/driver.js

@@ -0,0 +1,13 @@
+/**
+ * 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.
+ */ export { };

package/dist/drivers/memory.driver.d.ts

@@ -0,0 +1,35 @@
+import type { FeatureFlagDriver } from './driver';
+import type { FlagContext, FlagManifest, FlagValue } from '../feature-flags.types';
+export 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.
+ */
+export 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}. */
+export declare function memoryFlagDriver(options?: MemoryFlagDriverOptions): MemoryFlagDriver;

package/dist/drivers/memory.driver.js

@@ -0,0 +1,50 @@
+/**
+ * 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.
+ */ export class MemoryFlagDriver {
+    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}. */ export function memoryFlagDriver(options) {
+    return new MemoryFlagDriver(options);
+}

package/dist/drivers/registry.d.ts

@@ -0,0 +1,24 @@
+import type { FeatureFlagsOptions } from '../feature-flags.types';
+import type { FeatureFlagDriver } from './driver';
+/**
+ * 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.
+ */
+export 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.
+ */
+export declare function buildDriverRegistry(options: FeatureFlagsOptions): FeatureFlagDriverRegistry;

package/dist/drivers/registry.js

@@ -0,0 +1,51 @@
+import { FeatureFlagError } from "../feature-flags.error.js";
+import { MemoryFlagDriver } from "./memory.driver.js";
+/**
+ * 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.
+ */ export class FeatureFlagDriverRegistry {
+    drivers = 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.
+ */ export function buildDriverRegistry(options) {
+    const drivers = options.drivers && options.drivers.length > 0 ? options.drivers : [
+        new MemoryFlagDriver()
+    ];
+    return new FeatureFlagDriverRegistry(drivers, options.default);
+}

package/dist/feature-flags.error.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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.
+ */
+export declare class FeatureFlagError extends Error {
+    name: string;
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}

package/dist/feature-flags.error.js

@@ -0,0 +1,15 @@
+/**
+ * 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.
+ */ export class FeatureFlagError extends Error {
+    name = 'FeatureFlagError';
+    constructor(message, options){
+        super(message, options?.cause !== undefined ? {
+            cause: options.cause
+        } : undefined);
+    }
+}

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

@@ -0,0 +1,21 @@
+import type { FeatureFlagsOptions } from './feature-flags.types';
+/**
+ * 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;
+}>;
+export declare class FeatureFlagsModule extends ConfigurableModuleClass {
+}
+export {};

package/dist/feature-flags.module.js

@@ -0,0 +1,63 @@
+import { APP_GUARD, Scope, defineModule } from "@velajs/vela";
+import { buildDriverRegistry } from "./drivers/registry.js";
+import { FeatureFlagGuard } from "./guards/feature-flag.guard.js";
+import { FeatureFlagsService } from "./feature-flags.service.js";
+import { FEATURE_FLAG_TOKENS } from "./feature-flags.tokens.js";
+/**
+ * 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
+                    ]
+                },
+                // Transient: a fresh service per injection, so `use()`/`forRequest()`
+                // clones and per-request context stay isolated. The service never injects
+                // REQUEST_CONTEXT, so it does not bubble to request scope and remains
+                // resolvable in queue / scheduled / global scope.
+                {
+                    provide: FEATURE_FLAG_TOKENS.Service,
+                    useClass: FeatureFlagsService,
+                    scope: Scope.TRANSIENT
+                },
+                FeatureFlagGuard
+            ],
+            exports: [
+                FEATURE_FLAG_TOKENS.Service,
+                FEATURE_FLAG_TOKENS.DriverRegistry,
+                FeatureFlagGuard,
+                OPTIONS
+            ]
+        })
+});
+export class FeatureFlagsModule extends ConfigurableModuleClass {
+}

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

@@ -0,0 +1,83 @@
+import { type LoggerService, type RequestContext } from '@velajs/vela';
+import type { FeatureFlagDriver } from './drivers/driver';
+import type { FeatureFlagDriverRegistry } from './drivers/registry';
+import type { FeatureFlagsOptions, FlagContext, FlagEvaluationDetails, FlagKey, FlagValue } from './feature-flags.types';
+/**
+ * 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.
+ */
+export 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;
+}

package/dist/feature-flags.service.js

@@ -0,0 +1,208 @@
+function _ts_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;
+}
+function _ts_metadata(k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+function _ts_param(paramIndex, decorator) {
+    return function(target, key) {
+        decorator(target, key, paramIndex);
+    };
+}
+// Never-throw + manifest-default ergonomics adapted from
+// @stratal/feature-flags (MIT, © Temitayo Fadojutimi), reshaped from a single
+// Cloudflare-binding service into this driver-based, edge-pure form.
+import { Inject, Injectable, Logger, Optional, Scope, getCurrentRequestContext } from "@velajs/vela";
+import { FEATURE_FLAG_TOKENS } from "./feature-flags.tokens.js";
+/**
+ * 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 undefined;
+    }
+}
+export class FeatureFlagsService {
+    registry;
+    options;
+    boundContext;
+    logger;
+    manifest;
+    driver;
+    constructor(registry, options, logger, // The next two are never provided by DI (they carry `@Optional()` so the
+    // container leaves them `undefined`). `forRequest()` and `use()` set them
+    // when cloning; tests may pass them directly.
+    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
+        });
+    }
+    // ==================== EVALUATION ====================
+    /** 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;
+    }
+    // ==================== INTERNAL ====================
+    /** 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 !== undefined) 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 = _ts_decorate([
+    Injectable({
+        scope: Scope.TRANSIENT
+    }),
+    _ts_param(0, Inject(FEATURE_FLAG_TOKENS.DriverRegistry)),
+    _ts_param(1, Inject(FEATURE_FLAG_TOKENS.Options)),
+    _ts_param(2, Optional()),
+    _ts_param(2, Inject(Logger)),
+    _ts_param(3, Optional()),
+    _ts_param(4, Optional()),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof FeatureFlagDriverRegistry === "undefined" ? Object : FeatureFlagDriverRegistry,
+        typeof FeatureFlagsOptions === "undefined" ? Object : FeatureFlagsOptions,
+        typeof LoggerService === "undefined" ? Object : LoggerService,
+        typeof RequestContext === "undefined" ? Object : RequestContext,
+        typeof FeatureFlagDriver === "undefined" ? Object : FeatureFlagDriver
+    ])
+], FeatureFlagsService);
+/** Extract a human-readable message from an unknown thrown value. */ function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/feature-flags.tokens.d.ts

@@ -0,0 +1,16 @@
+import type { FeatureFlagDriverRegistry } from './drivers/registry';
+import type { FeatureFlagsService } from './feature-flags.service';
+import type { FeatureFlagsOptions } from './feature-flags.types';
+/**
+ * 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)`.
+ */
+export 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>;
+};

package/dist/feature-flags.tokens.js

@@ -0,0 +1,10 @@
+import { moduleToken } from "@velajs/vela";
+/**
+ * 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)`.
+ */ export 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')
+};

package/dist/feature-flags.types.d.ts

@@ -0,0 +1,71 @@
+import type { RequestContext } from '@velajs/vela';
+import type { FeatureFlagDriver } from './drivers/driver';
+/**
+ * A value a feature flag can resolve to. Mirrors the four evaluation methods
+ * on {@link FeatureFlagDriver}.
+ */
+export 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.
+ */
+export 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;
+ *   }
+ * }
+ * ```
+ */
+export interface FeatureFlagRegistry {
+}
+/**
+ * A flag key. Narrows to the declared {@link FeatureFlagRegistry} keys when the
+ * app augments it; falls back to `string` otherwise.
+ */
+export 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.
+ */
+export type FlagManifest = Record<string, FlagValue>;
+/** Why an evaluation returned the value it did. */
+export type FlagEvaluationReason = 'STATIC' | 'DEFAULT' | 'ERROR';
+/** A flag value plus the metadata the service synthesizes around a driver read. */
+export interface FlagEvaluationDetails<T extends FlagValue = FlagValue> {
+    flagKey: string;
+    value: T;
+    reason: FlagEvaluationReason;
+    errorMessage?: string;
+}
+/**
+ * Feature-flags module configuration.
+ */
+export 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>;
+}

package/dist/feature-flags.types.js

@@ -0,0 +1,3 @@
+/**
+ * Feature-flags module configuration.
+ */ export { };

package/dist/guards/feature-flag.guard.d.ts

@@ -0,0 +1,24 @@
+import { type CanActivate, type ExecutionContext } from '@velajs/vela';
+import type { FeatureFlagsService } from '../feature-flags.service';
+/**
+ * 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.
+ */
+export 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;
+}

package/dist/guards/feature-flag.guard.js

@@ -0,0 +1,52 @@
+function _ts_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;
+}
+function _ts_metadata(k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+function _ts_param(paramIndex, decorator) {
+    return function(target, key) {
+        decorator(target, key, paramIndex);
+    };
+}
+import { ForbiddenException, Inject, Injectable, NotFoundException, REQUEST_CONTEXT, Reflector } from "@velajs/vela";
+import { FEATURE_FLAG_METADATA } from "../decorators/feature-flag.decorator.js";
+import { FEATURE_FLAG_TOKENS } from "../feature-flags.tokens.js";
+export 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);
+        const flags = requestContext ? this.flags.forRequest(requestContext) : this.flags;
+        const enabled = await flags.getBooleanValue(meta.key);
+        if (enabled) 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 {
+            const container = context.getContext().get('container');
+            return container?.resolve(REQUEST_CONTEXT);
+        } catch  {
+            return undefined;
+        }
+    }
+}
+FeatureFlagGuard = _ts_decorate([
+    Injectable(),
+    _ts_param(0, Inject(FEATURE_FLAG_TOKENS.Service)),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof FeatureFlagsService === "undefined" ? Object : FeatureFlagsService
+    ])
+], FeatureFlagGuard);

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+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';

package/dist/index.js

@@ -0,0 +1,15 @@
+// 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";

package/dist/testing/index.d.ts

@@ -0,0 +1,25 @@
+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;
+}
+/**
+ * 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 declare function createTestFeatureFlags(values?: FlagManifest, options?: Pick<FeatureFlagsOptions, 'manifest' | 'context'>): TestFeatureFlags;

package/dist/testing/index.js

@@ -0,0 +1,36 @@
+// @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";
+/**
+ * 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
+    };
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@velajs/feature-flags",
+  "version": "0.1.0",
+  "description": "Edge-first, driver-based feature flags for the Vela framework",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "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",
+    "@swc/core": "^1.15.43",
+    "@velajs/testing": "^0.4.0",
+    "@velajs/vela": "^1.12.0",
+    "hono": "^4.12.27",
+    "typescript": "^6.0.3",
+    "unplugin-swc": "^1.5.9",
+    "vitest": "^4.1.9"
+  },
+  "scripts": {
+    "build": "rm -rf dist && swc src -d dist --strip-leading-paths && tsc --emitDeclarationOnly",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}