Browse documentation

@dads-framework/feature-flags

On this page

Feature flags defined in code, with a stored audience per flag: off, on for the tenants you select, or on for everyone. Every change is revision-checked, applied in batches that land together or not at all, and recorded in history. The application decides what a tenant is.

What Dad does for you

A flag lives in code, so it is reviewed, owned, and deleted like code. Only who sees it is stored, and nothing stored can invent a flag the code never defined.

Try it

Install the flag kit.

Shell
npm install @dads-framework/feature-flags @dads-framework/runtime

Save as pilot.mts and run node pilot.mts with Node.js 22.18 or newer. The script enables invoice export for one tenant in memory.

TypeScript
import {
  composeFeatureFlags,
  defineFeatureFlag,
} from "@dads-framework/feature-flags";
import {
  InMemoryFeatureFlagStore,
  FakeTenantDirectory,
} from "@dads-framework/feature-flags/testing";
import { SystemClock } from "@dads-framework/runtime/clock";

const bulkExport = defineFeatureFlag({
  slug: "billing.invoices.bulk-export",
  name: "Bulk invoice export",
  description: "Export every invoice in a period as one file.",
  owner: "billing team",
  defaultEnabled: false,
  affectedPages: ["/invoices"],
  affectedApiCapabilities: ["POST /invoices/exports"],
  cleanupTrigger: "Removed after two weeks on for everyone.",
  globalStabilityDays: 14,
});

const flags = composeFeatureFlags({
  definitions: [bulkExport],
  store: new InMemoryFeatureFlagStore(),
  tenants: new FakeTenantDirectory(),
  clock: new SystemClock(),
});

await flags.update.execute({
  actorId: "user-1",
  request: {
    changes: [
      {
        slug: bulkExport.slug,
        expectedRevision: 0,
        mode: "SELECTED_TENANTS",
        tenantIds: ["acme"],
      },
    ],
  },
});

console.log(
  await flags.evaluator.isActive({
    slug: bulkExport.slug,
    context: { kind: "tenant", tenantId: "acme" },
  }),
);
console.log(
  await flags.evaluator.isActive({
    slug: bulkExport.slug,
    context: { kind: "platform" },
  }),
);

The script prints true for Acme and false for the platform. The selected-tenant rollout leaves the platform audience off.

The generated starter defines the note-export flag in domains/notes/server/flags.ts and contributes it from domains/notes/server/plugin.ts. The service in assembly/services.ts evaluates the API’s declared flags.

Use it

  • defineFeatureFlag(definition) parses a definition where it is declared. A definition is off by default and names at least one affected page or API capability.
  • composeFeatureFlags({ definitions, publicSlugs?, store, tenants, clock, readPreview? }) returns management, history, update, effective, publicState, evaluator, and evaluatorReadingStatesOncePerRequest.
  • readPreview(context) optionally supplies an authorized request override for one defined flag. Effective state and both evaluators include the override. The public list, management views, rollout state, and history use stored audiences.
  • TenantDirectory is the application's port: findActiveTenants(ids) answers which ids are active tenants and what they are called.
  • FeatureFlagStore is the storage port. @dads-framework/feature-flags/postgres implements it; InMemoryFeatureFlagStore in /testing is the in-memory one. verifyFeatureFlagStoreConformance(createStore) in /testing is the suite both pass; run it against any store you write.
  • FeatureFlagContext is { kind: "platform" } or { kind: "tenant", tenantId }. The platform context counts flags that are on for everyone only.
  • @dads-framework/feature-flags/contract holds the Zod schemas, route paths and header names, with no server code, for a client to import.
  • @dads-framework/feature-flags/http serves the routes and the per-request evaluator; @dads-framework/client-feature-flags reads the state in a browser.

What it refuses to do

  • It never stores a definition. A stored row for a slug the code no longer defines is never evaluated and never listed.
  • It never applies part of a batch. One stale expectedRevision refuses the whole batch.
  • It never selects a tenant the TenantDirectory does not report as active.
  • It never shows a selected-tenants pilot to the platform context or to the public state.
  • It never decides who may manage flags. The HTTP binding asks the application's Authorization with the permission the application names.

Contract

