Offline Init Part 3 of 4: Add offlineInit() for synchronous SDK initialization without network by aarsilv · Pull Request #118 · Eppo-exp/node-server-sdk

aarsilv · 2026-01-20T01:32:40Z

Summary

Adds offlineInit() function to initialize the SDK with pre-fetched configuration
Enables SDK usage in environments without network access or for faster startup

Stacked PRs

Test plan

Verify offlineInit() initializes the client with provided configuration
Verify flag assignments work correctly after offline initialization
Verify getInstance() returns the client after offline init

🤖 Generated with Claude Code

aarsilv · 2026-01-20T03:50:23Z

src/i-client-config.ts

+   * }
+   * ```
+   */
+  flagsConfiguration: string;


Opted to deviate from our client JS SDK and follow in the footsteps of python and iOS using the more user-friendly and information-rich wire format.

aarsilv · 2026-01-20T04:07:17Z

src/i-client-config.ts

+  /**
+   * Configuration settings for the event dispatcher.
+   * @deprecated Eppo has discontinued eventing support. Event tracking will be handled by Datadog SDKs.
+   */


May as well start flagging this as deprecated so we can rip out in a future version! 🪓

aarsilv · 2026-01-20T04:07:33Z

src/index.ts

+/**
+ * @deprecated Eppo has discontinued eventing support. Event tracking will be handled by Datadog SDKs.
+ */


Deprecating this event-related method too! 🪓

aarsilv · 2026-01-20T04:11:08Z

src/index.ts

+ * @returns the initialized client instance
+ * @public
+ */
+export function offlineInit(config: IOfflineClientConfig): EppoClient {


🚀 The main new method!

Copilot

Pull request overview

This PR adds an offlineInit() function to enable synchronous SDK initialization using pre-fetched configuration, allowing the SDK to operate without network access or achieve faster startup times.

Changes:

Introduces offlineInit() function that parses and loads flag and bandit configurations from JSON strings
Adds IOfflineClientConfig interface for offline initialization configuration
Extracts DEFAULT_ASSIGNMENT_CACHE_SIZE constant to share between init() and offlineInit()

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.

File	Description
src/index.ts	Adds `offlineInit()` function, `IOfflineClientConfig` export, and `DEFAULT_ASSIGNMENT_CACHE_SIZE` constant
src/index.spec.ts	Comprehensive test suite for `offlineInit()` covering initialization, assignment logging, error handling, and bandit support
src/i-client-config.ts	Defines `IOfflineClientConfig` interface with documentation for offline initialization parameters

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-20T04:12:48Z

src/index.ts

+    // Note: setEntries is async but MemoryOnlyConfigurationStore performs synchronous operations internally,
+    // so there's no race condition. We add .catch() for defensive error handling, matching JS client SDK pattern.


The comment claims setEntries is async but MemoryOnlyConfigurationStore performs synchronous operations internally. This is confusing and potentially misleading. If the operations are truly synchronous, the method shouldn't return a promise. Consider clarifying whether this is actually asynchronous or if the promise is just for API consistency.

Suggested change

// Note: setEntries is async but MemoryOnlyConfigurationStore performs synchronous operations internally,

// so there's no race condition. We add .catch() for defensive error handling, matching JS client SDK pattern.

// Note: setEntries returns a Promise for API consistency, but MemoryOnlyConfigurationStore

// performs its work synchronously, so there is no race condition. We still attach .catch()

// for defensive error handling in case the Promise is ever rejected.

Copilot · 2026-01-20T04:12:48Z

src/index.ts

+      .catch((err) =>
+        applicationLogger.warn(`Error setting flags for memory-only configuration store: ${err}`),
+      );


The error message uses string interpolation with ${err} which will result in "[object Object]" for Error objects. Use err.message or handle the error object properly to provide a meaningful error message.

Suggested change

.catch((err) =>

applicationLogger.warn(`Error setting flags for memory-only configuration store: ${err}`),

);

.catch((err) => {

const message = err instanceof Error ? err.message : String(err);

applicationLogger.warn(

`Error setting flags for memory-only configuration store: ${message}`,

);

});

src/index.ts

Copilot · 2026-01-20T04:12:49Z

src/index.ts

+      banditModelConfigurationStore
+        .setEntries(banditsConfigResponse.bandits ?? {})
+        .catch((err) =>
+          applicationLogger.warn(
+            `Error setting bandit models for memory-only configuration store: ${err}`,
+          ),
+        );


The error message uses string interpolation with ${err} which will result in "[object Object]" for Error objects. Use err.message or handle the error object properly to provide a meaningful error message.

greghuels · 2026-01-20T12:10:12Z

src/index.ts

+    const flagsConfigResponse = JSON.parse(flagsConfiguration) as {
+      createdAt?: string;
+      format?: string;
+      environment?: { name: string };
+      flags: Record<string, Flag>;
+      banditReferences?: Record<
+        string,
+        {
+          modelVersion: string;
+          flagVariations: BanditVariation[];
+        }
+      >;
+    };


There should never be a situation where a configuration object is missing a key, so why not just validate that each field exists and throw or log an "invalid configuration" error if it's missing anything? That way you can cast to IUniversalFlagConfigResponse for valid configurations and you can remove the guards below. The main benefit here is that you reduce the chance that an invalid configuration causes issues in other parts of the SDK that expect certain fields to be set.

Great call! Will go beyond just parsing to checking expected keys are all there.

greghuels

Main issue is that I don't think we shouldn't allow invalid configurations

src/index.ts

aarsilv · 2026-01-26T03:15:23Z

src/index.ts

+  try {
+    // Parse and validate the flags configuration JSON
+    const parsedFlagsConfig = JSON.parse(flagsConfiguration);
+    const flagsValidationErrors = validateFlagsConfiguration(parsedFlagsConfig);


@greghuels Claude whipped this up to ensure we meet the type so we don't need to be super defensive with checking field existence per your suggestion

Nice, thanks for updating!

Adds the ability to initialize the SDK with pre-fetched configuration JSON, enabling: - Synchronous initialization without network requests - Use cases where configuration is bootstrapped from another source - Edge/serverless environments where polling isn't desired Also includes: - IOfflineClientConfig interface for offline initialization options - DEFAULT_ASSIGNMENT_CACHE_SIZE constant for consistent cache sizing - Deprecation annotations on event tracking (discontinued feature) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Use realistic bandit model coefficients from bandit-models-v1.json and test subject "alice" from test-case-banner-bandit.json to verify that getBanditAction returns the expected variation and action after offline initialization. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- Rename "makes client available via getInstance()" to "can request assignment" - Move "no network requests" test into "basic initialization" section - Add assignment verification to "empty flags configuration" test Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- Add validateFlagsConfiguration() to ensure all required fields exist - Add validateBanditsConfiguration() to validate bandit config structure - Update offlineInit() to validate configs before loading: - If validation fails and throwOnFailedInitialization=true: throw error - If validation fails and throwOnFailedInitialization=false: log warning and use empty config (all assignments return defaults) - Update test helper to include banditReferences field This ensures invalid configurations are caught early and provides clear error messages about what fields are missing or invalid. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- Reorder validation functions to follow clean code principles (high-level methods first) - Fix ${err} string interpolation to properly extract error messages Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

aarsilv mentioned this pull request Jan 20, 2026

Offline Init Part 4 of 4: Add shared test data round-trip tests for offline initialization #119

Merged

aarsilv force-pushed the aarsilv/ffesupport-461-offline-init-part2-get-bandits-configuration branch from 6109625 to 7eb55bb Compare January 20, 2026 03:04

aarsilv force-pushed the aarsilv/ffesupport-461-offline-init-part3-offline-init branch 2 times, most recently from c6bb75d to a769852 Compare January 20, 2026 03:08

aarsilv force-pushed the aarsilv/ffesupport-461-offline-init-part2-get-bandits-configuration branch from 5c56e10 to eae1ff4 Compare January 20, 2026 03:10

aarsilv force-pushed the aarsilv/ffesupport-461-offline-init-part3-offline-init branch from a769852 to b9221c2 Compare January 20, 2026 03:10

This was referenced Jan 20, 2026

Offline Init Part 1 of 4: Add getFlagsConfiguration() to export flag configuration as JSON #116

Merged

Offline Init Part 2 of 4: Add getBanditsConfiguration() to export bandit models as JSON #117

Merged

aarsilv changed the title ~~Add offlineInit() for synchronous SDK initialization without network~~ Offline Init Part 3 of 4: Add offlineInit() for synchronous SDK initialization without network Jan 20, 2026

aarsilv force-pushed the aarsilv/ffesupport-461-offline-init-part2-get-bandits-configuration branch from eae1ff4 to 3f88511 Compare January 20, 2026 03:20

aarsilv force-pushed the aarsilv/ffesupport-461-offline-init-part3-offline-init branch 2 times, most recently from 7cc0255 to 0466712 Compare January 20, 2026 03:24

aarsilv force-pushed the aarsilv/ffesupport-461-offline-init-part2-get-bandits-configuration branch from 7396a8f to 128bac6 Compare January 20, 2026 03:41

aarsilv force-pushed the aarsilv/ffesupport-461-offline-init-part3-offline-init branch 2 times, most recently from 065c1b6 to 3b021c2 Compare January 20, 2026 03:48

aarsilv commented Jan 20, 2026

View reviewed changes

aarsilv marked this pull request as ready for review January 20, 2026 04:12

aarsilv requested review from Copilot, greghuels and sameerank January 20, 2026 04:12

aarsilv assigned greghuels Jan 20, 2026

Copilot AI reviewed Jan 20, 2026

View reviewed changes

greghuels reviewed Jan 20, 2026

View reviewed changes

greghuels requested changes Jan 20, 2026

View reviewed changes

greghuels assigned aarsilv and unassigned greghuels Jan 21, 2026

aarsilv force-pushed the aarsilv/ffesupport-461-offline-init-part2-get-bandits-configuration branch from 1eb8a4e to 87e6424 Compare January 26, 2026 02:28

aarsilv force-pushed the aarsilv/ffesupport-461-offline-init-part3-offline-init branch 2 times, most recently from 4bd2bc5 to ae372fa Compare January 26, 2026 02:31

aarsilv force-pushed the aarsilv/ffesupport-461-offline-init-part2-get-bandits-configuration branch from b235e30 to c35ea62 Compare January 26, 2026 02:48

aarsilv force-pushed the aarsilv/ffesupport-461-offline-init-part3-offline-init branch 2 times, most recently from 96ca311 to 5a34532 Compare January 26, 2026 03:05

aarsilv commented Jan 26, 2026

View reviewed changes

aarsilv requested a review from greghuels January 26, 2026 03:15

aarsilv assigned greghuels and unassigned aarsilv Jan 26, 2026

greghuels approved these changes Jan 26, 2026

View reviewed changes

greghuels assigned aarsilv and unassigned greghuels Jan 26, 2026

aarsilv force-pushed the aarsilv/ffesupport-461-offline-init-part2-get-bandits-configuration branch from 291bc6f to f3ee984 Compare January 27, 2026 00:12

Base automatically changed from aarsilv/ffesupport-461-offline-init-part2-get-bandits-configuration to main January 27, 2026 00:13

aarsilv and others added 5 commits January 26, 2026 19:14

Move validation functions after offlineInit, fix error logging

6111973

- Reorder validation functions to follow clean code principles (high-level methods first) - Fix ${err} string interpolation to properly extract error messages Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

aarsilv force-pushed the aarsilv/ffesupport-461-offline-init-part3-offline-init branch from 75ac5ee to 6111973 Compare January 27, 2026 00:14

aarsilv merged commit c266cf1 into main Jan 27, 2026
8 checks passed

aarsilv deleted the aarsilv/ffesupport-461-offline-init-part3-offline-init branch January 27, 2026 00:16

		// Note: setEntries is async but MemoryOnlyConfigurationStore performs synchronous operations internally,
		// so there's no race condition. We add .catch() for defensive error handling, matching JS client SDK pattern.

-    // Note: setEntries is async but MemoryOnlyConfigurationStore performs synchronous operations internally,
-    // so there's no race condition. We add .catch() for defensive error handling, matching JS client SDK pattern.
+    // Note: setEntries returns a Promise for API consistency, but MemoryOnlyConfigurationStore
+    // performs its work synchronously, so there is no race condition. We still attach .catch()
+    // for defensive error handling in case the Promise is ever rejected.

Conversation

aarsilv commented Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Stacked PRs

Test plan

Uh oh!

aarsilv Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

aarsilv Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

aarsilv Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

aarsilv Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

greghuels Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aarsilv Jan 21, 2026

Choose a reason for hiding this comment

Uh oh!

greghuels left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

aarsilv Jan 26, 2026

Choose a reason for hiding this comment

Uh oh!

greghuels Jan 26, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

aarsilv commented Jan 20, 2026 •

edited

Loading

greghuels Jan 20, 2026 •

edited

Loading