Configuration

To move your feature flags out of component logic and into a central store, you use createFeatures. This function takes your feature definitions, validates them, and returns the store every other call reads. A rule in a definition replaces the role === 'bookseller' check each component would otherwise repeat.

Declarative Feature Definitions

@evanion/feature uses a declarative configuration so you can define the intent (is it enabled?) and the rules (when is it active?) in a single place. createFeatures validates the dependency graph, deep-clones and freezes your definitions, and returns the store.

import { createFeatures } from '@evanion/feature';
 
const definitions = [{ key: 'gift-cards', enabled: true }];
const features = createFeatures(definitions);
 
features.isEnabled('gift-cards'); // -> true
Object.isFrozen(definitions[0]); // -> false
Object.isFrozen(features.definition('gift-cards')); // -> true

The store holds a frozen copy of each definition. Your own array stays editable, and an assignment to the copy definition() returns throws a TypeError, so the store never diverges from what it resolves.

The Configuration Schema

A rule carries an optional id, a when list of conditions, an optional rollout, and an optional variant it pins. A condition names a context field, an op and a value.

Resolution Precedence

When you call resolve(), @evanion/feature follows a strict hierarchy to determine if a feature is active.

1. The Kill Switch: If enabled === false, the feature is off. No rules are evaluated.
2. The Dependency Chain: If any feature in dependsOn resolves to false, this feature is off. No rules are evaluated.
3. The Default State: If enabled === true and there are no rules, the feature is on.
4. The Rules: If rules exist, they are OR-ed. If any rule matches, the feature is on. Inside a rule, conditions are AND-ed.

enabled does not depend on rule order. rule names the first rule that matched, and that rule’s variant pin is the one applied, so moving a rule up can change which rule a decision names.

The kill switch works in one direction only. Setting enabled: true on a feature whose rules do not match changes the stored intent, and the feature still resolves off.

Dependency Cascades

@evanion/feature cascades dependencies transitively and one way. With demo night booking behind express pickup, and express pickup behind the new checkout, express pickup being off takes demo night booking off and leaves the new checkout on.

import { createFeatures } from '@evanion/feature';
 
const features = createFeatures([
  { key: 'demo-night-booking', enabled: true, dependsOn: ['express-pickup'] },
  { key: 'express-pickup', enabled: false, dependsOn: ['new-checkout'] },
  { key: 'new-checkout', enabled: true },
]);
 
features.isEnabled('demo-night-booking'); // -> false
features.isEnabled('new-checkout'); // -> true

createFeatures evaluates in dependency order, so the cascade works at any depth and you can declare your features in any order.

Configuration Errors

createFeatures validates the dependency graph at construction. It throws a subclass of FeatureConfigError if it detects:

• Cycles: FeatureCycleError, e.g., A depends on B, and B depends on A. Its path property holds the cycle’s keys, from the first key back to itself.
• Unknown Dependencies: UnknownDependencyError, when a feature depends on a key that isn’t configured.
• Duplicates: DuplicateFeatureError, when two features share the same key.

import { createFeatures } from '@evanion/feature';
import type { FeatureDefinition } from '@evanion/feature';
 
const attempt = (definitions: FeatureDefinition[]) => {
  try {
    createFeatures(definitions);
    return 'built';
  } catch (error) {
    return String(error);
  }
};
 
const cycle: FeatureDefinition[] = [
  { key: 'a', enabled: true, dependsOn: ['c'] },
  { key: 'b', enabled: true, dependsOn: ['a'] },
  { key: 'c', enabled: true, dependsOn: ['b'] },
];
const duplicate: FeatureDefinition[] = [
  { key: 'a', enabled: true },
  { key: 'a', enabled: true },
];
 
attempt(cycle); // -> 'FeatureCycleError: feature dependency cycle: a -> c -> b -> a'
attempt([{ key: 'a', enabled: true, dependsOn: ['b'] }]); // -> 'UnknownDependencyError: feature "a" depends on "b", which is not configured'
attempt(duplicate); // -> 'DuplicateFeatureError: duplicate feature key "a"'

Variants are checked at the same point: DuplicateVariantError for two variants sharing a name, and UnknownVariantError for a rule pinning a variant its feature does not declare. Once createFeatures returns, resolve, plan and toggle never throw.

Defining Rules and Conditions

To activate features based on the user’s context, you use @evanion/feature rules. In the example below, a bookseller matches the first rule, and every other customer is subject to the second rule’s 10% rollout:

