@strav/flag 0.4.31 → 1.0.0-alpha.42

package/src/drivers/postgres/postgres_flag_store.ts

@@ -0,0 +1,132 @@
+/**
+ * `PostgresFlagStore` — cross-process feature flag store backed by a
+ * single `strav_flags` table (key: `(feature, scope)`). Values live in
+ * a `jsonb` column so booleans, numbers, strings, and rich variant
+ * payloads all round-trip.
+ *
+ * Bun's SQL driver hydrates jsonb scalars natively but returns
+ * jsonb objects/arrays as their JSON-encoded text — the read path
+ * `JSON.parse`s strings opportunistically and falls back to the raw
+ * string when parsing fails (so a string-scalar stored as `"hello"`
+ * round-trips correctly without us claiming `hello` is an object).
+ * Same pattern as `@strav/cache`'s Postgres driver.
+ *
+ * The runtime peer-dep on `@strav/database` is *optional* — apps
+ * using `MemoryFlagStore` shouldn't pull `@strav/database` into their
+ * bundle. The minimum surface is declared inline as
+ * `PostgresFlagDatabase`.
+ */
+
+import type { FeatureStore } from '../../feature_store.ts'
+import type { ScopeKey, StoredFeature } from '../../types.ts'
+
+export interface PostgresFlagDatabase {
+  query<T = Record<string, unknown>>(sql: string, params?: readonly unknown[]): Promise<T[]>
+  execute(sql: string, params?: readonly unknown[]): Promise<number>
+}
+
+export interface PostgresFlagStoreOptions {
+  db: PostgresFlagDatabase
+}
+
+const TABLE = '"strav_flags"'
+
+export class PostgresFlagStore implements FeatureStore {
+  readonly name = 'postgres'
+  private readonly db: PostgresFlagDatabase
+
+  constructor(options: PostgresFlagStoreOptions) {
+    this.db = options.db
+  }
+
+  async get(feature: string, scope: ScopeKey): Promise<unknown | undefined> {
+    const rows = await this.db.query<{ value: unknown }>(
+      `SELECT "value" FROM ${TABLE} WHERE "feature" = $1 AND "scope" = $2 LIMIT 1`,
+      [feature, scope],
+    )
+    if (rows.length === 0) return undefined
+    return hydrate(rows[0]?.value)
+  }
+
+  async getMany(features: string[], scope: ScopeKey): Promise<Map<string, unknown>> {
+    const out = new Map<string, unknown>()
+    if (features.length === 0) return out
+    const placeholders = features.map((_, i) => `$${i + 2}`).join(', ')
+    const rows = await this.db.query<{ feature: string; value: unknown }>(
+      `SELECT "feature", "value" FROM ${TABLE}
+       WHERE "scope" = $1 AND "feature" IN (${placeholders})`,
+      [scope, ...features],
+    )
+    for (const r of rows) out.set(r.feature, hydrate(r.value))
+    return out
+  }
+
+  async set(feature: string, scope: ScopeKey, value: unknown): Promise<void> {
+    const json = JSON.stringify(value)
+    await this.db.execute(
+      `INSERT INTO ${TABLE} ("feature", "scope", "value", "created_at", "updated_at")
+       VALUES ($1, $2, $3::jsonb, now(), now())
+       ON CONFLICT ("feature", "scope")
+       DO UPDATE SET "value" = $3::jsonb, "updated_at" = now()`,
+      [feature, scope, json],
+    )
+  }
+
+  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> {
+    await this.db.execute(`DELETE FROM ${TABLE} WHERE "feature" = $1 AND "scope" = $2`, [
+      feature,
+      scope,
+    ])
+  }
+
+  async purge(feature: string): Promise<void> {
+    await this.db.execute(`DELETE FROM ${TABLE} WHERE "feature" = $1`, [feature])
+  }
+
+  async purgeAll(): Promise<void> {
+    await this.db.execute(`DELETE FROM ${TABLE}`)
+  }
+
+  async featureNames(): Promise<string[]> {
+    const rows = await this.db.query<{ feature: string }>(
+      `SELECT DISTINCT "feature" FROM ${TABLE} ORDER BY "feature"`,
+    )
+    return rows.map((r) => r.feature)
+  }
+
+  async allFor(feature: string): Promise<StoredFeature[]> {
+    const rows = await this.db.query<{
+      feature: string
+      scope: string
+      value: unknown
+      created_at: Date
+      updated_at: Date
+    }>(
+      `SELECT "feature", "scope", "value", "created_at", "updated_at"
+       FROM ${TABLE} WHERE "feature" = $1 ORDER BY "scope"`,
+      [feature],
+    )
+    return rows.map((r) => ({
+      feature: r.feature,
+      scope: r.scope,
+      value: hydrate(r.value),
+      createdAt: r.created_at,
+      updatedAt: r.updated_at,
+    }))
+  }
+}
+
+function hydrate(raw: unknown): unknown {
+  if (typeof raw !== 'string') return raw
+  try {
+    return JSON.parse(raw)
+  } catch {
+    return raw
+  }
+}

