@strav/flag 0.4.31 → 1.0.0-alpha.42

package/src/flag_provider.ts

@@ -1,33 +1,57 @@
-import { ServiceProvider } from '@strav/kernel'
-import type { Application } from '@strav/kernel'
-import FlagManager from './flag_manager.ts'
+/**
+ * `FlagProvider` — registers `FlagManager` under its own token, backed
+ * by the in-process `MemoryFlagStore` by default. Apps that need
+ * cross-process persistence swap in `PostgresFlagProvider` from
+ * `@strav/flag/postgres` — both register under the same `FlagManager`
+ * token, so consumers don't change their inject.
+ *
+ * `define` lets callers register feature resolvers up-front in the
+ * same place they wire the provider:
+ *
+ *   new FlagProvider({
+ *     define(flags) {
+ *       flags.define('beta-ui', (scope) => scope.startsWith('User:'))
+ *     },
+ *   })
+ *
+ * Resolvers can also be added later (e.g. from another provider's
+ * `boot()`) via `app.resolve(FlagManager).define(...)`.
+ */
+
+import { type Application, ConfigRepository, EventBus, ServiceProvider } from '@strav/kernel'
+import { MemoryFlagStore } from './drivers/memory/memory_flag_store.ts'
+import { FlagManager } from './flag_manager.ts'
+import type { FlagConfig } from './types.ts'
 
 export interface FlagProviderOptions {
-  /** Auto-create the features table. Default: `true` */
-  ensureTables?: boolean
+  /**
+   * Hook invoked at boot, after the manager is created. Use it to
+   * register flag resolvers.
+   */
+  define?: (flags: FlagManager) => void | Promise<void>
 }
 
