@devcycle/js-client-sdk

# DevCycle JS Client SDK - Architecture & API Diagrams This document provides visual diagrams describing the functionality of each public-facing function in the DevCycle JS Client SDK. ## Table of Contents 1. [Initialization](#initialization) - [initializeDevCycle](#initializedevcyclesdkkey-user-options) - [onClientInitialized](#onclientinitializedcallback) 2. [Variable Evaluation](#variable-evaluation) - [variable](#variablekey-defaultvalue) - [variableValue](#variablevaluekey-defaultvalue) 3. [User Management](#user-management) - [identifyUser](#identifyuseruser-callback) - [resetUser](#resetusercallback) 4. [Data Retrieval](#data-retrieval) - [allFeatures](#allfeatures) - [allVariables](#allvariables) 5. [Event Tracking](#event-tracking) - [track](#trackevent) - [flushEvents](#flusheventscallback) 6. [Event Subscription](#event-subscription) - [subscribe](#subscribekey-handler) - [unsubscribe](#unsubscribekey-handler) 7. [Hooks](#hooks) - [addHook](#addhookhook) - [clearHooks](#clearhooks) 8. [Lifecycle](#lifecycle) - [close](#close) 9. [DVCVariable Class](#dvcvariable-class) - [onUpdate](#onupdatecallback) --- ## Initialization ### `initializeDevCycle(sdkKey, user, options)` Primary function to initialize the DevCycle SDK. Creates and returns a `DevCycleClient` instance that can be used to evaluate feature flags and track events. ```mermaid sequenceDiagram participant App participant SDK as DevCycleClient participant Cache as CacheStore participant API as DevCycle API participant SSE as Streaming Connection App->>SDK: initializeDevCycle(sdkKey, user, options) SDK->>Cache: Load cached config Cache-->>SDK: Cached config (if available) SDK->>API: Fetch latest config API-->>SDK: Bucketed config SDK->>SSE: Establish real-time connection SDK-->>App: DevCycleClient (ready) ``` --- ### `onClientInitialized(callback?)` Wait for the SDK to finish initializing. Can be used with either a callback or as a Promise. ```mermaid flowchart TD A[onClientInitialized] --> B{Callback provided?} B -->|Yes| C[Execute callback when ready] B -->|No| D[Return Promise] C --> E[callback error, client] D --> F[Resolves with DevCycleClient] ``` --- ## Variable Evaluation ### `variable(key, defaultValue)` Get a variable object for a feature flag. Returns a `DVCVariable` instance that contains the current value and supports reactive updates via `onUpdate()`. ```mermaid flowchart TD A[variable key, defaultValue] --> B{Config has variable?} B -->|Yes| C{Type matches?} B -->|No| E[Return DVCVariable with default] C -->|Yes| D[Return DVCVariable with config value] C -->|No| F[Log type mismatch warning] F --> E ``` --- ### `variableValue(key, defaultValue)` Get the value of a variable directly. This is a convenience method that calls `variable()` and returns just the value. ```mermaid flowchart TD A[variableValue key, defaultValue] --> B[Call variable key, defaultValue] B --> C[Get DVCVariable instance] C --> D[Return variable.value] ``` --- ## User Management ### `identifyUser(user, callback?)` Update the current user or identify a new user. This triggers a config refresh from the DevCycle API. ```mermaid sequenceDiagram participant App participant Client as DevCycleClient participant API as DevCycle API App->>Client: identifyUser(user) Client->>Client: Flush pending events Client->>API: Fetch config for new user API-->>Client: Updated config Client-->>App: Updated variables ``` --- ### `resetUser(callback?)` Reset the current user to an anonymous user. Generates a new anonymous ID and fetches fresh config. ```mermaid sequenceDiagram participant App participant Client as DevCycleClient participant Store as CacheStore participant API as DevCycle API App->>Client: resetUser() Client->>Client: Flush pending events Client->>Store: Remove old anonymous ID Client->>Client: Create new anonymous user Client->>API: Fetch config for new user API-->>Client: Updated config Client-->>App: Updated variables ``` --- ## Data Retrieval ### `allFeatures()` Get all features for the current user. Returns an object mapping feature keys to feature data. ```mermaid flowchart TD A[allFeatures] --> B{Config loaded?} B -->|Yes| C[Return config.features] B -->|No| D[Return empty object] ``` --- ### `allVariables()` Get all variables for the current user. Returns an object mapping variable keys to variable data. ```mermaid flowchart TD A[allVariables] --> B{Config loaded?} B -->|Yes| C[Return config.variables] B -->|No| D[Return empty object] ``` --- ## Event Tracking ### `track(event)` Track a custom event. Events are queued and sent to DevCycle in batches. ```mermaid sequenceDiagram participant App participant Client as DevCycleClient participant Queue as EventQueue App->>Client: track(event) Client->>Client: Validate event.type Client->>Queue: queueEvent(event) Note over Queue: Event added to batch ``` --- ### `flushEvents(callback?)` Manually flush all queued events to DevCycle. Useful before page unload 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 API-->>Queue: Acknowledged Queue-->>Client: Complete Client-->>App: Promise resolved ``` --- ## Event Subscription ### `subscribe(key, handler)` Subscribe to SDK events. The handler is called whenever the specified event is emitted. ```mermaid flowchart TD A[subscribe key, handler] --> B{Event Type} B --> C[initialized] B --> D[error] B --> E[configUpdated] B --> F[variableUpdated:*] B --> G[featureUpdated:*] B --> H[variableEvaluated:*] C --> I[handler success: boolean] D --> J[handler error: Error] E --> K[handler variables: DVCVariableSet] F --> L[handler key, variable] G --> M[handler key, feature] H --> N[handler key, variable] ``` --- ### `unsubscribe(key, handler?)` Remove an event subscription. If no handler is provided, removes all handlers for the given key. ```mermaid flowchart TD A[unsubscribe key, handler?] --> B{Handler provided?} B -->|Yes| C[Remove specific handler] B -->|No| D[Remove all handlers for key] C --> E[EventEmitter.unsubscribe] D --> E ``` --- ## 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] ``` --- ### `clearHooks()` Remove all registered evaluation hooks. ```mermaid flowchart TD A[clearHooks] --> B[EvalHooksRunner.clear] B --> C[All hooks removed] ``` --- ## Lifecycle ### `close()` Close the SDK client. Flushes pending events, closes connections, and removes event listeners. Call this when the client is no longer needed. ```mermaid sequenceDiagram participant App participant Client as DevCycleClient participant SSE as StreamingConnection participant Queue as EventQueue App->>Client: close() Client->>Client: Set closing = true Client->>Client: Remove event listeners Client->>SSE: close() Client->>Queue: close() Note over Queue: Flush remaining events Client-->>App: Promise resolved ``` --- ## DVCVariable Class ### `onUpdate(callback)` Register a callback that is called whenever the variable's value changes due to a config update. ```mermaid flowchart TD A[variable.onUpdate callback] --> B[Store callback on variable] B --> C[Return variable for chaining] D[Config update received] --> E{Variable value changed?} E -->|Yes| F[Call stored callback with new value] E -->|No| G[No action] ``` --- ## Additional Notes ### Error Handling Summary | Function | Consumer-Relevant Error Scenarios | |----------|-----------------------------------| | `initializeDevCycle` | Invalid SDK key throws `UserError`. Missing user throws `Error`. | | `identifyUser` | Config fetch failure falls back to cached config if available, otherwise throws. | | `resetUser` | Config fetch failure rolls back to previous anonymous ID and throws. | | `variable` | Type mismatch logs warning and returns default value (does not throw). | ### Real-time Updates The SDK establishes a Server-Sent Events (SSE) connection after initialization to receive real-time config updates. This connection: - Automatically reconnects when the page becomes visible - Closes after a period of inactivity when the page is hidden - Can be disabled via `options.disableRealtimeUpdates`