package/src/feature_store.ts

@@ -1,33 +1,40 @@
+/**
+ * `FeatureStore` — contract every flag storage driver implements.
+ *
+ * The store is purely a persistence layer: it doesn't know about
+ * resolvers, the in-process cache, or scope semantics. The
+ * `FlagManager` composes the higher-level behavior on top.
+ */
+
 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. */
+  /** Retrieve a stored value. `undefined` if the pair has never been resolved. */
   get(feature: string, scope: ScopeKey): Promise<unknown | undefined>
 
-  /** Retrieve stored values for multiple features for a single scope. */
+  /** Batch-read multiple features for a single scope. */
   getMany(features: string[], scope: ScopeKey): Promise<Map<string, unknown>>
 
-  /** Store a resolved value (upsert). */
+  /** Upsert a value for `(feature, scope)`. */
   set(feature: string, scope: ScopeKey, value: unknown): Promise<void>
 
-  /** Store multiple resolved values at once. */
+  /** Batch upsert. Drivers SHOULD do this in a single transaction. */
   setMany(entries: Array<{ feature: string; scope: ScopeKey; value: unknown }>): Promise<void>
 
-  /** Remove the stored value for a feature+scope pair. */
+  /** Drop a single `(feature, scope)` entry. */
   forget(feature: string, scope: ScopeKey): Promise<void>
 
-  /** Remove ALL stored values for a feature (all scopes). */
+  /** Drop every entry for `feature` across all scopes. */
   purge(feature: string): Promise<void>
 
-  /** Remove all stored values for all features. */
+  /** Drop every entry for every feature. */
   purgeAll(): Promise<void>
 
-  /** List all distinct feature names that have stored values. */
+  /** Distinct names of features that have at least one stored entry. */
   featureNames(): Promise<string[]>
 
-  /** List all stored records for a feature. */
+  /** All stored records for `feature` (every scope it's been resolved against). */
   allFor(feature: string): Promise<StoredFeature[]>
 }

package/src/flag_error.ts

@@ -0,0 +1,29 @@
+import { StravError } from '@strav/kernel'
+
+export class FlagError extends StravError {
+  constructor(message: string) {
+    super(message, { code: 'flag-error', status: 500 })
+  }
+}
+
+export class FeatureNotDefinedError extends FlagError {
+  constructor(feature: string) {
+    super(`Feature "${feature}" is not defined. Register it with flagManager.define().`)
+  }
+}
+
+/**
+ * Thrown when `flag.strictScopes` is enabled and a flag is evaluated
+ * without a scope. Catches the common bug where a per-user flag
+ * silently resolves the global value because the caller forgot to
+ * pass `ctx.auth.user`.
+ */
+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. flags.for(user).value('${feature}')) or call ` +
+        `flags.activateForEveryone('${feature}') for genuinely global flags.`,
+    )
+  }
+}