import { createFeatures } from '@evanion/feature';
 
const features = createFeatures([
  {
    key: 'beta-banner',
    enabled: true,
    rules: [
      {
        id: 'internal',
        when: [{ field: 'roles', op: 'contains', value: 'bookseller' }],
      },
      { id: 'ramp', rollout: { percent: 10 } },
    ],
  },
]);
 
features.isEnabled('beta-banner', { roles: ['bookseller'] }); // -> true
const customer = (targetingKey: string) =>
  features.isEnabled('beta-banner', { roles: ['customer'], targetingKey });
 
customer('cust-0042'); // -> false
customer('cust-0007'); // -> true

A rule that declares no id is named by a hash of what it matches on, so its name survives a rule being inserted above it. A decision names the rule in rule, and in its breakdown when no rule matched. The hash leaves out rollout.percent, so two rollout rules on one feature that differ only in their percentage share a name. Give a rule you expect to read in a log an explicit id.

Condition Operators

A day-of-week condition has no default zone: it names an IANA zone, because UTC day-of-week is wrong for a shop open in Stockholm.

Missing Context Fields

In @evanion/feature, a condition over a field the context does not carry never holds, and that includes ne and not-in. Treating ne on an absent field as true would switch features on for exactly the contexts that carry the least information.

import { createFeatures } from '@evanion/feature';
 
const preview = createFeatures([
  {
    key: 'new-checkout',
    enabled: true,
    rules: [
      {
        id: 'not-customers',
        when: [{ field: 'role', op: 'ne', value: 'customer' }],
      },
    ],
  },
]);
 
preview.isEnabled('new-checkout', { role: 'bookseller' }); // -> true
preview.isEnabled('new-checkout', {}); // -> false

Time Windows

To read the same on every host, a date-time string must include an offset (e.g., +09:00, +0900 or Z). A date with no time is read as UTC midnight. createFeatures rejects a date-time without an offset, and a date the calendar does not have, at construction.

import { createFeatures } from '@evanion/feature';
 
const opening = (value: string) => {
  try {
    createFeatures([
      {
        key: 'new-checkout',
        enabled: true,
        rules: [{ id: 'launch', when: [{ field: 'now', op: 'after', value }] }],
      },
    ]);
    return 'built';
  } catch (error) {
    return (error as Error).name;
  }
};
 
opening('2026-01-01T09:00:00+09:00'); // -> 'built'
opening('2026-01-01T09:00:00+0900'); // -> 'built'
opening('2026-01-01'); // -> 'built'
opening('2026-01-01T00:00:00'); // -> 'FeatureConfigError'
opening('2026-04-31'); // -> 'FeatureConfigError'

A window’s value can also be epoch milliseconds or a Date. createFeatures refuses NaN and a number outside the range a Date holds, and it takes a Date as the instant it holds, so new Date('2026-01-01T00:00:00') carries the zone of the host that built it.

Type-Safe Keys and Variants

You can maintain type safety for your @evanion/feature configuration depending on how your data is stored. If you define your configuration as an array literal, TypeScript infers the keys and variant names automatically.

If your configuration comes from a JSON file or variable, you can provide a schema interface:

import { createFeatures } from '@evanion/feature';
import type { FeatureDefinition } from '@evanion/feature';
 
interface Flags {
  'new-checkout': never;
  'express-pickup': { variant: 'control' | 'blue'; value: never };
}
 
// Typed as definitions, so the compiler has no literals to read.
const config: FeatureDefinition<keyof Flags>[] = [
  { key: 'new-checkout', enabled: true },
  {
    key: 'express-pickup',
    enabled: true,
    dependsOn: ['new-checkout'],
    variants: [
      { name: 'control', weight: 50 },
      { name: 'blue', weight: 50 },
    ],
  },
];
 
const features = createFeatures<Flags>(config);
 
features.variantOf('express-pickup', { targetingKey: 'cust-0042' }); // -> 'blue'
// @ts-expect-error -- 'express-delivery' is not a key of Flags
features.isEnabled('express-delivery'); // -> false

This ensures that calling features.isEnabled('express-delivery') is a compile error, and features.variantOf('express-pickup') returns 'control' | 'blue' | undefined. createFeatures<Flags>(config) also checks every definition’s key against keyof Flags.

Decisions resolves this store and reads what each decision says about the rule that decided it.