Evaluation engine

The evaluation engine is a pure, deterministic, framework-agnostic module (@clubedge/evaluation-engine). It has zero dependencies on NestJS, Redis, or databases — it’s a pure function over flag configuration data and an evaluation context.

Evaluation pipeline

A flag is resolved in strict order. The first matching step determines the result:

Step	Check	Result if matched	Reason code
1	Is the flag archived?	`{ enabled: false }`	`flag_archived`
2	Is the flag disabled in this environment?	`{ enabled: false }`	`flag_disabled`
3	Does a targeting rule match (in priority order)?	`{ enabled: rule.value }`	`targeting_rule`
4	Does the percentage rollout bucket this user?	`{ enabled: true }` or `{ enabled: false }`	`rollout`
5	No rules, no rollout, flag is on	`{ enabled: true }`	`flag_enabled`

Key ordering details

Rules are evaluated in ascending priority order. Lower numbers are evaluated first. The first matching rule wins — remaining rules are not evaluated.
Rollout is only checked after all targeting rules have been evaluated and none matched.
Archived check is the first short-circuit — even an archived flag with matching rules returns false.
Disabled check is the second short-circuit — if isEnabled is false for the environment, no further evaluation occurs.

Evaluation reasons

Reason	Description
`flag_archived`	Flag has been archived (soft-deleted)
`flag_disabled`	Flag exists but is disabled in the target environment
`targeting_rule`	A targeting rule matched the evaluation context
`rollout`	A percentage rollout bucketed the subject in or out
`flag_enabled`	Flag is enabled with no targeting rules and no rollout

Deterministic rollout

Rollouts use FNV-1a hashing to assign subjects to buckets deterministically:

// FNV-1a hash
let hash = 2166136261;  // offset basis
for (let i = 0; i < input.length; i++) {
  hash ^= input.charCodeAt(i);  // XOR with each byte
  hash = (hash * 16777619) >>> 0;  // FNV prime, unsigned
}
const percentage = hash % 100;
return percentage < rolloutPercentage;  // enabled if in bucket

Property	Detail
Hash input	`userId` (for `per_user`) or `tenantId` (for `per_tenant`)
Determinism	Same subject + same rollout config always yields the same bucket
Missing key	If the seed (`userId`/`tenantId`) is absent, the rollout returns `false` (not in bucket)
Flag isolation	The hash input is just the subject key — different flags with the same user will produce different buckets because the percentage threshold differs per flag config

Context attributes

The evaluation context is the set of attributes used for targeting rules and rollout bucketing:

Attribute	Type	Used for
`userId`	`string`	Targeting conditions, `per_user` rollout bucketing
`tenantId`	`string`	Targeting conditions, `per_tenant` rollout bucketing
`email`	`string`	Targeting conditions
`country`	`string`	Targeting conditions
`customAttributes`	`Record<string, string \| number \| boolean>`	Arbitrary targeting conditions

A condition’s attribute field references one of these keys by name (e.g. "country", "userId", or any custom attribute key). Standard attributes (userId, tenantId, email, country) are resolved directly; anything else is resolved from customAttributes.

Supported operators

Targeting rule conditions support these comparison operators:

Operator	Description	Applies to
`==`	Equals	string, number, boolean
`!=`	Not equals	string, number, boolean
`>`	Greater than	number
`<`	Less than	number
`>=`	Greater than or equal	number
`<=`	Less than or equal	number

Only the six operators above are supported. String operators like ends_with, starts_with, contains, etc. are not available. Use multiple prioritized flat rules with == / != to achieve more complex targeting.

Targeting rule evaluation logic

Rules with multiple conditions combine via the rule’s logic field:

and — every condition must match for the rule to fire
or — at least one condition must match

country == "US" AND plan == "premium" — one rule, logic: "and", two conditions.country == "US" OR plan == "premium" — one rule, logic: "or", two conditions.

Nested condition groups (e.g. (A AND B) OR (C AND (D OR E))) are not supported. The schema has no grouping/parent-condition column — conditions belong to a single flat rule. Achieve complex targeting via multiple prioritized rules evaluated in sequence.

Batch evaluation

The Evaluation API supports batch evaluation of up to 100 flags in a single request. Results are returned in the same order as the evaluations array — match by index, not by flagKey alone. Server-side path (POST /sdk/v1/evaluate/batch) — each item is evaluated with its own context, hitting the same cache + engine pipeline as single evaluation. SDK path — the SDK does not support batch evaluation directly. It fetches all configs via GET /sdk/v1/config and evaluates each flag once at fetch time (see SDK configuration).

Essentials

Feature Flags

Evaluation pipeline

Key ordering details

Evaluation reasons

Deterministic rollout

Context attributes

Supported operators

Targeting rule evaluation logic

Batch evaluation

​Evaluation pipeline

​Key ordering details

​Evaluation reasons

​Deterministic rollout

​Context attributes

​Supported operators

​Targeting rule evaluation logic

​Batch evaluation

Evaluation pipeline

Key ordering details

Evaluation reasons

Deterministic rollout

Context attributes

Supported operators

Targeting rule evaluation logic

Batch evaluation