Decisions

resolve() answers every feature for one context, and each answer is a decision that says why the feature is on or off. toggle() is the one call that changes what the next decision reads.

Resolving Features

To check if a feature is active, you use the resolution methods provided by @evanion/feature. Depending on whether you need a single answer or a full audit, you have two primary ways to check a feature’s state:

1. features.isEnabled(key, context): Returns a simple boolean. It returns false for a key the store was not built with.
2. features.resolve(context): Returns a complete record of every feature in the store and its current decision.

Both are pure functions of the configuration and the context, and both write nothing. context is optional, and a context with no now field reads the clock at the call.

Because isEnabled() evaluates the whole dependency graph on every call, a request that reads several flags should call resolve() once and keep the record.

Example: Resolving a Request

To see how this works in practice, consider a store containing the new checkout and express pickup from Getting Started, utilizing the after-launch rule and its 25% rollout:

const decisions = features.resolve({ targetingKey: 'cust-0101', now });
 
decisions['new-checkout']; // -> { key: 'new-checkout', enabled: true, reason: 'rule-match', rule: 'after-launch' }
decisions['express-pickup']; // -> { key: 'express-pickup', enabled: true, reason: 'default-on' }

Anatomy of a Decision

When you use resolve(), @evanion/feature returns a Decision object that provides a detailed audit trail for every feature. While enabled is the only field your application needs, the other fields are designed for operators.

Every field except enabled is output only. Nothing in the library reads them back to decide anything.

Understanding the Reason

To determine exactly which part of the logic decided the outcome, you inspect the reason field:

Reading the Dependency Cascade

When a parent feature is disabled, @evanion/feature cascades that state to all dependants. In the example below, the new checkout is turned off in the chain Getting Started toggles, and the decisions for both dependants report reason: 'dependency-off'.

features.toggle('new-checkout', false);
const decisions = features.resolve();
 
decisions['express-pickup']; // -> { key: 'express-pickup', enabled: false, reason: 'dependency-off', blockedBy: 'new-checkout', cause: { key: 'new-checkout', reason: 'explicitly-off' } }
decisions['demo-night-booking']; // -> { key: 'demo-night-booking', enabled: false, reason: 'dependency-off', blockedBy: 'express-pickup', cause: { key: 'new-checkout', reason: 'explicitly-off' } }

You can use this cascade to trace failures without manually walking the dependency graph:

• blockedBy identifies the immediate edge (e.g., demo night booking is blocked by express pickup).
• cause walks the chain to the root failure (e.g., demo night booking is ultimately off because the new checkout is explicitly-off).

An operator reading demo night booking’s cause finds the new checkout immediately.

Why a Rule Did Not Match

To debug why a feature is disabled despite being generally enabled, you can examine the no-rule-matched reason. When a feature resolves to false for this reason, the @evanion/feature decision includes a detailed breakdown of every rule and why it failed.

import { createFeatures } from '@evanion/feature';
 
const features = createFeatures([
  {
    key: 'new-checkout',
    enabled: true,
    rules: [
      { when: [{ field: 'role', op: 'eq', value: 'bookseller' }] },
      { id: 'a-share', rollout: { percent: 10 } },
    ],
  },
]);
 
const customer = { role: 'customer', targetingKey: 'cust-0042' };
 
features.resolve(customer)['new-checkout']; // -> { key: 'new-checkout', enabled: false, reason: 'no-rule-matched', rules: [{ rule: 'rule-d69c7f2b', matched: false, failed: { field: 'role', op: 'eq', value: 'bookseller' } }, { rule: 'a-share', matched: false, rollout: { percent: 10, by: 'targetingKey', member: false } }] }

If a condition failed, the failed object names the first condition that did not hold: its field, operator, and value. If a rollout left the customer out, the rollout object gives the percentage, the field it bucketed on, and member: false. Note that since the first rule above declares no id, its outcome carries the hash-derived name rule-d69c7f2b.

Managing State with toggle

To modify the stored intent of a feature in @evanion/feature, you use the toggle() call. This is the only way to change state; it sets the enabled property, applies the change at once, and returns a report of which dependants went off with it.

The store below demonstrates this using the same three-flag chain before any toggle is applied:

features.toggle('express-pickup', false); // -> { ok: true, key: 'express-pickup', enabled: false, willDisable: ['demo-night-booking'] }
features.toggle('express-pickup', true); // -> { ok: true, key: 'express-pickup', enabled: true, willDisable: [] }
// @ts-expect-error -- the store's keys are checked at compile time too
features.toggle('express-delivery', false); // -> { ok: false, key: 'express-delivery', error: 'unknown-feature' }

The willDisable property holds only the dependants that resolved on before the write and off after it. Both sides are evaluated against one context—provided as the optional third argument of toggle(key, enabled, context)—and with none, both read an empty context at the current time.

Because willDisable is empty when enabling, a UI can use this to report the full effect of a change: “Turning off Express Pickup also disabled Demo Night Booking.” A key the store was not built with returns ok: false and never throws.

Inspecting the Store

To audit the configuration of an @evanion/feature store, you can use these inspection properties:

• features.keys: Every configured key, in configuration order.
• features.config: The deeply frozen configuration array.
• features.definition(key): The specific definition for one feature, or undefined.
• features.dependants(key): Every feature that depends on the given key, transitively, in dependency order.

Using the same three-flag chain:

features.keys; // -> ['new-checkout', 'express-pickup', 'demo-night-booking']
features.dependants('new-checkout'); // -> ['express-pickup', 'demo-night-booking']
features.definition('express-pickup'); // -> { key: 'express-pickup', enabled: true, dependsOn: ['new-checkout'] }
Object.isFrozen(features.config); // -> true

To learn more about the 25% rollout carried by the new checkout’s after-launch rule, see Rollouts.