feat: Adds feature flags runtime client with local evaluation

[stanleyphu]

Description

• Adds FeatureFlagsRuntimeClient, a polling-based client that fetches all flag configurations from /sdk/feature-flags and evaluates them locally in-memory. Targeting rules (org-level and user-level) are resolved client-side with zero per-request API overhead.
• Exposed via workos.featureFlags.createRuntimeClient(options?).

Implementation Details

• InMemoryStore — atomic-swap key/value store for flag data
• Evaluator — stateless evaluation: flag enabled → org target → user target → default value
• FeatureFlagsRuntimeClient — orchestrates polling, caching, and evaluation
  • Configurable polling interval (default 30s, min 5s) with jitter
  • Exponential backoff on consecutive errors (capped at 60s)
  • Stops polling on 401 and emits 'failed' event
  • waitUntilReady() with optional timeout
  • Bootstrap flags for instant availability before first poll
  • 'change' events when flags are added, modified, or removed
  • getStats() for observability

Usage

Basic usage

import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_test_...');
const client = workos.featureFlags.createRuntimeClient();

await client.waitUntilReady();

if (client.isEnabled('new-dashboard')) {
  // serve new dashboard
}

With targeting context

// User-level targeting
client.isEnabled('beta-feature', { userId: 'user_123' });

// Org-level targeting
client.isEnabled('enterprise-feature', { organizationId: 'org_456' });

// Both
client.isEnabled('rollout-feature', {
  userId: 'user_123',
  organizationId: 'org_456',
});

// Custom default when flag doesn't exist
client.isEnabled('unknown-flag', {}, true); // returns true instead of false

Configuration options

const client = workos.featureFlags.createRuntimeClient({
  pollingIntervalMs: 10000,    // poll every 10s (min 5s)
  requestTimeoutMs: 5000,      // timeout per poll request
  bootstrapFlags: cachedFlags,  // pre-populate store for instant reads
  logger: console,              // any object with debug/info/warn/error
});

Reacting to changes

client.on('change', ({ key, previous, current }) => {
  console.log(`Flag ${key} changed`, { previous, current });
});

client.on('error', (err) => {
  console.error('Poll failed, will retry:', err.message);
});

client.on('failed', (err) => {
  // Unrecoverable (e.g. 401) — client has stopped polling
  console.error('Client stopped:', err.message);
});

Evaluating all flags at once

const flags = client.getAllFlags({ userId: 'user_123' });
// { 'new-dashboard': true, 'beta-feature': false, ... }

Observability

const stats = client.getStats();
// { pollCount: 42, pollErrorCount: 1, cacheAge: 12340, flagCount: 5, ... }

Cleanup

client.close(); // stops polling, removes listeners

Documentation

Does this require changes to the WorkOS Docs? E.g. the API Reference or code snippets need updates.

[ ] Yes

If yes, link a related docs PR and add a docs maintainer as a reviewer. Their approval is required.

[greptile-apps]

Greptile Summary

This PR introduces FeatureFlagsRuntimeClient, a polling-based, locally-evaluating feature-flag client exposed via workos.featureFlags.createRuntimeClient(). It includes an InMemoryStore for atomic flag swaps, an Evaluator for user/org targeting, configurable polling with jitter and exponential backoff, bootstrap support for instant availability, change-event diffing, and a waitUntilReady() promise with optional timeout — all well-covered by unit tests.

Key changes:

• runtime-client.ts — core client with polling loop, abort handling, backoff, and change detection
• evaluator.ts — stateless evaluation: user target → org target → default_value precedence
• in-memory-store.ts — defensive-copy swap store
• feature-flags.ts — createRuntimeClient() factory method
• New interfaces: EvaluationContext, FlagPollResponse, RuntimeClientOptions, RuntimeClientStats

Issues found:

• P1 — close() does not call readyReject, so any waitUntilReady() caller without a timeout will hang indefinitely if the client is closed before it becomes ready.
• P2 — waitUntilReady({ timeoutMs: 0 }) is silently treated as "no timeout" because !0 === true bypasses the timeout branch.

