Cloud

Feature Flags

Deterministic runtime feature toggles with percentage rollout, tenant and user allow-lists, and scheduled activation windows.

4 min readUpdated DocumentationEdit this page
On this page10

Overview

The feature flag system provides runtime feature toggles with deterministic, identity-based rollout using FNV-1a hashing. The same identity always gets the same result across requests and server instances, with no random flipping.

Basic Usage

TypeScript
TS
1import { featureFlags } from '@axiljs/cloud'
2
3featureFlags.define({
4  name: 'new-checkout',
5  enabled: true,
6  rolloutPercentage: 25,
7})
8
9const enabled = featureFlags.isEnabled('new-checkout', {
10  userId: 'usr-42',
11})

define() creates or replaces a flag. rolloutPercentage defaults to 100 and must be an integer from 0 to 100; anything else throws a RangeError.

Deterministic Rollout

AxilJS hashes the flag name together with an identity to place each caller in a bucket from 0 to 99. The caller gets the flag when its bucket is below rolloutPercentage. The identity is userId, falling back to tenantId, then to 'anonymous'.

  • The same identity always gets the same answer for a given flag
  • No UI flickering between requests
  • Consistent behaviour across horizontally scaled instances
TypeScript
TS
1featureFlags.define({
2  name: 'beta-dashboard',
3  enabled: true,
4  rolloutPercentage: 50,
5})
6
7featureFlags.isEnabled('beta-dashboard', { userId: 'usr-100' }) // same result...
8featureFlags.isEnabled('beta-dashboard', { userId: 'usr-100' }) // ...every time

Tenant and User Allow-Lists

allowedTenants and allowedUsers are allow-lists. A caller that matches either list gets the flag regardless of rolloutPercentage. When a list is non-empty, callers that match neither list are rejected, even at 100% rollout.

TypeScript
TS
1featureFlags.define({
2  name: 'premium-reports',
3  enabled: true,
4  allowedTenants: ['acme-corp'],
5  allowedUsers: ['vip-user-1'],
6})
7
8featureFlags.isEnabled('premium-reports', { tenantId: 'acme-corp' })                   // true
9featureFlags.isEnabled('premium-reports', { tenantId: 'other', userId: 'vip-user-1' }) // true
10featureFlags.isEnabled('premium-reports', { tenantId: 'other' })                       // false

Warning

Empty allow-lists mean "no allow-list", not "nobody". allowedTenants: [] and allowedUsers: [] behave exactly like omitting the property: every tenant and user is evaluated against rolloutPercentage. To turn a flag off for everyone, set enabled: false.

TypeScript
TS
1// Wrong: this does NOT disable the flag; all tenants still get it
2featureFlags.define({ name: 'legacy-export', enabled: true, allowedTenants: [] })
3
4// Right: switch the flag off
5featureFlags.define({ name: 'legacy-export', enabled: false })

Scheduled Activation

Flags can be scheduled to activate and expire automatically. Outside the window isEnabled() returns false, including for allow-listed callers.

TypeScript
TS
1featureFlags.define({
2  name: 'holiday-promo',
3  enabled: true,
4  startAt: '2026-12-01T00:00:00Z',
5  endAt: '2026-12-31T23:59:59Z',
6})

Custom Manager Instance

featureFlags is a shared in-memory FeatureFlagManager. For isolated flag scopes or tests, create your own.

TypeScript
TS
1import { FeatureFlagManager } from '@axiljs/cloud'
2
3const myFlags = new FeatureFlagManager()
4myFlags.define({ name: 'experiment-1', enabled: true, rolloutPercentage: 10 })

API Reference

define(flag)

PropertyTypeDefaultDescription
namestring—Unique flag identifier
enabledboolean—Global on/off switch; false disables for everyone
descriptionstring—Optional human-readable note
rolloutPercentagenumber (integer 0–100)100Deterministic rollout bucket
allowedTenantsstring[]—Tenant allow-list; empty array = no allow-list
allowedUsers(string | number)[]—User allow-list; empty array = no allow-list
startAtstring (ISO 8601)—Flag is inactive before this time
endAtstring (ISO 8601)—Flag is inactive after this time

isEnabled(name, context?)

context is { tenantId?: string; userId?: string | number }. Returns boolean; unknown flags return false.

Evaluation order:

  1. Enabled: a missing flag or enabled: false returns false.
  2. Schedule: before startAt or after endAt returns false.
  3. Allow-lists: a match in a non-empty allowedTenants or allowedUsers returns true. If either list is non-empty and nothing matched, returns false.
  4. Rollout: below 100%, the identity bucket must be under rolloutPercentage.

get(name) / getAll() / remove(name)

get returns the FeatureFlag or undefined, getAll returns FeatureFlag[], and remove returns true if a flag was deleted.

Was this page helpful?

Help improve the documentation

AxilJS is open source and documentation improvements are welcome.

AxilJS DocumentationMIT License · Built by SyntaxilitY