Flag

Installation

bun add @strav/flag
bun strav install flag

Setup

1. Register FlagManager

Using a service provider (recommended)

import { FlagProvider } from '@strav/flag'

app.use(new FlagProvider())

To skip auto-creation (e.g. when using migrations):

app.use(new FlagProvider({ ensureTables: false }))

Manual setup

import FlagManager from '@strav/flag'

app.singleton(FlagManager)
app.resolve(FlagManager)
await FlagManager.ensureTables()

2. Configure drivers

import { env } from '@strav/kernel'

export default {
  default: env('FLAG_DRIVER', 'database'),

  drivers: {
    database: {
      driver: 'database',
    },

    array: {
      driver: 'array',
    },
  },
}

Defining features

Features must be defined before they can be checked. Define them during app bootstrap, after the provider boots.

Closure-based

import { flag } from '@strav/flag'

// Boolean flag
flag.define('new-checkout', true)

// Dynamic — receives the serialized scope key (e.g. "User:42")
flag.define('beta-ui', (scope) => {
  if (scope === '__global__') return false
  const id = parseInt(scope.split(':')[1])
  return id % 10 === 0  // 10% rollout
})

// Rich value for A/B testing
flag.define('checkout-variant', (scope) => {
  const id = parseInt(scope.split(':')[1] ?? '0')
  return id % 2 === 0 ? 'variant-a' : 'variant-b'
})

Class-based

import type { FeatureClass } from '@strav/flag'

class NewBillingExperience implements FeatureClass {
  static readonly key = 'new-billing'

  resolve(scope: string) {
    return scope !== '__global__'
  }
}

flag.defineClass(NewBillingExperience)

Checking features

import { flag } from '@strav/flag'

if (await flag.active('new-checkout')) {
  // feature is on
}

if (await flag.inactive('new-checkout')) {
  // feature is off
}

// Rich value
const variant = await flag.value('checkout-variant') as string

Conditional execution

const html = await flag.when(
  'new-checkout',
  (value) => renderNewCheckout(value),
  () => renderOldCheckout(),
)

Batch check

const values = await flag.values(['new-checkout', 'beta-ui', 'checkout-variant'])
// Map { 'new-checkout' => true, 'beta-ui' => false, 'checkout-variant' => 'variant-a' }

Scoping

const user = ctx.get<User>('user')

await flag.for(user).active('beta-ui')
await flag.for(user).value('checkout-variant')
await flag.for(user).values(['feat-a', 'feat-b'])

class Workspace {
  id = 5
  featureScope() { return 'Workspace' }
}
// Serializes to "Workspace:5"

Global scope

Manual activation

Override the resolver and store a specific value:

// Activate for the global scope
await flag.activate('maintenance-mode')

// Activate for a specific user
await flag.for(user).activate('beta-ui')

// Activate with a rich value
await flag.activate('checkout-variant', 'variant-c')

// Deactivate
await flag.deactivate('maintenance-mode')
await flag.for(user).deactivate('beta-ui')

Activate/deactivate for everyone

Shorthand for the global scope:

await flag.activateForEveryone('maintenance-mode')
await flag.deactivateForEveryone('maintenance-mode')

// With a rich value
await flag.activateForEveryone('checkout-variant', 'variant-b')

Resolution flow

1. In-memory cache — return immediately if cached
2. Store lookup — check the database for a persisted value
3. Resolver — call the closure/class resolve() method
4. Persist — store the resolved value in the database
5. Cache — cache in memory for the rest of the request

Eager loading

When rendering a list where you check features per-item, eager-load to avoid N+1 queries:

const users = await User.all()

await flag.load(['beta-ui', 'checkout-variant'], users)

for (const user of users) {
  // These are now cached — no additional DB queries
  if (await flag.for(user).active('beta-ui')) {
    // ...
  }
}

Cleanup

// Remove stored value for the current scope — forces re-resolution on next check
await flag.forget('beta-ui')
await flag.for(user).forget('beta-ui')

// Remove all stored values for a feature (all scopes)
await flag.purge('beta-ui')

// Remove everything
await flag.purgeAll()

Cache flushing

The in-memory cache lives for the duration of the process. Flush it to force a re-read from the database:

flag.flushCache()

Middleware

import { ensureFeature } from '@strav/flag'

router.group({ middleware: [auth(), ensureFeature('beta-ui')] }, (r) => {
  r.get('/beta/dashboard', betaDashboard)
})

import { compose } from '@strav/http'

r.get('/team/:id/analytics', compose(
  [ensureFeature('team-analytics', (ctx) => ctx.get('team'))],
  analyticsHandler,
))

Events

import Emitter from '@strav/kernel'

Emitter.on('flag:resolved', ({ feature, scope, value }) => {
  console.log(`Feature "${feature}" resolved to ${value} for ${scope}`)
})

Custom driver

import { flag } from '@strav/flag'
import type { FeatureStore } from '@strav/flag'

flag.extend('redis', (config) => {
  return new RedisFeatureStore(config)
})

Then set it as the driver in your config:

export default {
  default: 'redis',
  drivers: {
    redis: {
      driver: 'redis',
      url: env('REDIS_URL', 'redis://localhost:6379'),
    },
  },
}

CLI commands

The flag package provides three CLI commands (auto-discovered by the framework):

flag:setup

bun strav flag:setup

flag:list

List all stored feature flags with their scopes and values:

bun strav flag:list

flag:purge

Purge stored values for a specific feature or all features:

bun strav flag:purge beta-ui
bun strav flag:purge --all

Testing

# .env.test
FLAG_DRIVER=array

import { beforeEach } from 'bun:test'
import FlagManager from '@strav/flag'

beforeEach(() => {
  FlagManager.reset()
})

Controller example

import { flag } from '@strav/flag'

export default class CheckoutController {
  async show(ctx: Context) {
    const user = ctx.get<User>('user')

    const variant = await flag.for(user).value('checkout-variant') as string

    return await flag.for(user).when(
      'new-checkout',
      () => ctx.json({ variant, layout: 'new' }),
      () => ctx.json({ layout: 'classic' }),
    )
  }

  async toggleBeta(ctx: Context) {
    const user = ctx.get<User>('user')
    const { enabled } = await ctx.body<{ enabled: boolean }>()

    if (enabled) {
      await flag.for(user).activate('beta-ui')
    } else {
      await flag.for(user).deactivate('beta-ui')
    }

    return ctx.json({ ok: true })
  }
}