Confidence Score: 4/5

Safe to merge after addressing the P1 close() issue that can cause process hang on shutdown.

One P1 defect remains: close() never calls readyReject, meaning a pending waitUntilReady() without a timeout will hang forever if close() is invoked before initialization completes. All previously raised concerns (abort guard, order-sensitive diff, 401 rejection) were addressed.

src/feature-flags/runtime-client.ts — specifically the close() method and waitUntilReady guard condition

Important Files Changed

Filename	Overview
src/feature-flags/runtime-client.ts	Core polling client; close() does not reject pending readyPromise, risking indefinite hangs on shutdown. Minor falsy-check issue in waitUntilReady.
src/feature-flags/evaluator.ts	Stateless flag evaluator: user target → org target → default_value precedence. Logic is correct and well-tested.
src/feature-flags/in-memory-store.ts	Simple atomic-swap key/value store; defensive copies on read and write look correct.
src/feature-flags/feature-flags.ts	Adds createRuntimeClient factory method delegating to FeatureFlagsRuntimeClient; straightforward change.
src/feature-flags/runtime-client.spec.ts	Comprehensive test suite covering polling, backoff, change events, error handling, and bootstrap flags.

Sequence Diagram

sequenceDiagram
    participant Caller
    participant Client as FeatureFlagsRuntimeClient
    participant Store as InMemoryStore
    participant Evaluator
    participant API as WorkOS API

    Caller->>Client: createRuntimeClient(options)
    Note over Client: Bootstrap flags → store.swap(), resolveReady()
    Client-->>Client: setTimeout(() => poll(), 0)

    Client->>API: GET /sdk/feature-flags
    alt success
        API-->>Client: FlagPollResponse
        Client->>Store: store.swap(data)
        Client-->>Client: resolveReady()
        Client-->>Caller: emit('change', ...) [if 2nd+ poll]
        Client-->>Client: scheduleNextPoll(baseDelay + jitter)
    else error (non-401)
        API-->>Client: Error
        Client-->>Caller: emit('error', err)
        Client-->>Client: scheduleNextPoll(backoff + jitter)
    else 401 Unauthorized
        API-->>Client: UnauthorizedException
        Client-->>Caller: emit('error', err)
        Client-->>Caller: emit('failed', err)
        Client-->>Client: readyReject(err) [if not initialized]
        Note over Client: Polling stops permanently
    end

    Caller->>Client: waitUntilReady({ timeoutMs? })
    Client-->>Caller: readyPromise (resolves or rejects)

    Caller->>Client: close()
    Client-->>Client: closed=true, abort in-flight, clearTimer, removeAllListeners

Loading

Comments Outside Diff (1)

1. src/feature-flags/runtime-client.ts, line 1022-1030 (link)

   close() leaves pending waitUntilReady() promises hanging indefinitely

   close() aborts the in-flight poll and clears the timer, but never calls this.readyReject. Any caller currently awaiting waitUntilReady() without a timeoutMs (e.g. during graceful shutdown) will have their promise suspended forever, preventing the Node.js process from exiting and leaking the pending microtask.

   Concrete scenario:

   const client = workos.featureFlags.createRuntimeClient();
   const ready = client.waitUntilReady(); // no timeout
   // ... server is unreachable, first poll is in-flight
   client.close();
   await ready; // hangs forever — process cannot exit

   Fix: reject readyPromise in close():

   close(): void {
     this.closed = true;
     this.pollAbortController?.abort();
     if (this.pollTimer) {
       clearTimeout(this.pollTimer);
       this.pollTimer = null;
     }
     if (this.readyReject) {
       this.readyReject(new Error('Client closed before becoming ready'));
       this.readyReject = null;
     }
     this.removeAllListeners();
   }

_{Reviews (3): Last reviewed commit: "fix: Reject waitUntilReady on 401 before..." | Re-trigger Greptile}

[gjtorikian]

@greptile review

[gjtorikian]

@greptile review