-export default class FlagProvider extends ServiceProvider {
-  readonly name = 'flag'
-  override readonly dependencies = ['config', 'database']
+export class FlagProvider extends ServiceProvider {
+  override readonly name = 'flag'
+  override readonly dependencies = ['config']
 
-  constructor(private options?: FlagProviderOptions) {
+  constructor(private readonly options: FlagProviderOptions = {}) {
     super()
   }
 
   override register(app: Application): void {
-    app.singleton(FlagManager)
+    app.singleton(FlagManager, (c) => {
+      const cfg = (c.resolve(ConfigRepository).get('flag') as FlagConfig | undefined) ?? {}
+      return new FlagManager({
+        store: new MemoryFlagStore(),
+        events: c.resolve(EventBus),
+        config: cfg,
+      })
+    })
   }
 
   override async boot(app: Application): Promise<void> {
-    app.resolve(FlagManager)
-
-    if (this.options?.ensureTables !== false) {
-      await FlagManager.ensureTables()
-    }
-  }
-
-  override shutdown(): void {
-    FlagManager.reset()
+    const flags = app.resolve(FlagManager)
+    if (this.options.define) await this.options.define(flags)
   }
 }

package/src/http/ensure_feature.ts

@@ -0,0 +1,56 @@
+/**
+ * `ensureFeature` — route guard that 403s when a flag is inactive.
+ *
+ *   router.get('/beta', ensureFeature('beta-ui'), betaHandler)
+ *
+ *   router.group(
+ *     { middleware: [auth(), ensureFeature('analytics', (ctx) => ctx.auth?.user ?? null)] },
+ *     (r) => { ... }
+ *   )
+ *
+ * Scope source: by default the middleware reads `ctx.auth?.user` if
+ * the `@strav/auth` augmentation is installed and falls back to the
+ * global scope otherwise. Pass `scopeFrom` for per-route logic (team,
+ * tenant, custom subject).
+ *
+ * Returns a `Response` directly instead of throwing — the response is
+ * symmetrical for HTML and JSON callers (both get a 403), and the
+ * caller doesn't need to wire a custom exception handler.
+ */
+
+import type { HttpContext, MiddlewareFn } from '@strav/http'
+import { FlagManager } from '../flag_manager.ts'
+import type { Scopeable } from '../types.ts'
+
+export interface EnsureFeatureOptions {
+  /** Custom value when the feature is denied. Default: `{ error: 'Feature not available' }`. */
+  body?: unknown
+  /** Custom status. Default: `403`. */
+  status?: number
+  /** Where to read the scope from. Default: `ctx.auth?.user ?? null`. */
+  scopeFrom?: (ctx: HttpContext) => Scopeable | null | undefined
+}
+
+export function ensureFeature(feature: string, options: EnsureFeatureOptions = {}): MiddlewareFn {
+  return async (ctx, next) => {
+    const flags = ctx.container.resolve(FlagManager)
+    const scope = options.scopeFrom ? options.scopeFrom(ctx) : defaultScope(ctx)
+    const active = await flags.active(feature, scope)
+    if (active) return next()
+    return new Response(
+      JSON.stringify(options.body ?? { error: 'Feature not available', feature }),
+      {
+        status: options.status ?? 403,
+        headers: { 'Content-Type': 'application/json' },
+      },
+    )
+  }
+}
+
+function defaultScope(ctx: HttpContext): Scopeable | null {
+  // `ctx.auth` only exists when `@strav/auth` is loaded — the
+  // augmentation is declared there. Read defensively so this
+  // middleware works in apps without auth wired.
+  const auth = (ctx as unknown as { auth?: { user?: Scopeable | null } }).auth
+  return auth?.user ?? null
+}

package/src/http/index.ts

@@ -0,0 +1 @@
+export { type EnsureFeatureOptions, ensureFeature } from './ensure_feature.ts'

package/src/index.ts

@@ -1,40 +1,30 @@
-// 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
+// Public API of @strav/flag.
+//
+// Root barrel exports the manager + types + errors + the in-memory
+// store and its provider. Backends and integrations ship under
+// subpaths:
+//   - `@strav/flag/memory`    (re-exports the in-memory store)
+//   - `@strav/flag/postgres`  (Postgres backplane + migration helper)
+//   - `@strav/flag/http`      (ensureFeature route guard)
+//   - `@strav/flag/console`   (flag:* CLI commands)
+
+export { MemoryFlagStore } from './drivers/memory/memory_flag_store.ts'
 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, MissingScopeError } from './errors.ts'
-
-// Types
-export type {
-  FlagConfig,
-  DriverConfig,
-  Scopeable,
-  ScopeKey,
-  StoredFeature,
-  FeatureResolver,
-  FeatureClass,
-  FeatureClassConstructor,
-  FlagActor,
-  FlagUpdatedEvent,
+export { FeatureNotDefinedError, FlagError, MissingScopeError } from './flag_error.ts'
+export { FlagManager, type FlagManagerOptions } from './flag_manager.ts'
+export { FlagProvider, type FlagProviderOptions } from './flag_provider.ts'
+export { PendingScopedFeature } from './pending_scope.ts'
+export {
+  type FeatureClass,
+  type FeatureClassConstructor,
+  type FeatureResolver,
+  type FlagActor,
+  type FlagConfig,
+  type FlagDeletedEvent,
+  type FlagResolvedEvent,
+  type FlagUpdatedEvent,
+  GLOBAL_SCOPE,
+  type Scopeable,
+  type ScopeKey,
+  type StoredFeature,
 } from './types.ts'
-export { GLOBAL_SCOPE } from './types.ts'

package/src/pending_scope.ts

@@ -1,47 +1,59 @@
+/**
+ * `PendingScopedFeature` — the fluent return value of
+ * `FlagManager.for(scope)`. Lets call sites read several features for
+ * the same scope without repeating the scope argument.
+ *
+ *   const flags = app.resolve(FlagManager).for(ctx.auth.user)
+ *   if (await flags.active('beta-ui')) { ... }
+ *   const limit = await flags.value('upload-limit')
+ */
+
+import type { FlagManager } from './flag_manager.ts'
 import type { FlagActor, 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) {}
+export class PendingScopedFeature {
+  constructor(
+    private readonly manager: FlagManager,
+    private readonly scope: Scopeable,
+  ) {}
 
   value(feature: string): Promise<unknown> {
-    return FlagManager.value(feature, this.scope)
+    return this.manager.value(feature, this.scope)
   }
 
   active(feature: string): Promise<boolean> {
-    return FlagManager.active(feature, this.scope)
+    return this.manager.active(feature, this.scope)
   }
 
   inactive(feature: string): Promise<boolean> {
-    return FlagManager.inactive(feature, this.scope)
+    return this.manager.inactive(feature, this.scope)
   }
 
   when<A, I>(
     feature: string,
     onActive: (value: unknown) => A | Promise<A>,
-    onInactive: () => I | Promise<I>
+    onInactive: () => I | Promise<I>,
   ): Promise<A | I> {
-    return FlagManager.when(feature, onActive, onInactive, this.scope)
+    return this.manager.when(feature, onActive, onInactive, this.scope)
   }
 
   activate(feature: string, value?: unknown, actor?: FlagActor | null): Promise<void> {
-    return FlagManager.activate(feature, value, this.scope, actor)
+    return this.manager.activate(feature, value, this.scope, actor)
   }
 
   deactivate(feature: string, actor?: FlagActor | null): Promise<void> {
-    return FlagManager.deactivate(feature, this.scope, actor)
+    return this.manager.deactivate(feature, this.scope, actor)
   }
 
   forget(feature: string): Promise<void> {
-    return FlagManager.forget(feature, this.scope)
+    return this.manager.forget(feature, this.scope)
   }
 
   values(features: string[]): Promise<Map<string, unknown>> {
-    return FlagManager.values(features, this.scope)
+    return this.manager.values(features, this.scope)
   }
 
   load(features: string[]): Promise<void> {
-    return FlagManager.load(features, [this.scope])
+    return this.manager.load(features, [this.scope])
   }
 }

package/src/types.ts

@@ -1,21 +1,40 @@
-// ── Scope ────────────────────────────────────────────────────────────────
+/**
+ * Public types for `@strav/flag`.
+ *
+ * Feature flags are evaluated against a *scope* — usually the
+ * authenticated user, sometimes a team / workspace / tenant, sometimes
+ * nothing at all (the global scope). The scope is serialized to a
+ * stable string key and used as the lookup discriminator both in the
+ * in-process cache and the persistent store.
+ */
+
+// ─── Scope ────────────────────────────────────────────────────────────────
 
-/** Any object that can be used as a feature flag scope. */
+/**
+ * Anything that can serve as a flag scope. The shape is intentionally
+ * loose — any object with an `id` works (`User`, `Team`, `Tenant`,
+ * `ApiKey`, etc.). Pass `featureScope()` to override the type prefix
+ * when the constructor name is unstable (minified bundles, mixins).
+ */
 export interface Scopeable {
   id: string | number
-  /** Optional type discriminator. Defaults to constructor.name. */
+  /** Optional discriminator. Defaults to `constructor.name`. */
   featureScope?: () => string
 }
 
-/** Serialized scope string, e.g. 'User:42', '__global__'. */
+/** Serialized scope string, e.g. `User:42`, `Team:7`, `__global__`. */
 export type ScopeKey = string
 
-/** The global scope sentinel. */
+/** Sentinel for the global (no scope) bucket. */
 export const GLOBAL_SCOPE = '__global__'
 
-// ── Feature definitions ──────────────────────────────────────────────────
+// ─── Feature definitions ──────────────────────────────────────────────────
 
-/** A closure that resolves a feature value for the given scope. */
+/**
+ * A closure that resolves a feature value for the given scope key.
+ * The return value is whatever the app wants — a `boolean` for binary
+ * flags, a `string`/`number`/object for A-B variants or rich config.
+ */
 export type FeatureResolver<T = unknown> = (scope: ScopeKey) => T | Promise<T>
 
 /** A class-based feature with a `resolve` method. */
@@ -29,7 +48,7 @@ export interface FeatureClassConstructor {
   new (): FeatureClass
 }
 
-// ── Stored values ────────────────────────────────────────────────────────
+// ─── Stored values ────────────────────────────────────────────────────────
 
 export interface StoredFeature {
   feature: string
@@ -39,53 +58,58 @@ export interface StoredFeature {
   updatedAt: Date
 }
 
-// ── Configuration ────────────────────────────────────────────────────────
+// ─── Configuration ────────────────────────────────────────────────────────
 
 export interface FlagConfig {
-  default: string
-  drivers: Record<string, DriverConfig>
   /**
-   * When true, calls to `value`/`active`/`activate`/`deactivate` that
-   * resolve to a null/undefined scope throw `MissingScopeError` instead
-   * of silently falling back to the global scope. Default: `false`
-   * (backwards-compatible). Apps that derive scope from request state
-   * (e.g., `ctx.get('user')`) should turn this on so a forgotten or
-   * unauthenticated request raises a loud error instead of evaluating
-   * the global flag for everyone.
+   * When `true`, the read path (`value` / `active` / `inactive` /
+   * `when` / `values` / `forget`) called without a scope throws
+   * `MissingScopeError` instead of silently falling back to the
+   * global value. Defends against the common bug where middleware
+   * forgets to pass `ctx.auth.user` and a per-user flag silently
+   * evaluates the global flag for everyone.
+   *
+   * The write path keeps loose semantics — `activate('flag')` with no
+   * scope still writes the global value. Callers that want explicit
+   * global writes should prefer `activateForEveryone()`.
+   *
+   * Default: `false` (backward-compatible). Turn on in new apps.
    */
-  strictScopes: boolean
+  strictScopes?: boolean
 }
 
-export interface DriverConfig {
-  driver: string
-  [key: string]: unknown
-}
-
-// ── Actor ────────────────────────────────────────────────────────────────
+// ─── Actor ────────────────────────────────────────────────────────────────
 
 /**
- * Who initiated a flag write. Optional, but recommended for accountability.
- * Carried through to `flag:updated` event payloads so an audit hook can
- * record the change. See `@strav/flag` CLAUDE.md for the recommended
- * audit-integration pattern.
+ * Who initiated a flag write. Optional but recommended for audit. The
+ * actor is carried through to the `flag:updated` event so an audit
+ * hook can record who flipped what.
  */
 export interface FlagActor {
   type: string
   id: string | number
 }
 
-// ── Events ───────────────────────────────────────────────────────────────
+// ─── Events ───────────────────────────────────────────────────────────────
+
+export interface FlagResolvedEvent {
+  feature: string
+  scope: ScopeKey
+  value: unknown
+}
 
-/**
- * Payload for the `flag:updated` Emitter event. Fired when `activate()`
- * or `deactivate()` writes to the store.
- */
 export interface FlagUpdatedEvent {
   feature: string
   scope: ScopeKey
   value: unknown
-  /** Previous stored value (if any) — undefined when the flag had no prior store entry. */
+  /** Previous stored value, or `undefined` if the flag had no entry. */
   previous: unknown
-  /** Who initiated the change. `null` when the caller did not provide an actor. */
+  /** Caller-supplied actor, `null` when not provided. */
   actor: FlagActor | null
 }
+
+export interface FlagDeletedEvent {
+  feature: string
+  /** Specific scope, or `*` for purge / purgeAll. */
+  scope: ScopeKey | '*'
+}

package/src/commands/flag_commands.ts

@@ -1,99 +0,0 @@
-import type { Command } from 'commander'
-import chalk from 'chalk'
-import { bootstrap, shutdown } from '@strav/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

@@ -1,79 +0,0 @@
-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
-  }
-}