Skip to main content

​
How evaluation works

Flag evaluation never hits the management API database on the hot path. Instead:
  1. SDK initialisation — the SDK fetches the full flag bundle for your environment from the Delivery API. The bundle is a JSON snapshot of all flag configs, served from an edge cache and held in-process for 30 seconds.
  2. evaluate() call — the rule engine runs entirely in your process against the cached bundle. No network I/O.
  3. Telemetry flush — evaluation events are buffered in memory and flushed to the Management API asynchronously. Your application never waits for telemetry.

​
Evaluation reasons

Every evaluation returns a reason alongside the resolved value:
ReasonMeaning
DISABLEDThe flag’s master enabled switch is false
RULE_MATCHA rule matched and its value was returned
ROLLOUTA rule matched but evaluation was gated by rolloutPercentage — this user is in the rollout bucket
DEFAULTNo rule matched; defaultValue was returned
CLIENT_RESTRICTEDA client API key attempted to evaluate a flag with clientSafe: false
FLAG_NOT_FOUNDThe flag key does not exist in the bundle for this environment
ERRORAn unexpected error occurred in the engine — defaultValue was returned
The engine never throws. Any unhandled error results in { reason: "ERROR", value: defaultValue }.

​
Evaluation context

Pass any attributes you want to target on: 
const value = await client.evaluate("my-flag", {
  userId: "user_abc123",
  plan: "pro",
  country: "US",
  email: "alice@example.com",
  // ... any custom attribute
});
Attributes are matched against rule conditions. Unknown attributes are ignored.

​
Bundle format

The cache key for an environment’s flag bundle is: 
env:{environmentId}:flags
The bundle is a JSON object mapping flag keys to their latest FlagConfig. The Delivery API reads this key on cold start, then serves from an in-process cache for subsequent requests within the same worker lifetime.

​
Cold start path

On a cold start, the Delivery API performs at most 2 cache reads:
  1. sdk:{keyHash} — resolve the API key to orgId + environmentId
  2. env:{environmentId}:flags — fetch the flag bundle
Subsequent evaluations in the same worker instance use the in-memory cache.