@devcycle/nodejs-server-sdk

# DevCycle Node.js Server SDK - Architecture & API Diagrams (Local Bucketing) This document provides visual diagrams describing the functionality of each public-facing function in the DevCycle Node.js Server SDK using **Local Bucketing** mode (the default). Local Bucketing uses a WebAssembly library to evaluate flags locally. Configuration is fetched from the DevCycle CDN and cached. All evaluations are synchronous. For Cloud Bucketing mode documentation, see [ARCHITECTURE-CLOUD.md](./ARCHITECTURE-CLOUD.md). ## Table of Contents 1. [Initialization](#initialization) - [initializeDevCycle](#initializedevcyclesdkkey-options) - [onClientInitialized](#onclientinitializedcallback) 2. [Variable Evaluation](#variable-evaluation) - [variable](#variableuser-key-defaultvalue) - [variableValue](#variablevalueuser-key-defaultvalue) 3. [Data Retrieval](#data-retrieval) - [allVariables](#allvariablesuser) - [allFeatures](#allfeaturesuser) 4. [Event Tracking](#event-tracking) - [track](#trackuser-event) - [flushEvents](#flusheventscallback) 5. [Hooks](#hooks) - [addHook](#addhookhook) 6. [Client Bootstrapping](#client-bootstrapping) - [getClientBootstrapConfig](#getclientbootstrapconfiguser-useragent) 7. [Custom Data](#custom-data) - [setClientCustomData](#setclientcustomdatacustomdata) 8. [Lifecycle](#lifecycle) - [close](#close) --- ## Initialization ### `initializeDevCycle(sdkKey, options)` Creates and returns a `DevCycleClient` for local bucketing. The client initializes asynchronously by fetching configuration from the DevCycle CDN. ```mermaid sequenceDiagram participant App participant Init as initializeDevCycle participant Client as DevCycleClient participant WASM as Bucketing Library participant CDN as DevCycle CDN App->>Init: initializeDevCycle(sdkKey, options) Init->>Client: new DevCycleClient(sdkKey, options) Client->>WASM: Import WASM bucketing library Client->>CDN: Fetch project config CDN-->>Client: Project config Client->>WASM: Load config into WASM Client-->>App: DevCycleClient ``` --- ### `onClientInitialized(callback?)` Wait for the SDK to finish initializing. The client fetches configuration from the CDN before it's ready. ```mermaid flowchart TD A[onClientInitialized] --> B{Callback provided?} B -->|Yes| C[Execute callback when ready] B -->|No| D[Return Promise] C --> E[callback err?] D --> F[Resolves with DevCycleClient] ``` --- ## Variable Evaluation ### `variable(user, key, defaultValue)` Get a variable object for a feature flag. Returns a `DVCVariable` instance containing the value and evaluation metadata. Evaluations are **synchronous** using the WASM bucketing library. ```mermaid flowchart TD A[variable user, key, defaultValue] --> B{Config loaded?} B -->|No| C[Log warning Return DVCVariable with default] B -->|Yes| D[Populate user with platform data] D --> E[WASM: variableForUser_PB] E --> F{Variable found?} F -->|Yes| G{Type matches?} F -->|No| H[Return DVCVariable with default] G -->|Yes| I[Return DVCVariable with config value] G -->|No| J[Log type mismatch error] J --> H ``` --- ### `variableValue(user, key, defaultValue)` Get the value of a variable directly. Convenience method that calls `variable()` and returns just the value. ```mermaid flowchart TD A[variableValue user, key, defaultValue] --> B[Call variable user, key, defaultValue] B --> C[Get DVCVariable instance] C --> D[Return variable.value] ``` --- ## Data Retrieval ### `allVariables(user)` Get all variables for a user. Returns an object mapping variable keys to variable data. ```mermaid flowchart TD A[allVariables user] --> B{Config loaded?} B -->|No| C[Log warning Return empty object] B -->|Yes| D[Populate user with platform data] D --> E[WASM: bucketUserForConfig] E --> F[Return config.variables] ``` --- ### `allFeatures(user)` Get all features for a user. Returns an object mapping feature keys to feature data. ```mermaid flowchart TD A[allFeatures user] --> B{Config loaded?} B -->|No| C[Log warning Return empty object] B -->|Yes| D[Populate user with platform data] D --> E[WASM: bucketUserForConfig] E --> F[Return config.features] ``` --- ## Event Tracking ### `track(user, event)` Track a custom event. Events are queued and batched for efficient delivery. ```mermaid sequenceDiagram participant App participant Client as DevCycleClient participant Queue as EventQueue App->>Client: track(user, event) Client->>Client: Validate event.type alt Not initialized Client-->>App: Log warning, return end Client->>Client: Populate user with platform data Client->>Queue: queueEvent(user, event) Note over Queue: Event added to batch Flushed on interval or manually ``` --- ### `flushEvents(callback?)` Manually flush all queued events to DevCycle. Useful before process exit or when immediate delivery is needed. ```mermaid sequenceDiagram participant App participant Client as DevCycleClient participant Queue as EventQueue participant API as DevCycle API App->>Client: flushEvents() Client->>Queue: flushEvents() Queue->>API: POST /v1/events (batched) API-->>Queue: Acknowledged Queue-->>Client: Complete Client-->>App: Promise resolved ``` --- ## Hooks ### `addHook(hook)` Add an evaluation hook that runs before and/or after variable evaluations. Hooks can be used for logging, analytics, or custom processing. ```mermaid flowchart TD A[addHook hook] --> B[EvalHooksRunner.enqueue] B --> C[Hook stored in runner] D[variable called] --> E[Run beforeEvaluate hooks] E --> F[Evaluate variable] F --> G[Run afterEvaluate hooks] ``` --- ## Client Bootstrapping ### `getClientBootstrapConfig(user, userAgent)` Generate a configuration object suitable for bootstrapping a client-side SDK. This enables server-side rendering scenarios where the server provides initial flag values to the client. Requires `enableClientBootstrapping: true` in initialization options. ```mermaid sequenceDiagram participant App participant Client as DevCycleClient participant WASM as Bucketing Library App->>Client: getClientBootstrapConfig(user, userAgent) Client->>Client: await onInitialized alt enableClientBootstrapping not set Client-->>App: Throw Error end Client->>WASM: getSDKKeyFromConfig (get client SDK key) WASM-->>Client: clientSDKKey alt No client SDK key found Client-->>App: Throw Error end Client->>Client: Generate client populated user Client->>WASM: bucketUserForConfig (using client config) WASM-->>Client: BucketedUserConfig Client-->>App: BucketedUserConfig + clientSDKKey ``` --- ## Custom Data ### `setClientCustomData(customData)` Set custom data that will be used for all subsequent bucketing operations. Useful for setting global context that applies to all users. ```mermaid flowchart TD A[setClientCustomData customData] --> B{Bucketing lib loaded?} B -->|No| C[Return silently] B -->|Yes| D[bucketingLib.setClientCustomData] D --> E[Custom data stored in WASM Used for all evaluations] ``` --- ## Lifecycle ### `close()` Close the SDK client. Flushes pending events, stops config polling, and cleans up resources. Should be called before process exit. ```mermaid sequenceDiagram participant App participant Client as DevCycleClient participant Config as ConfigManager participant Queue as EventQueue App->>Client: close() Client->>Client: await onInitialized Client->>Queue: flushEvents() Queue-->>Client: Events flushed Client->>Config: cleanup() Note over Config: Stop polling Close SSE connection Client->>Queue: cleanup() Note over Queue: Stop flush interval Client->>Client: Clear bucketing tracker interval Client-->>App: Promise resolved ``` --- ## Additional Notes ### Error Handling Summary | Function | Consumer-Relevant Error Scenarios | |----------|-----------------------------------| | `initializeDevCycle` | Invalid SDK key throws `Error`. | | `variable` | Returns default value if config not loaded or type mismatch (does not throw). | | `allVariables` / `allFeatures` | Returns empty object if config not loaded (does not throw). | | `track` | Logs warning if not initialized (does not throw). | | `getClientBootstrapConfig` | Throws if `enableClientBootstrapping` option not set. |