@strav/flag 0.4.31 → 1.0.0-alpha.43

package/src/flag_manager.ts

@@ -1,75 +1,101 @@
-import { inject, Configuration, Emitter, ConfigurationError } from '@strav/kernel'
-import { Database } from '@strav/database'
-import type {
-  FlagConfig,
-  DriverConfig,
-  FeatureResolver,
-  FeatureClassConstructor,
-  FlagActor,
-  ScopeKey,
-  Scopeable,
-} from './types.ts'
-import { GLOBAL_SCOPE } from './types.ts'
+/**
+ * `FlagManager` — the primary `@strav/flag` surface. Instances are
+ * resolved from the container; static state would defeat per-app
+ * isolation (test parallelism, multi-tenant test suites). Same shape
+ * as `Cache` / `Broadcaster` — singleton-via-container, not
+ * singleton-via-module.
+ *
+ * Resolution flow for `value(feature, scope)`:
+ *   1. Check the in-process cache (`feature\0scope` key).
+ *   2. Check the persistent `FeatureStore`. Cache + return on hit.
+ *   3. Run the registered resolver (closure or class). Persist the
+ *      result so subsequent reads short-circuit at step 2.
+ *
+ * Resolver execution is one-shot: the FIRST evaluation against a
+ * given scope persists, and subsequent reads of the same `(feature,
+ * scope)` return the stored value verbatim — even if the resolver's
+ * logic later changes. That's deliberate (rollouts must be stable);
+ * apps that want re-evaluation should `forget(feature, scope)` or
+ * `purge(feature)` after the resolver change.
+ */
+
+import type { EventBus } from '@strav/kernel'
 import type { FeatureStore } from './feature_store.ts'
