@strav/flag 0.4.30 → 1.0.0-alpha.42

package/src/drivers/database_driver.ts

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

@@ -1,25 +0,0 @@
-import { StravError } from '@strav/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().`)
-  }
-}
-
-/**
- * Thrown when `flag.strictScopes` is enabled and a flag operation is
- * called without a scope (or with a null/undefined one). Catches the
- * common bug where middleware forgets to pass `ctx.get('user')` and
- * the lookup silently evaluates the global flag.
- */
-export class MissingScopeError extends FlagError {
-  constructor(feature: string) {
-    super(
-      `Feature "${feature}" was evaluated without a scope, but flag.strictScopes is enabled. ` +
-        `Pass an explicit scope (e.g. flag.for(user).value('${feature}')) or call ` +
-        `flag.activateForEveryone('${feature}') for genuinely global flags.`
-    )
-  }
-}

package/src/helpers.ts

@@ -1,109 +0,0 @@
-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 '@strav/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/middleware/ensure_feature.ts

@@ -1,36 +0,0 @@
-import type { Middleware } from '@strav/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/stubs/config/flag.ts

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

package/tsconfig.json

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