Shape Fields
FeatureFlagState slug, audienceMode, rememberedTenants[], revision, globalEnabledAt, updatedAt, updatedBy
UpdateFeatureFlagsRequest changes[]: { slug, expectedRevision, mode, note? }, plus tenantIds when mode is SELECTED_TENANTS
FeatureFlagHistoryEntry batchId, slug, revision, previousState, nextState, note?, changedAt, changedBy
EffectiveFeatureState features (sorted slugs that are on), stateHash (SHA-256 of that list)
PublicFeatureState features (public-list slugs that are on for everyone)
Error code Kind When
FEATURE_FLAG_STATE_CHANGED conflict an expectedRevision is not the stored revision
FEATURE_FLAG_NOT_FOUND not-found a batch or history read names a slug the code never defined
FEATURE_FLAG_CHANGE_DUPLICATED validation one batch names the same slug twice
FEATURE_FLAG_TENANT_NOT_FOUND not-found a selected tenant is not active

composeFeatureFlags throws at startup when a slug is defined twice or a public slug is not defined.

Install as a plugin

createFeatureFlagsPlugin({ definitions, publicSlugs }) declares the flag definitions and offers featureFlagsService. The API host supplies the store, tenant directory, and clock through featureFlagDepsService. Import a route or storage plugin below when needed.

HTTP routes and previews

Serves @dads-framework/feature-flags through the HTTP kit: management routes guarded by a permission the application names, the caller's effective feature state, the public list, and the evaluator the kit runs once per request.

Try it

Install the flag kit and its HTTP binding.

Shell
npm install @dads-framework/feature-flags @dads-framework/http @dads-framework/access

Save as flag-routes.mts and run node flag-routes.mts with Node.js 22.18 or newer. The test harness runs requests in process and denies all permission checks by default.

TypeScript
import { composeFeatureFlags } from "@dads-framework/feature-flags";
import {
  FakeTenantDirectory,
  featureFlagDefinitionFactory,
  FixedClock,
  InMemoryFeatureFlagStore,
} from "@dads-framework/feature-flags/testing";
import { createFeatureFlagRoutes } from "@dads-framework/feature-flags/http";
import { fromFixed } from "@dads-framework/http";
import {
  buildTestApp,
  TEST_SUBJECT_HEADER,
} from "@dads-framework/http/testing";

const exportFlag = featureFlagDefinitionFactory({ slug: "orders.export" });
const flags = composeFeatureFlags({
  definitions: [exportFlag],
  publicSlugs: [exportFlag.slug],
  store: new InMemoryFeatureFlagStore(),
  tenants: new FakeTenantDirectory(),
  clock: new FixedClock(new Date("2026-01-01T00:00:00Z")),
});
await flags.update.execute({
  actorId: "example-operator",
  request: {
    changes: [{ slug: exportFlag.slug, expectedRevision: 0, mode: "EVERYONE" }],
  },
});

const app = await buildTestApp({
  routes: createFeatureFlagRoutes({
    featureFlags: flags,
    manage: {
      kind: "permission",
      resourceType: "app/settings",
      permission: "manage_feature_flags",
      resourceId: fromFixed("main"),
    },
  }),
});
try {
  const publicState = await app.inject({
    method: "GET",
    url: "/feature-state/public",
  });
  console.log(publicState.statusCode, publicState.body);

  const management = await app.inject({
    method: "GET",
    url: "/feature-flags",
    headers: { [TEST_SUBJECT_HEADER]: "example-user" },
  });
  console.log(management.statusCode);
} finally {
  await app.close();
}

The anonymous public request returns 200 with orders.export in data.features. The signed-in caller has no management permission, so the second request returns 404.

The repo-only src/http/feature-flag-routes.test.ts mounts these routes and checks public reads and management access. The generated starter wires the package’s request evaluator in assembly/feature-previews.ts.

Use it

  • createFeatureFlagRoutes({ featureFlags, manage, tag? }) returns the route group below.
  • FeatureFlagRequestEvaluator(effective, resolveContext) is the HTTP kit's FeatureStateRequestEvaluator. resolveContext is where the application says which tenant a request acts in. Resolve it from what the session proves, not from a header alone, when tenants must not read each other's pilots.

Scoped previews

Set readPreview: readFeatureFlagPreview when composing the flags. Set featureState.preview.resolver to createFeatureFlagPreviewResolver and choose the request and dropped-response headers in featureState.preview. Use the composed flags’ definitions in the preview resolver and share resolveContext with FeatureFlagRequestEvaluator.

The host supplies findPreview(previewId) to look up a typed record with owner, context, feature, active, allowsWrites and expiresAt. The host issues and revokes those records separately from rollout settings. Its canPreview({ subject, context, feature }) verifies current preview permission, including the caller's relationship to the selected tenant. A context header is only a hint for that check. The resolver also checks the record's owner, context, expiry and flag definition before applying it. Requests with a valid preview receive a private, non-cacheable response.