-import { DatabaseDriver } from './drivers/database_driver.ts'
-import { ArrayDriver } from './drivers/array_driver.ts'
-import { FeatureNotDefinedError, MissingScopeError } 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>,
-      strictScopes: config.get('flag.strictScopes', false) as boolean,
-    }
+import { FeatureNotDefinedError, MissingScopeError } from './flag_error.ts'
+import { PendingScopedFeature } from './pending_scope.ts'
+import {
+  type FeatureClassConstructor,
+  type FeatureResolver,
+  type FlagActor,
+  type FlagConfig,
+  type FlagDeletedEvent,
+  type FlagResolvedEvent,
+  type FlagUpdatedEvent,
+  GLOBAL_SCOPE,
+  type Scopeable,
+  type ScopeKey,
+} from './types.ts'
+
+export interface FlagManagerOptions {
+  store: FeatureStore
+  events?: EventBus
+  config?: FlagConfig
+}
+
+export class FlagManager {
+  private readonly store: FeatureStore
+  private readonly events: EventBus | undefined
+  private readonly config: FlagConfig
+  private readonly definitions = new Map<string, FeatureResolver>()
+  private readonly classFeatures = new Map<string, FeatureClassConstructor>()
+  private readonly cache = new Map<string, unknown>()
+
+  constructor(options: FlagManagerOptions) {
+    this.store = options.store
+    this.events = options.events
+    this.config = options.config ?? {}
   }
 
-  // ── Configuration ──────────────────────────────────────────────────
+  // ─── Driver access ─────────────────────────────────────────────────
 
-  static get config(): FlagConfig {
-    if (!FlagManager._config) {
-      throw new ConfigurationError(
-        'FlagManager not configured. Resolve it through the container first.'
-      )
-    }
-    return FlagManager._config
+  /** The underlying store. Useful for migrations / diagnostics. */
+  driver(): FeatureStore {
+    return this.store
   }
 
-  // ── Feature definitions ────────────────────────────────────────────
+  // ─── Feature definitions ───────────────────────────────────────────
 
-  static define(name: string, resolver: FeatureResolver | boolean): void {
+  /**
+   * Register a feature.
+   *
+   *   flags.define('beta-ui', true)                       // always on
+   *   flags.define('beta-ui', false)                      // always off
+   *   flags.define('beta-ui', (scope) => scope.startsWith('User:42'))
+   */
+  define(name: string, resolver: FeatureResolver | boolean): void {
     if (typeof resolver === 'boolean') {
-      const val = resolver
-      FlagManager._definitions.set(name, () => val)
+      const fixed = resolver
+      this.definitions.set(name, () => fixed)
     } else {
-      FlagManager._definitions.set(name, resolver)
+      this.definitions.set(name, resolver)
     }
   }
 
-  static defineClass(feature: FeatureClassConstructor): void {
+  /** Register a class-based feature. The class is `new`'d per evaluation. */
+  defineClass(feature: FeatureClassConstructor): void {
     const key = feature.key ?? toKebab(feature.name)
-    FlagManager._classFeatures.set(key, feature)
+    this.classFeatures.set(key, feature)
   }
 
-  /** Get all defined feature names (closures + classes). */
-  static defined(): string[] {
-    return [...FlagManager._definitions.keys(), ...FlagManager._classFeatures.keys()]
+  /** Names of every registered feature (closure + class). */
+  defined(): string[] {
+    return [...this.definitions.keys(), ...this.classFeatures.keys()]
   }
 
-  // ── Scope helpers ──────────────────────────────────────────────────
+  // ─── Scope helpers ─────────────────────────────────────────────────
 
-  static serializeScope(scope: Scopeable | null | undefined): ScopeKey {
+  /** Serialize a scope to its store/cache key. */
+  serializeScope(scope: Scopeable | null | undefined): ScopeKey {
     if (!scope) return GLOBAL_SCOPE
     const type =
       typeof scope.featureScope === 'function' ? scope.featureScope() : scope.constructor.name
@@ -77,103 +103,88 @@ export default class FlagManager {
   }
 
   /**
-   * Resolve a scope to its key, applying the `strictScopes` policy on
-   * the READ path. A null/undefined scope under strict mode raises
-   * `MissingScopeError` so a forgotten request-context lookup doesn't
-   * silently return the global value.
-   *
-   * The WRITE path keeps the loose semantics — `activate(feature)`
-   * with no scope still writes to the global. Callers that want
-   * explicit-global writes should prefer `activateForEveryone()` /
-   * `deactivateForEveryone()`.
+   * Resolve a scope on the READ path. If `strictScopes` is enabled and
+   * no scope was passed, throw — the silent-global-fallback bug is a
+   * real production hazard.
    */
-  private static resolveScopeStrict(
-    feature: string,
-    scope: Scopeable | null | undefined
-  ): ScopeKey {
-    if (!scope && FlagManager._config?.strictScopes) {
+  private resolveScopeStrict(feature: string, scope: Scopeable | null | undefined): ScopeKey {
+    if (!scope && this.config.strictScopes === true) {
       throw new MissingScopeError(feature)
     }
-    return FlagManager.serializeScope(scope)
+    return this.serializeScope(scope)
   }
 
-  // ── Core resolution ────────────────────────────────────────────────
+  // ─── Core resolution ───────────────────────────────────────────────
 
-  static async value(feature: string, scope?: Scopeable | null): Promise<unknown> {
-    const scopeKey = FlagManager.resolveScopeStrict(feature, scope)
-    const cacheKey = FlagManager.cacheKey(feature, scopeKey)
+  async value(feature: string, scope?: Scopeable | null): Promise<unknown> {
+    const scopeKey = this.resolveScopeStrict(feature, scope)
+    const cacheKey = this.cacheKey(feature, scopeKey)
 
-    // 1. Check in-memory cache
-    if (FlagManager._cache.has(cacheKey)) {
-      return FlagManager._cache.get(cacheKey)
+    if (this.cache.has(cacheKey)) {
+      return this.cache.get(cacheKey)
     }
 
-    // 2. Check store
-    const store = FlagManager.store()
-    const stored = await store.get(feature, scopeKey)
+    const stored = await this.store.get(feature, scopeKey)
     if (stored !== undefined) {
-      FlagManager._cache.set(cacheKey, stored)
+      this.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
+    const resolved = await this.resolveFeature(feature, scopeKey)
+    await this.store.set(feature, scopeKey, resolved)
+    this.cache.set(cacheKey, resolved)
+    await this.emit<FlagResolvedEvent>('flag:resolved', {
+      feature,
+      scope: scopeKey,
+      value: resolved,
+    })
+    return resolved
   }
 
-  static async active(feature: string, scope?: Scopeable | null): Promise<boolean> {
-    return Boolean(await FlagManager.value(feature, scope))
+  async active(feature: string, scope?: Scopeable | null): Promise<boolean> {
+    return Boolean(await this.value(feature, scope))
   }
 
-  static async inactive(feature: string, scope?: Scopeable | null): Promise<boolean> {
-    return !(await FlagManager.active(feature, scope))
+  async inactive(feature: string, scope?: Scopeable | null): Promise<boolean> {
+    return !(await this.active(feature, scope))
   }
 
-  static async when<TActive, TInactive>(
+  async when<A, I>(
     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()
+    onActive: (value: unknown) => A | Promise<A>,
+    onInactive: () => I | Promise<I>,
+    scope?: Scopeable | null,
+  ): Promise<A | I> {
+    const v = await this.value(feature, scope)
+    return v ? onActive(v) : onInactive()
   }
 
-  // ── Scoped API ─────────────────────────────────────────────────────
+  // ─── Scoped API ────────────────────────────────────────────────────
 
-  static for(scope: Scopeable): PendingScopedFeature {
-    return new PendingScopedFeature(scope)
+  for(scope: Scopeable): PendingScopedFeature {
+    return new PendingScopedFeature(this, scope)
   }
 
-  // ── Manual activation/deactivation ─────────────────────────────────
+  // ─── Manual activation ─────────────────────────────────────────────
 
   /**
    * Turn a flag on (or assign a rich value).
    *
-   * Pass `actor` to record who made the change — the value is included
-   * in the `flag:updated` event payload so an audit hook can wire it
-   * through to `@strav/audit`. See the package CLAUDE.md for the
-   * recommended one-liner pattern.
+   * Pass `actor` to attribute the change in the `flag:updated` event
+   * so an audit subscriber can record who flipped what.
    */
-  static async activate(
+  async activate(
     feature: string,
     value?: unknown,
     scope?: Scopeable | null,
-    actor?: FlagActor | null
+    actor?: FlagActor | null,
   ): Promise<void> {
-    const scopeKey = FlagManager.serializeScope(scope)
+    const scopeKey = this.serializeScope(scope)
     const resolved = value !== undefined ? value : true
-    const previous = await FlagManager.store().get(feature, scopeKey)
-    await FlagManager.store().set(feature, scopeKey, resolved)
-    FlagManager._cache.set(FlagManager.cacheKey(feature, scopeKey), resolved)
-    await Emitter.emit('flag:updated', {
+    const previous = await this.store.get(feature, scopeKey)
+    await this.store.set(feature, scopeKey, resolved)
+    this.cache.set(this.cacheKey(feature, scopeKey), resolved)
+    await this.emit<FlagUpdatedEvent>('flag:updated', {
       feature,
       scope: scopeKey,
       value: resolved,
@@ -182,21 +193,16 @@ export default class FlagManager {
     })
   }
 
-  /**
-   * Turn a flag off.
-   *
-   * Pass `actor` to record who made the change — see {@link activate}.
-   */
-  static async deactivate(
+  async deactivate(
     feature: string,
     scope?: Scopeable | null,
-    actor?: FlagActor | null
+    actor?: FlagActor | null,
   ): Promise<void> {
-    const scopeKey = FlagManager.serializeScope(scope)
-    const previous = await FlagManager.store().get(feature, scopeKey)
-    await FlagManager.store().set(feature, scopeKey, false)
-    FlagManager._cache.set(FlagManager.cacheKey(feature, scopeKey), false)
-    await Emitter.emit('flag:updated', {
+    const scopeKey = this.serializeScope(scope)
+    const previous = await this.store.get(feature, scopeKey)
+    await this.store.set(feature, scopeKey, false)
+    this.cache.set(this.cacheKey(feature, scopeKey), false)
+    await this.emit<FlagUpdatedEvent>('flag:updated', {
       feature,
       scope: scopeKey,
       value: false,
@@ -205,205 +211,132 @@ export default class FlagManager {
     })
   }
 
-  static async activateForEveryone(
-    feature: string,
-    value?: unknown,
-    actor?: FlagActor | null
-  ): Promise<void> {
-    return FlagManager.activate(feature, value, null, actor)
+  activateForEveryone(feature: string, value?: unknown, actor?: FlagActor | null): Promise<void> {
+    return this.activate(feature, value, null, actor)
   }
 
-  static async deactivateForEveryone(
-    feature: string,
-    actor?: FlagActor | null
-  ): Promise<void> {
-    return FlagManager.deactivate(feature, null, actor)
+  deactivateForEveryone(feature: string, actor?: FlagActor | null): Promise<void> {
+    return this.deactivate(feature, null, actor)
   }
 
-  // ── Batch operations ───────────────────────────────────────────────
+  // ─── Batch ─────────────────────────────────────────────────────────
 
-  static async values(features: string[], scope?: Scopeable | null): Promise<Map<string, unknown>> {
+  async values(features: string[], scope?: Scopeable | null): Promise<Map<string, unknown>> {
     const result = new Map<string, unknown>()
-    // Use the first feature name in the strict-scope error message — every
-    // batch call shares the same scope so the missing-scope diagnosis is
-    // identical regardless of which feature trips the check.
-    const scopeKey = FlagManager.resolveScopeStrict(features[0] ?? '<batch>', scope)
+    if (features.length === 0) return result
+
+    // strict-scope check uses the first feature name for the error
+    // message — every entry shares the same scope, the diagnosis is
+    // identical regardless of which one trips it.
+    const scopeKey = this.resolveScopeStrict(features[0] as string, 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))
+      const ck = this.cacheKey(f, scopeKey)
+      if (this.cache.has(ck)) {
+        result.set(f, this.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[] = []
-
+    const stored = await this.store.getMany(misses, scopeKey)
+    const unresolved: 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)
+        const v = stored.get(f)
+        result.set(f, v)
+        this.cache.set(this.cacheKey(f, scopeKey), v)
       } else {
-        stillMissing.push(f)
+        unresolved.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 })
+    for (const f of unresolved) {
+      const v = await this.resolveFeature(f, scopeKey)
+      await this.store.set(f, scopeKey, v)
+      this.cache.set(this.cacheKey(f, scopeKey), v)
+      result.set(f, v)
+      await this.emit<FlagResolvedEvent>('flag:resolved', { feature: f, scope: scopeKey, value: v })
     }
-
     return result
   }
 
-  /** Get all stored feature names. */
-  static async stored(): Promise<string[]> {
-    return FlagManager.store().featureNames()
+  /** Distinct names of features that have at least one stored entry. */
+  stored(): Promise<string[]> {
+    return this.store.featureNames()
   }
 
-  // ── Eager loading ──────────────────────────────────────────────────
-
-  static async load(features: string[], scopes: Scopeable[]): Promise<void> {
-    const store = FlagManager.store()
+  // ─── Eager load ────────────────────────────────────────────────────
 
+  /**
+   * Resolve `features × scopes` up-front and prime the cache. Useful
+   * at request start when subsequent code paths read several flags.
+   */
+  async load(features: string[], scopes: Scopeable[]): Promise<void> {
     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)
+      const scopeKey = this.serializeScope(scope)
+      const stored = await this.store.getMany(features, scopeKey)
+      for (const [f, v] of stored) {
+        this.cache.set(this.cacheKey(f, scopeKey), v)
       }
-
-      // 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)
+          const v = await this.resolveFeature(f, scopeKey)
+          await this.store.set(f, scopeKey, v)
+          this.cache.set(this.cacheKey(f, scopeKey), v)
         }
       }
     }
   }
 
-  // ── Cleanup ────────────────────────────────────────────────────────
-
-  static async forget(feature: string, scope?: Scopeable | null): Promise<void> {
-    const scopeKey = FlagManager.resolveScopeStrict(feature, scope)
-    await FlagManager.store().forget(feature, scopeKey)
-    FlagManager._cache.delete(FlagManager.cacheKey(feature, scopeKey))
-    await Emitter.emit('flag:deleted', { feature, scope: scopeKey })
-  }
+  // ─── Cleanup ───────────────────────────────────────────────────────
 
-  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: '*' })
+  async forget(feature: string, scope?: Scopeable | null): Promise<void> {
+    const scopeKey = this.resolveScopeStrict(feature, scope)
+    await this.store.forget(feature, scopeKey)
+    this.cache.delete(this.cacheKey(feature, scopeKey))
+    await this.emit<FlagDeletedEvent>('flag:deleted', { feature, scope: scopeKey })
   }
 
-  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.`)
+  async purge(feature: string): Promise<void> {
+    await this.store.purge(feature)
+    const prefix = `${feature}\0`
+    for (const key of this.cache.keys()) {
+      if (key.startsWith(prefix)) this.cache.delete(key)
     }
-
-    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()
+    await this.emit<FlagDeletedEvent>('flag:deleted', { feature, scope: '*' })
   }
 
-  // ── Table setup ────────────────────────────────────────────────────
-
-  static async ensureTables(): Promise<void> {
-    const store = FlagManager.store()
-    if (store instanceof DatabaseDriver) {
-      await store.ensureTable()
-    }
+  async purgeAll(): Promise<void> {
+    await this.store.purgeAll()
+    this.cache.clear()
+    await this.emit<FlagDeletedEvent>('flag:deleted', { feature: '*', scope: '*' })
   }
 
-  // ── 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
+  /** Drop the in-process cache only. The store is untouched. */
+  flushCache(): void {
+    this.cache.clear()
   }
 
-  // ── Private helpers ────────────────────────────────────────────────
+  // ─── Private ───────────────────────────────────────────────────────
 
-  private static cacheKey(feature: string, scope: ScopeKey): string {
+  private 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)
+  private async resolveFeature(feature: string, scope: ScopeKey): Promise<unknown> {
+    const fn = this.definitions.get(feature)
+    if (fn) return fn(scope)
+    const Cls = this.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().`
-        )
-    }
+  private async emit<T>(event: string, payload: T): Promise<void> {
+    if (!this.events) return
+    await this.events.emit(event, payload)
   }
 }