@strav/flag 0.1.0

package/README.md

@@ -0,0 +1,66 @@
+# @stravigor/flag
+
+Feature flags for the [Strav](https://www.npmjs.com/package/@stravigor/core) framework. Define, scope, and toggle features with database persistence, in-memory drivers, and per-user/team targeting.
+
+## Install
+
+```bash
+bun add @stravigor/flag
+bun strav install flag
+```
+
+Requires `@stravigor/core` as a peer dependency.
+
+## Setup
+
+```ts
+import { FlagProvider } from '@stravigor/flag'
+
+app.use(new FlagProvider())
+```
+
+## Usage
+
+```ts
+import { flag } from '@stravigor/flag'
+
+// Check if a feature is active
+if (await flag.active('dark-mode')) {
+  // feature is enabled
+}
+
+// Scoped to a user or team
+if (await flag.for(user).active('beta-dashboard')) {
+  // enabled for this user
+}
+
+// Rich values
+const limit = await flag.value('upload-limit', 10)
+```
+
+## Middleware
+
+```ts
+import { ensureFeature } from '@stravigor/flag'
+
+router.get('/beta', ensureFeature('beta-dashboard'), betaHandler)
+```
+
+## Drivers
+
+- **Database** — persistent feature flags in `_strav_features`
+- **Array** — in-memory driver for testing
+
+## CLI
+
+```bash
+bun strav flag:setup    # Create the features table
+```
+
+## Documentation
+
+See the full [Flag guide](../../guides/flag.md).
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@strav/flag",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Feature flags for the Strav framework",
+  "license": "MIT",
+  "exports": {
+    ".": "./src/index.ts",
+    "./*": "./src/*.ts"
+  },
+  "strav": {
+    "commands": "src/commands"
+  },
+  "files": [
+    "src/",
+    "stubs/",
+    "package.json",
+    "tsconfig.json"
+  ],
+  "peerDependencies": {
+    "@strav/kernel": "0.1.0",
+    "@strav/database": "0.1.0",
+    "@strav/http": "0.1.0",
+    "@strav/cli": "0.1.0"
+  },
+  "scripts": {
+    "test": "bun test tests/",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "commander": "^14.0.3"
+  }
+}

package/src/commands/flag_commands.ts