What it refuses to do

  • It never answers a management route to a caller without the manage permission. The HTTP kit asks the application's Authorization first and answers a refusal with 404, the same as an unknown route.
  • It never decides the tenant itself. A request the resolver answers null for carries no feature state.

Contract

Route Access Answers
GET /feature-flags manage FeatureFlagManagementList
GET /feature-flags/:slug/history manage paged FeatureFlagHistoryEntry
POST /feature-flags manage { states: FeatureFlagState[] }
GET /feature-state signed-in session EffectiveFeatureState; the platform answer when no context resolves
GET /feature-state/public public PublicFeatureState

Errors are the core package's, mapped by the HTTP kit: conflict 409, not-found 404, validation 400.

createFeatureFlagRoutesPlugin() serves the configured public flag list. Supply { manage } to select the management routes and the signed-in effective state route as well. Add the plugin only to the API route list that should receive those operations. The selected API needs featureFlagsService.

PostgreSQL storage

The Postgres store for @dads-framework/feature-flags: one node-pg-migrate migration, the Drizzle tables it creates, and DrizzleFeatureFlagStore, which writes a batch of flag changes and their history in one transaction.

Try it

Use a fresh Postgres database for the example and export its connection URL as DATABASE_URL. Install the store and the migration runner.

Shell
npm install @dads-framework/feature-flags @dads-framework/postgres drizzle-orm node-pg-migrate
mkdir -p migrations

Save this as migrations/1767225600000_feature_flags.mjs.

JavaScript
export {
  installFeatureFlagSchemaV1 as up,
  removeFeatureFlagSchemaV1 as down,
} from "@dads-framework/feature-flags/postgres";

Apply the migration.

Shell
npx node-pg-migrate up

Save as read-flag-store.mts and run node read-flag-store.mts with Node.js 22.18 or newer.

TypeScript
import {
  DrizzleFeatureFlagStore,
  featureFlagStates,
} from "@dads-framework/feature-flags/postgres";
import { createPostgresConnection } from "@dads-framework/postgres";

const connectionString = process.env.DATABASE_URL;
if (!connectionString)
  throw new Error("Set DATABASE_URL before running this script.");

const connection = createPostgresConnection(
  { connectionString, schema: { featureFlagStates } },
  console,
);
try {
  const store = new DrizzleFeatureFlagStore(connection.drizzle);
  console.log(await store.listStates(["orders.export"]));
} finally {
  await connection.close();
}

The script prints []. The migration creates the tables, and the store finds no persisted audience for orders.export in the fresh database.

The generated starter creates the store in assembly/services.ts using its shared Drizzle connection. The repo’s src/postgres/drizzle-feature-flag-store.integration.test.ts exercises that store against PostgreSQL.

Use it

  • src/postgres/migrations/20261119180000_feature_flags.migration.ts creates feature_flag_states, feature_flag_tenant_targets and feature_flag_change_events. Run it with your node-pg-migrate setup. installFeatureFlagSchemaV1(pgm) and removeFeatureFlagSchemaV1(pgm) are the same up and down, for a migration of your own to call. The shipped migration retains the original filename and checksum from @dads-framework/feature-flags-postgres.
  • DrizzleFeatureFlagStore(db) implements FeatureFlagStore.
  • featureFlagStates, featureFlagTenantTargets and featureFlagChangeEvents are the Drizzle tables, for reads of your own.

What it refuses to do

  • It never writes part of a batch. A stale revision, or a first write that loses the race to another, rolls back every state, tenant and history row in the batch and answers revision-conflict.
  • It never updates or deletes a history row. Code only inserts there.
  • It never stores EVERYONE without global_enabled_at, or any other mode with it: a CHECK constraint holds that.

Contract

Table Key columns
feature_flag_states slug (unique), audience_mode, global_enabled_at, updated_by, row_version
feature_flag_tenant_targets feature_flag_state_id, tenant_id (unique together), tenant_name, enabled_at
feature_flag_change_events batch_id, slug, revision, previous_state, next_state, note, changed_by

row_version is the wire's revision. Tenant and actor ids are text: the application decides their format. applyBatch answers "applied" or "revision-conflict"; any other database error is thrown.

Select featureFlagsPostgresSchema when the application uses this store. The plugin contributes the original TypeScript migration to api.migrationSources(root) and opens no connection. Pass a DrizzleFeatureFlagStore through the host-supplied flag dependencies.