@stravigor/banner 0.4.4

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@stravigor/banner",
+  "version": "0.4.4",
+  "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": {
+    "@stravigor/core": "0.4.3"
+  },
+  "scripts": {
+    "test": "bun test tests/",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/banner_manager.ts

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

package/src/banner_provider.ts

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

package/src/commands/banner_commands.ts

@@ -0,0 +1,94 @@
+import type { Command } from 'commander'
+import chalk from 'chalk'
+import { bootstrap, shutdown } from '@stravigor/core/cli/bootstrap'
+import BannerManager from '../banner_manager.ts'
+
+export function register(program: Command): void {
+  program
+    .command('banner:setup')
+    .description('Create the feature flag storage table')
+    .action(async () => {
+      let db
+      try {
+        const { db: database, config } = await bootstrap()
+        db = database
+
+        new BannerManager(db, config)
+
+        console.log(chalk.dim('Creating features table...'))
+        await BannerManager.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('banner: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 BannerManager(db, config)
+
+        if (options?.all || !feature) {
+          console.log(chalk.dim('Purging all feature flags...'))
+          await BannerManager.purgeAll()
+          console.log(chalk.green('All feature flags purged.'))
+        } else {
+          console.log(chalk.dim(`Purging feature "${feature}"...`))
+          await BannerManager.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('banner:list')
+    .description('List all stored feature flags')
+    .action(async () => {
+      let db
+      try {
+        const { db: database, config } = await bootstrap()
+        db = database
+
+        new BannerManager(db, config)
+
+        const names = await BannerManager.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 BannerManager.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,77 @@
+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,122 @@
+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
+    for (const e of entries) await this.set(e.feature, e.scope, e.value)
+  }
+
+  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/core/exceptions/strav_error'
+
+export class BannerError extends StravError {}
+
+export class FeatureNotDefinedError extends BannerError {
+  constructor(feature: string) {
+    super(`Feature "${feature}" is not defined. Register it with banner.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/helpers.ts

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

package/src/index.ts

@@ -0,0 +1,38 @@
+// Manager
+export { default, default as BannerManager } from './banner_manager.ts'
+
+// Provider
+export { default as BannerProvider } from './banner_provider.ts'
+export type { BannerProviderOptions } from './banner_provider.ts'
+
+// Helper
+export { banner } 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 { BannerError, FeatureNotDefinedError } from './errors.ts'
+
+// Types
+export type {
+  BannerConfig,
+  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/core/http/middleware'
+import BannerManager from '../banner_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 BannerManager.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 BannerManager from './banner_manager.ts'
+
+/** Fluent scoped feature check — created by `BannerManager.for(scope)`. */
+export default class PendingScopedFeature {
+  constructor(private scope: Scopeable) {}
+
+  value(feature: string): Promise<unknown> {
+    return BannerManager.value(feature, this.scope)
+  }
+
+  active(feature: string): Promise<boolean> {
+    return BannerManager.active(feature, this.scope)
+  }
+
+  inactive(feature: string): Promise<boolean> {
+    return BannerManager.inactive(feature, this.scope)
+  }
+
+  when<A, I>(
+    feature: string,
+    onActive: (value: unknown) => A | Promise<A>,
+    onInactive: () => I | Promise<I>
+  ): Promise<A | I> {
+    return BannerManager.when(feature, onActive, onInactive, this.scope)
+  }
+
+  activate(feature: string, value?: unknown): Promise<void> {
+    return BannerManager.activate(feature, value, this.scope)
+  }
+
+  deactivate(feature: string): Promise<void> {
+    return BannerManager.deactivate(feature, this.scope)
+  }
+
+  forget(feature: string): Promise<void> {
+    return BannerManager.forget(feature, this.scope)
+  }
+
+  values(features: string[]): Promise<Map<string, unknown>> {
+    return BannerManager.values(features, this.scope)
+  }
+
+  load(features: string[]): Promise<void> {
+    return BannerManager.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 BannerConfig {
+  default: string
+  drivers: Record<string, DriverConfig>
+}
+
+export interface DriverConfig {
+  driver: string
+  [key: string]: unknown
+}

package/stubs/config/banner.ts

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

package/tsconfig.json

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