@@ -0,0 +1,99 @@
+import type { Command } from 'commander'
+import chalk from 'chalk'
+import { bootstrap, shutdown } from '@stravigor/cli'
+import FlagManager from '../flag_manager.ts'
+
+export function register(program: Command): void {
+  program
+    .command('flag:setup')
+    .description('Create the feature flag storage table')
+    .action(async () => {
+      let db
+      try {
+        const { db: database, config } = await bootstrap()
+        db = database
+
+        new FlagManager(db, config)
+
+        console.log(chalk.dim('Creating features table...'))
+        await FlagManager.ensureTables()
+        console.log(chalk.green('Features table created successfully.'))
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err instanceof Error ? err.message : err}`))
+        process.exit(1)
+      } finally {
+        if (db) await shutdown(db)
+      }
+    })
+
+  program
+    .command('flag:purge [feature]')
+    .description('Purge stored feature flag values')
+    .option('--all', 'Purge all features')
+    .action(async (feature?: string, options?: { all?: boolean }) => {
+      let db
+      try {
+        const { db: database, config } = await bootstrap()
+        db = database
+
+        new FlagManager(db, config)
+
+        if (options?.all || !feature) {
+          console.log(chalk.dim('Purging all feature flags...'))
+          await FlagManager.purgeAll()
+          console.log(chalk.green('All feature flags purged.'))
+        } else {
+          console.log(chalk.dim(`Purging feature "${feature}"...`))
+          await FlagManager.purge(feature)
+          console.log(chalk.green(`Feature "${feature}" purged.`))
+        }
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err instanceof Error ? err.message : err}`))
+        process.exit(1)
+      } finally {
+        if (db) await shutdown(db)
+      }
+    })
+
+  program
+    .command('flag:list')
+    .description('List all stored feature flags')
+    .action(async () => {
+      let db
+      try {
+        const { db: database, config } = await bootstrap()
+        db = database
+
+        new FlagManager(db, config)
+
+        const names = await FlagManager.stored()
+
+        if (names.length === 0) {
+          console.log(chalk.dim('No stored feature flags.'))
+          return
+        }
+
+        console.log(chalk.bold(`Stored feature flags (${names.length}):\n`))
+        for (const name of names) {
+          const records = await FlagManager.store().allFor(name)
+          console.log(
+            `  ${chalk.cyan(name)} ${chalk.dim(`(${records.length} scope${records.length === 1 ? '' : 's'})`)}`
+          )
+          for (const r of records) {
+            const val =
+              typeof r.value === 'boolean'
+                ? r.value
+                  ? chalk.green('active')
+                  : chalk.red('inactive')
+                : chalk.yellow(JSON.stringify(r.value))
+            console.log(`    ${chalk.dim(r.scope)} → ${val}`)
+          }
+        }
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err instanceof Error ? err.message : err}`))
+        process.exit(1)
+      } finally {
+        if (db) await shutdown(db)
+      }
+    })
+}

package/src/drivers/array_driver.ts

@@ -0,0 +1,79 @@
+import type { FeatureStore } from '../feature_store.ts'
+import type { ScopeKey, StoredFeature } from '../types.ts'
+
+/** In-memory feature store for testing. */
+export class ArrayDriver implements FeatureStore {
+  readonly name = 'array'
+  private data = new Map<string, { value: unknown; createdAt: Date; updatedAt: Date }>()
+
+  private key(feature: string, scope: ScopeKey): string {
+    return `${feature}\0${scope}`
+  }
+
+  async get(feature: string, scope: ScopeKey): Promise<unknown | undefined> {
+    return this.data.get(this.key(feature, scope))?.value
+  }
+
+  async getMany(features: string[], scope: ScopeKey): Promise<Map<string, unknown>> {
+    const result = new Map<string, unknown>()
+    for (const feature of features) {
+      const entry = this.data.get(this.key(feature, scope))
+      if (entry !== undefined) result.set(feature, entry.value)
+    }
+    return result
+  }
+
+  async set(feature: string, scope: ScopeKey, value: unknown): Promise<void> {
+    const existing = this.data.get(this.key(feature, scope))
+    const now = new Date()
+    this.data.set(this.key(feature, scope), {
+      value,
+      createdAt: existing?.createdAt ?? now,
+      updatedAt: now,
+    })
+  }
+
+  async setMany(
+    entries: Array<{ feature: string; scope: ScopeKey; value: unknown }>
+  ): Promise<void> {
+    for (const e of entries) await this.set(e.feature, e.scope, e.value)
+  }
+
+  async forget(feature: string, scope: ScopeKey): Promise<void> {
+    this.data.delete(this.key(feature, scope))
+  }
+
+  async purge(feature: string): Promise<void> {
+    for (const key of this.data.keys()) {
+      if (key.startsWith(`${feature}\0`)) this.data.delete(key)
+    }
+  }
+
+  async purgeAll(): Promise<void> {
+    this.data.clear()
+  }
+
+  async featureNames(): Promise<string[]> {
+    const names = new Set<string>()
+    for (const key of this.data.keys()) {
+      names.add(key.split('\0')[0]!)
+    }
+    return [...names]
+  }
+
+  async allFor(feature: string): Promise<StoredFeature[]> {
+    const results: StoredFeature[] = []
+    for (const [key, entry] of this.data) {
+      if (key.startsWith(`${feature}\0`)) {
+        results.push({
+          feature,
+          scope: key.split('\0')[1]!,
+          value: entry.value,
+          createdAt: entry.createdAt,
+          updatedAt: entry.updatedAt,
+        })
+      }
+    }
+    return results
+  }
+}

package/src/drivers/database_driver.ts

@@ -0,0 +1,139 @@
+import type { SQL } from 'bun'
+import type { FeatureStore } from '../feature_store.ts'
+import type { ScopeKey, StoredFeature } from '../types.ts'
+
+/** PostgreSQL-backed feature store using `_strav_features`. */
+export class DatabaseDriver implements FeatureStore {
+  readonly name = 'database'
+
+  constructor(private sql: SQL) {}
+
+  async ensureTable(): Promise<void> {
+    await this.sql`
+      CREATE TABLE IF NOT EXISTS "_strav_features" (
+        "id"         BIGSERIAL PRIMARY KEY,
+        "feature"    VARCHAR(255) NOT NULL,
+        "scope"      VARCHAR(255) NOT NULL,
+        "value"      JSONB NOT NULL DEFAULT 'true',
+        "created_at" TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+        "updated_at" TIMESTAMPTZ NOT NULL DEFAULT NOW()
+      )
+    `
+
+    await this.sql`
+      CREATE UNIQUE INDEX IF NOT EXISTS "idx_strav_features_lookup"
+        ON "_strav_features" ("feature", "scope")
+    `
+  }
+
+  async get(feature: string, scope: ScopeKey): Promise<unknown | undefined> {
+    const rows = await this.sql`
+      SELECT "value" FROM "_strav_features"
+      WHERE "feature" = ${feature} AND "scope" = ${scope}
+      LIMIT 1
+    `
+    if (rows.length === 0) return undefined
+    return parseValue(rows[0].value)
+  }
+
+  async getMany(features: string[], scope: ScopeKey): Promise<Map<string, unknown>> {
+    if (features.length === 0) return new Map()
+
+    const rows = await this.sql`
+      SELECT "feature", "value" FROM "_strav_features"
+      WHERE "feature" IN ${this.sql(features)} AND "scope" = ${scope}
+    `
+
+    const result = new Map<string, unknown>()
+    for (const row of rows) {
+      result.set(row.feature as string, parseValue(row.value))
+    }
+    return result
+  }
+
+  async set(feature: string, scope: ScopeKey, value: unknown): Promise<void> {
+    const jsonValue = JSON.stringify(value)
+    await this.sql`
+      INSERT INTO "_strav_features" ("feature", "scope", "value", "created_at", "updated_at")
+      VALUES (${feature}, ${scope}, ${jsonValue}::jsonb, NOW(), NOW())
+      ON CONFLICT ("feature", "scope")
+      DO UPDATE SET "value" = ${jsonValue}::jsonb, "updated_at" = NOW()
+    `
+  }
+
+  async setMany(
+    entries: Array<{ feature: string; scope: ScopeKey; value: unknown }>
+  ): Promise<void> {
+    if (entries.length === 0) return
+    if (entries.length === 1) {
+      await this.set(entries[0]!.feature, entries[0]!.scope, entries[0]!.value)
+      return
+    }
+
+    await this.sql.begin(async tx => {
+      for (const e of entries) {
+        const jsonValue = JSON.stringify(e.value)
+        await tx`
+          INSERT INTO "_strav_features" ("feature", "scope", "value", "created_at", "updated_at")
+          VALUES (${e.feature}, ${e.scope}, ${jsonValue}::jsonb, NOW(), NOW())
+          ON CONFLICT ("feature", "scope")
+          DO UPDATE SET "value" = ${jsonValue}::jsonb, "updated_at" = NOW()
+        `
+      }
+    })
+  }
+
+  async forget(feature: string, scope: ScopeKey): Promise<void> {
+    await this.sql`
+      DELETE FROM "_strav_features"
+      WHERE "feature" = ${feature} AND "scope" = ${scope}
+    `
+  }
+
+  async purge(feature: string): Promise<void> {
+    await this.sql`
+      DELETE FROM "_strav_features"
+      WHERE "feature" = ${feature}
+    `
+  }
+
+  async purgeAll(): Promise<void> {
+    await this.sql`DELETE FROM "_strav_features"`
+  }
+
+  async featureNames(): Promise<string[]> {
+    const rows = await this.sql`
+      SELECT DISTINCT "feature" FROM "_strav_features"
+      ORDER BY "feature"
+    `
+    return rows.map((r: Record<string, unknown>) => r.feature as string)
+  }
+
+  async allFor(feature: string): Promise<StoredFeature[]> {
+    const rows = await this.sql`
+      SELECT "feature", "scope", "value", "created_at", "updated_at"
+      FROM "_strav_features"
+      WHERE "feature" = ${feature}
+      ORDER BY "scope"
+    `
+
+    return rows.map((row: Record<string, unknown>) => ({
+      feature: row.feature as string,
+      scope: row.scope as ScopeKey,
+      value: parseValue(row.value),
+      createdAt: row.created_at as Date,
+      updatedAt: row.updated_at as Date,
+    }))
+  }
+}
+
+function parseValue(raw: unknown): unknown {
+  if (typeof raw === 'string') {
+    try {
+      return JSON.parse(raw)
+    } catch {
+      return raw
+    }
+  }
+  return raw
+}

package/src/errors.ts

@@ -0,0 +1,9 @@
+import { StravError } from '@stravigor/kernel'
+
+export class FlagError extends StravError {}
+
+export class FeatureNotDefinedError extends FlagError {
+  constructor(feature: string) {
+    super(`Feature "${feature}" is not defined. Register it with flag.define().`)
+  }
+}

package/src/feature_store.ts

@@ -0,0 +1,33 @@
+import type { ScopeKey, StoredFeature } from './types.ts'
+
+/** Contract that every feature flag storage driver must implement. */
+export interface FeatureStore {
+  readonly name: string
+
+  /** Retrieve the stored value. Returns `undefined` if not yet resolved. */
+  get(feature: string, scope: ScopeKey): Promise<unknown | undefined>
+
+  /** Retrieve stored values for multiple features for a single scope. */
+  getMany(features: string[], scope: ScopeKey): Promise<Map<string, unknown>>
+
+  /** Store a resolved value (upsert). */
+  set(feature: string, scope: ScopeKey, value: unknown): Promise<void>
+
+  /** Store multiple resolved values at once. */
+  setMany(entries: Array<{ feature: string; scope: ScopeKey; value: unknown }>): Promise<void>
+
+  /** Remove the stored value for a feature+scope pair. */
+  forget(feature: string, scope: ScopeKey): Promise<void>
+
+  /** Remove ALL stored values for a feature (all scopes). */
+  purge(feature: string): Promise<void>
+
+  /** Remove all stored values for all features. */
+  purgeAll(): Promise<void>
+
+  /** List all distinct feature names that have stored values. */
+  featureNames(): Promise<string[]>
+
+  /** List all stored records for a feature. */
+  allFor(feature: string): Promise<StoredFeature[]>
+}

package/src/flag_manager.ts

@@ -0,0 +1,346 @@
+import { inject, Configuration, Emitter, ConfigurationError } from '@stravigor/kernel'
+import { Database } from '@stravigor/database'
+import type {
+  FlagConfig,
+  DriverConfig,
+  FeatureResolver,
+  FeatureClassConstructor,
+  ScopeKey,
+  Scopeable,
+} from './types.ts'
+import { GLOBAL_SCOPE } from './types.ts'
+import type { FeatureStore } from './feature_store.ts'
+import { DatabaseDriver } from './drivers/database_driver.ts'
+import { ArrayDriver } from './drivers/array_driver.ts'
+import { FeatureNotDefinedError } from './errors.ts'
+import PendingScopedFeature from './pending_scope.ts'
+
+@inject
+export default class FlagManager {
+  private static _config: FlagConfig
+  private static _db: Database
+  private static _stores = new Map<string, FeatureStore>()
+  private static _extensions = new Map<string, (config: DriverConfig) => FeatureStore>()
+  private static _definitions = new Map<string, FeatureResolver>()
+  private static _classFeatures = new Map<string, FeatureClassConstructor>()
+  private static _cache = new Map<string, unknown>()
+
+  constructor(db: Database, config: Configuration) {
+    FlagManager._db = db
+    FlagManager._config = {
+      default: config.get('flag.default', 'database') as string,
+      drivers: config.get('flag.drivers', {}) as Record<string, DriverConfig>,
+    }
+  }
+
+  // ── Configuration ──────────────────────────────────────────────────
+
+  static get config(): FlagConfig {
+    if (!FlagManager._config) {
+      throw new ConfigurationError(
+        'FlagManager not configured. Resolve it through the container first.'
+      )
+    }
+    return FlagManager._config
+  }
+
+  // ── Feature definitions ────────────────────────────────────────────
+
+  static define(name: string, resolver: FeatureResolver | boolean): void {
+    if (typeof resolver === 'boolean') {
+      const val = resolver
+      FlagManager._definitions.set(name, () => val)
+    } else {
+      FlagManager._definitions.set(name, resolver)
+    }
+  }
+
+  static defineClass(feature: FeatureClassConstructor): void {
+    const key = feature.key ?? toKebab(feature.name)
+    FlagManager._classFeatures.set(key, feature)
+  }
+
+  /** Get all defined feature names (closures + classes). */
+  static defined(): string[] {
+    return [...FlagManager._definitions.keys(), ...FlagManager._classFeatures.keys()]
+  }
+
+  // ── Scope helpers ──────────────────────────────────────────────────
+
+  static serializeScope(scope: Scopeable | null | undefined): ScopeKey {
+    if (!scope) return GLOBAL_SCOPE
+    const type =
+      typeof scope.featureScope === 'function' ? scope.featureScope() : scope.constructor.name
+    return `${type}:${scope.id}`
+  }
+
+  // ── Core resolution ────────────────────────────────────────────────
+
+  static async value(feature: string, scope?: Scopeable | null): Promise<unknown> {
+    const scopeKey = FlagManager.serializeScope(scope)
+    const cacheKey = FlagManager.cacheKey(feature, scopeKey)
+
+    // 1. Check in-memory cache
+    if (FlagManager._cache.has(cacheKey)) {
+      return FlagManager._cache.get(cacheKey)
+    }
+
+    // 2. Check store
+    const store = FlagManager.store()
+    const stored = await store.get(feature, scopeKey)
+    if (stored !== undefined) {
+      FlagManager._cache.set(cacheKey, stored)
+      return stored
+    }
+
+    // 3. Resolve
+    const value = await FlagManager.resolveFeature(feature, scopeKey)
+
+    // 4. Persist
+    await store.set(feature, scopeKey, value)
+    FlagManager._cache.set(cacheKey, value)
+
+    await Emitter.emit('flag:resolved', { feature, scope: scopeKey, value })
+
+    return value
+  }
+
+  static async active(feature: string, scope?: Scopeable | null): Promise<boolean> {
+    return Boolean(await FlagManager.value(feature, scope))
+  }
+
+  static async inactive(feature: string, scope?: Scopeable | null): Promise<boolean> {
+    return !(await FlagManager.active(feature, scope))
+  }
+
+  static async when<TActive, TInactive>(
+    feature: string,
+    onActive: (value: unknown) => TActive | Promise<TActive>,
+    onInactive: () => TInactive | Promise<TInactive>,
+    scope?: Scopeable | null
+  ): Promise<TActive | TInactive> {
+    const value = await FlagManager.value(feature, scope)
+    return value ? onActive(value) : onInactive()
+  }
+
+  // ── Scoped API ─────────────────────────────────────────────────────
+
+  static for(scope: Scopeable): PendingScopedFeature {
+    return new PendingScopedFeature(scope)
+  }
+
+  // ── Manual activation/deactivation ─────────────────────────────────
+
+  static async activate(feature: string, value?: unknown, scope?: Scopeable | null): Promise<void> {
+    const scopeKey = FlagManager.serializeScope(scope)
+    const resolved = value !== undefined ? value : true
+    await FlagManager.store().set(feature, scopeKey, resolved)
+    FlagManager._cache.set(FlagManager.cacheKey(feature, scopeKey), resolved)
+    await Emitter.emit('flag:updated', { feature, scope: scopeKey, value: resolved })
+  }
+
+  static async deactivate(feature: string, scope?: Scopeable | null): Promise<void> {
+    const scopeKey = FlagManager.serializeScope(scope)
+    await FlagManager.store().set(feature, scopeKey, false)
+    FlagManager._cache.set(FlagManager.cacheKey(feature, scopeKey), false)
+    await Emitter.emit('flag:updated', { feature, scope: scopeKey, value: false })
+  }
+
+  static async activateForEveryone(feature: string, value?: unknown): Promise<void> {
+    return FlagManager.activate(feature, value)
+  }
+
+  static async deactivateForEveryone(feature: string): Promise<void> {
+    return FlagManager.deactivate(feature)
+  }
+
+  // ── Batch operations ───────────────────────────────────────────────
+
+  static async values(features: string[], scope?: Scopeable | null): Promise<Map<string, unknown>> {
+    const result = new Map<string, unknown>()
+    const scopeKey = FlagManager.serializeScope(scope)
+
+    // Collect cache hits and misses
+    const misses: string[] = []
+    for (const f of features) {
+      const ck = FlagManager.cacheKey(f, scopeKey)
+      if (FlagManager._cache.has(ck)) {
+        result.set(f, FlagManager._cache.get(ck))
+      } else {
+        misses.push(f)
+      }
+    }
+
+    if (misses.length === 0) return result
+
+    // Check store for remaining
+    const stored = await FlagManager.store().getMany(misses, scopeKey)
+    const stillMissing: string[] = []
+
+    for (const f of misses) {
+      if (stored.has(f)) {
+        const val = stored.get(f)
+        result.set(f, val)
+        FlagManager._cache.set(FlagManager.cacheKey(f, scopeKey), val)
+      } else {
+        stillMissing.push(f)
+      }
+    }
+
+    // Resolve any that aren't stored yet
+    for (const f of stillMissing) {
+      const val = await FlagManager.resolveFeature(f, scopeKey)
+      await FlagManager.store().set(f, scopeKey, val)
+      FlagManager._cache.set(FlagManager.cacheKey(f, scopeKey), val)
+      result.set(f, val)
+      await Emitter.emit('flag:resolved', { feature: f, scope: scopeKey, value: val })
+    }
+
+    return result
+  }
+
+  /** Get all stored feature names. */
+  static async stored(): Promise<string[]> {
+    return FlagManager.store().featureNames()
+  }
+
+  // ── Eager loading ──────────────────────────────────────────────────
+
+  static async load(features: string[], scopes: Scopeable[]): Promise<void> {
+    const store = FlagManager.store()
+
+    for (const scope of scopes) {
+      const scopeKey = FlagManager.serializeScope(scope)
+      const stored = await store.getMany(features, scopeKey)
+
+      for (const [f, val] of stored) {
+        FlagManager._cache.set(FlagManager.cacheKey(f, scopeKey), val)
+      }
+
+      // Resolve any not yet stored
+      for (const f of features) {
+        if (!stored.has(f)) {
+          const val = await FlagManager.resolveFeature(f, scopeKey)
+          await store.set(f, scopeKey, val)
+          FlagManager._cache.set(FlagManager.cacheKey(f, scopeKey), val)
+        }
+      }
+    }
+  }
+
+  // ── Cleanup ────────────────────────────────────────────────────────
+
+  static async forget(feature: string, scope?: Scopeable | null): Promise<void> {
+    const scopeKey = FlagManager.serializeScope(scope)
+    await FlagManager.store().forget(feature, scopeKey)
+    FlagManager._cache.delete(FlagManager.cacheKey(feature, scopeKey))
+    await Emitter.emit('flag:deleted', { feature, scope: scopeKey })
+  }
+
+  static async purge(feature: string): Promise<void> {
+    await FlagManager.store().purge(feature)
+    // Clear all cache entries for this feature
+    for (const key of FlagManager._cache.keys()) {
+      if (key.startsWith(`${feature}\0`)) FlagManager._cache.delete(key)
+    }
+    await Emitter.emit('flag:deleted', { feature, scope: '*' })
+  }
+
+  static async purgeAll(): Promise<void> {
+    await FlagManager.store().purgeAll()
+    FlagManager._cache.clear()
+    await Emitter.emit('flag:deleted', { feature: '*', scope: '*' })
+  }
+
+  // ── Driver management ──────────────────────────────────────────────
+
+  static store(name?: string): FeatureStore {
+    const key = name ?? FlagManager.config.default
+
+    let store = FlagManager._stores.get(key)
+    if (store) return store
+
+    const driverConfig = FlagManager.config.drivers[key]
+    if (!driverConfig) {
+      throw new ConfigurationError(`Flag driver "${key}" is not configured.`)
+    }
+
+    store = FlagManager.createStore(key, driverConfig)
+    FlagManager._stores.set(key, store)
+    return store
+  }
+
+  static extend(name: string, factory: (config: DriverConfig) => FeatureStore): void {
+    FlagManager._extensions.set(name, factory)
+  }
+
+  // ── Cache ──────────────────────────────────────────────────────────
+
+  static flushCache(): void {
+    FlagManager._cache.clear()
+  }
+
+  // ── Table setup ────────────────────────────────────────────────────
+
+  static async ensureTables(): Promise<void> {
+    const store = FlagManager.store()
+    if (store instanceof DatabaseDriver) {
+      await store.ensureTable()
+    }
+  }
+
+  // ── Reset ──────────────────────────────────────────────────────────
+
+  static reset(): void {
+    FlagManager._stores.clear()
+    FlagManager._extensions.clear()
+    FlagManager._definitions.clear()
+    FlagManager._classFeatures.clear()
+    FlagManager._cache.clear()
+    FlagManager._config = undefined as any
+    FlagManager._db = undefined as any
+  }
+
+  // ── Private helpers ────────────────────────────────────────────────
+
+  private static cacheKey(feature: string, scope: ScopeKey): string {
+    return `${feature}\0${scope}`
+  }
+
+  private static async resolveFeature(feature: string, scope: ScopeKey): Promise<unknown> {
+    // Try closure definition first
+    const resolver = FlagManager._definitions.get(feature)
+    if (resolver) return resolver(scope)
+
+    // Try class-based definition
+    const Cls = FlagManager._classFeatures.get(feature)
+    if (Cls) return new Cls().resolve(scope)
+
+    throw new FeatureNotDefinedError(feature)
+  }
+
+  private static createStore(name: string, config: DriverConfig): FeatureStore {
+    const driverName = config.driver ?? name
+
+    const extension = FlagManager._extensions.get(driverName)
+    if (extension) return extension(config)
+
+    switch (driverName) {
+      case 'database':
+        return new DatabaseDriver(FlagManager._db.sql)
+      case 'array':
+        return new ArrayDriver()
+      default:
+        throw new ConfigurationError(
+          `Unknown flag driver "${driverName}". Register it with FlagManager.extend().`
+        )
+    }
+  }
+}
+
+function toKebab(name: string): string {
+  return name
+    .replace(/([a-z])([A-Z])/g, '$1-$2')
+    .replace(/[\s_]+/g, '-')
+    .toLowerCase()
+}

package/src/flag_provider.ts

@@ -0,0 +1,33 @@
+import { ServiceProvider } from '@stravigor/kernel'
+import type { Application } from '@stravigor/kernel'
+import FlagManager from './flag_manager.ts'
+
+export interface FlagProviderOptions {
+  /** Auto-create the features table. Default: `true` */
+  ensureTables?: boolean
+}
+
+export default class FlagProvider extends ServiceProvider {
+  readonly name = 'flag'
+  override readonly dependencies = ['config', 'database']
+
+  constructor(private options?: FlagProviderOptions) {
+    super()
+  }
+
+  override register(app: Application): void {
+    app.singleton(FlagManager)
+  }
+
+  override async boot(app: Application): Promise<void> {
+    app.resolve(FlagManager)
+
+    if (this.options?.ensureTables !== false) {
+      await FlagManager.ensureTables()
+    }
+  }
+
+  override shutdown(): void {
+    FlagManager.reset()
+  }
+}

package/src/helpers.ts

@@ -0,0 +1,109 @@
+import FlagManager from './flag_manager.ts'
+import PendingScopedFeature from './pending_scope.ts'
+import type { FeatureStore } from './feature_store.ts'
+import type { Scopeable, FeatureResolver, FeatureClassConstructor, DriverConfig } from './types.ts'
+
+/**
+ * Flag helper — the primary convenience API.
+ *
+ * @example
+ * import { flag } from '@stravigor/flag'
+ *
+ * flag.define('new-checkout', (scope) => scope.startsWith('User:'))
+ *
+ * if (await flag.active('new-checkout')) { ... }
+ */
+export const flag = {
+  define(name: string, resolver: FeatureResolver | boolean): void {
+    FlagManager.define(name, resolver)
+  },
+
+  defineClass(feature: FeatureClassConstructor): void {
+    FlagManager.defineClass(feature)
+  },
+
+  active(feature: string, scope?: Scopeable | null): Promise<boolean> {
+    return FlagManager.active(feature, scope)
+  },
+
+  inactive(feature: string, scope?: Scopeable | null): Promise<boolean> {
+    return FlagManager.inactive(feature, scope)
+  },
+
+  value(feature: string, scope?: Scopeable | null): Promise<unknown> {
+    return FlagManager.value(feature, scope)
+  },
+
+  when<A, I>(
+    feature: string,
+    onActive: (value: unknown) => A | Promise<A>,
+    onInactive: () => I | Promise<I>,
+    scope?: Scopeable | null
+  ): Promise<A | I> {
+    return FlagManager.when(feature, onActive, onInactive, scope)
+  },
+
+  for(scope: Scopeable): PendingScopedFeature {
+    return FlagManager.for(scope)
+  },
+
+  activate(feature: string, value?: unknown, scope?: Scopeable | null): Promise<void> {
+    return FlagManager.activate(feature, value, scope)
+  },
+
+  deactivate(feature: string, scope?: Scopeable | null): Promise<void> {
+    return FlagManager.deactivate(feature, scope)
+  },
+
+  activateForEveryone(feature: string, value?: unknown): Promise<void> {
+    return FlagManager.activateForEveryone(feature, value)
+  },
+
+  deactivateForEveryone(feature: string): Promise<void> {
+    return FlagManager.deactivateForEveryone(feature)
+  },
+
+  values(features: string[], scope?: Scopeable | null): Promise<Map<string, unknown>> {
+    return FlagManager.values(features, scope)
+  },
+
+  forget(feature: string, scope?: Scopeable | null): Promise<void> {
+    return FlagManager.forget(feature, scope)
+  },
+
+  purge(feature: string): Promise<void> {
+    return FlagManager.purge(feature)
+  },
+
+  purgeAll(): Promise<void> {
+    return FlagManager.purgeAll()
+  },
+
+  load(features: string[], scopes: Scopeable[]): Promise<void> {
+    return FlagManager.load(features, scopes)
+  },
+
+  store(name?: string): FeatureStore {
+    return FlagManager.store(name)
+  },
+
+  extend(name: string, factory: (config: DriverConfig) => FeatureStore): void {
+    FlagManager.extend(name, factory)
+  },
+
+  defined(): string[] {
+    return FlagManager.defined()
+  },
+
+  stored(): Promise<string[]> {
+    return FlagManager.stored()
+  },
+
+  flushCache(): void {
+    FlagManager.flushCache()
+  },
+
+  ensureTables(): Promise<void> {
+    return FlagManager.ensureTables()
+  },
+}

package/src/index.ts

@@ -0,0 +1,38 @@
+// Manager
+export { default, default as FlagManager } from './flag_manager.ts'
+
+// Provider
+export { default as FlagProvider } from './flag_provider.ts'
+export type { FlagProviderOptions } from './flag_provider.ts'
+
+// Helper
+export { flag } from './helpers.ts'
+
+// Store interface
+export type { FeatureStore } from './feature_store.ts'
+
+// Drivers
+export { DatabaseDriver } from './drivers/database_driver.ts'
+export { ArrayDriver } from './drivers/array_driver.ts'
+
+// Scoped API
+export { default as PendingScopedFeature } from './pending_scope.ts'
+
+// Middleware
+export { ensureFeature } from './middleware/ensure_feature.ts'
+
+// Errors
+export { FlagError, FeatureNotDefinedError } from './errors.ts'
+
+// Types
+export type {
+  FlagConfig,
+  DriverConfig,
+  Scopeable,
+  ScopeKey,
+  StoredFeature,
+  FeatureResolver,
+  FeatureClass,
+  FeatureClassConstructor,
+} from './types.ts'
+export { GLOBAL_SCOPE } from './types.ts'

package/src/middleware/ensure_feature.ts

@@ -0,0 +1,36 @@
+import type { Middleware } from '@stravigor/http'
+import FlagManager from '../flag_manager.ts'
+import type { Scopeable } from '../types.ts'
+
+/**
+ * Route protection middleware — returns 403 if the feature is not active.
+ *
+ * Uses `ctx.get('user')` as the default scope if available.
+ *
+ * @example
+ * router.group({ middleware: [auth(), ensureFeature('beta-ui')] }, (r) => { ... })
+ *
+ * // With custom scope extractor
+ * r.get('/team/:id', compose([ensureFeature('analytics', (ctx) => ctx.get('team'))], handler))
+ */
+export function ensureFeature(
+  feature: string,
+  scopeExtractor?: (ctx: Parameters<Middleware>[0]) => Scopeable | null
+): Middleware {
+  return async (ctx, next) => {
+    const scope = scopeExtractor
+      ? scopeExtractor(ctx)
+      : ((ctx.get('user') as Scopeable | undefined) ?? null)
+
+    const isActive = await FlagManager.active(feature, scope)
+
+    if (!isActive) {
+      return new Response(JSON.stringify({ error: 'Feature not available' }), {
+        status: 403,
+        headers: { 'Content-Type': 'application/json' },
+      })
+    }
+
+    return next()
+  }
+}

package/src/pending_scope.ts

@@ -0,0 +1,47 @@
+import type { Scopeable } from './types.ts'
+import FlagManager from './flag_manager.ts'
+
+/** Fluent scoped feature check — created by `FlagManager.for(scope)`. */
+export default class PendingScopedFeature {
+  constructor(private scope: Scopeable) {}
+
+  value(feature: string): Promise<unknown> {
+    return FlagManager.value(feature, this.scope)
+  }
+
+  active(feature: string): Promise<boolean> {
+    return FlagManager.active(feature, this.scope)
+  }
+
+  inactive(feature: string): Promise<boolean> {
+    return FlagManager.inactive(feature, this.scope)
+  }
+
+  when<A, I>(
+    feature: string,
+    onActive: (value: unknown) => A | Promise<A>,
+    onInactive: () => I | Promise<I>
+  ): Promise<A | I> {
+    return FlagManager.when(feature, onActive, onInactive, this.scope)
+  }
+
+  activate(feature: string, value?: unknown): Promise<void> {
+    return FlagManager.activate(feature, value, this.scope)
+  }
+
+  deactivate(feature: string): Promise<void> {
+    return FlagManager.deactivate(feature, this.scope)
+  }
+
+  forget(feature: string): Promise<void> {
+    return FlagManager.forget(feature, this.scope)
+  }
+
+  values(features: string[]): Promise<Map<string, unknown>> {
+    return FlagManager.values(features, this.scope)
+  }
+
+  load(features: string[]): Promise<void> {
+    return FlagManager.load(features, [this.scope])
+  }
+}

package/src/types.ts

@@ -0,0 +1,52 @@
+// ── Scope ────────────────────────────────────────────────────────────────
+
+/** Any object that can be used as a feature flag scope. */
+export interface Scopeable {
+  id: string | number
+  /** Optional type discriminator. Defaults to constructor.name. */
+  featureScope?: () => string
+}
+
+/** Serialized scope string, e.g. 'User:42', '__global__'. */
+export type ScopeKey = string
+
+/** The global scope sentinel. */
+export const GLOBAL_SCOPE = '__global__'
+
+// ── Feature definitions ──────────────────────────────────────────────────
+
+/** A closure that resolves a feature value for the given scope. */
+export type FeatureResolver<T = unknown> = (scope: ScopeKey) => T | Promise<T>
+
+/** A class-based feature with a `resolve` method. */
+export interface FeatureClass {
+  readonly key?: string
+  resolve(scope: ScopeKey): unknown | Promise<unknown>
+}
+
+export interface FeatureClassConstructor {
+  key?: string
+  new (): FeatureClass
+}
+
+// ── Stored values ────────────────────────────────────────────────────────
+
+export interface StoredFeature {
+  feature: string
+  scope: ScopeKey
+  value: unknown
+  createdAt: Date
+  updatedAt: Date
+}
+
+// ── Configuration ────────────────────────────────────────────────────────
+
+export interface FlagConfig {
+  default: string
+  drivers: Record<string, DriverConfig>
+}
+
+export interface DriverConfig {
+  driver: string
+  [key: string]: unknown
+}

package/stubs/config/flag.ts

@@ -0,0 +1,16 @@
+import { env } from '@stravigor/kernel'
+
+export default {
+  /** The default feature flag storage driver. */
+  default: env('FLAG_DRIVER', 'database'),
+
+  drivers: {
+    database: {
+      driver: 'database',
+    },
+
+    array: {
+      driver: 'array',
+    },
+  },
+}

package/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../tsconfig.json",
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "tests"]
+}