feat: buildAndInit for isolated client instances #166

typotter · 2025-01-31T16:40:41Z

labels: mergeable

Eppo Internal
🎟️ Fixes: FF-3888
📜 Multiple Eppo Clients
Configuration Side-loading

Motivation and Context

The init and getInstance() methods work on a singleton instance of the EppoClient which makes for a generally smooth developer experience given that the Eppo SDK essentially handles dependency management for the dev. This does have its own drawbacks, but those are not particularly relevant here.

There are use cases, however, when a non-singleton instance of the EppoClient is required. One such use case is embedding the Eppo SDK into a library which itself can be included in other applications. If that 3p library shipped with Eppo is integrated into another application that has the Eppo SDK running, there would be undefined behaviour as the SDK cannot handle this use case.

The init method (and class constructors) for EppoClient and subclasses have evolved organically over time, adding new options as new features are added to the clients. The very large options type is beginning to become a little untenable and disorganized so we take the opportunity to clean that up a bit here.

There are other limitations and drawbacks to the current model of instantiating an EppoClient statically and then initializing it when the code calls init including the awkward coupling of needing to wait for init to resolve in order to get a reference to an initialized client. We have an opportunity to decouple initialization and waiting to make for a better DX (in addition to giving the dev full control over managing the EppoClient reference (intrinsically allows for easier mocking in tests and will be consistent with the host applications existing DI approach).

This change must be done without a major version bump and completely preserve the existing singleton API

Description

Refactor the initialization options by grouping related options and extracting different types for each.
Each option type is then combined back into a type using the existing IClientConfig name (this keeps the change backwards compatible while offering a big win in option clarity)
- New method: buildAndInit which creates an isolated client instance.
- new method: waitForConfiguration which resolves when the first config is loaded.
Docs

How has this been documented?

https://linear.app/eppo/issue/FF-3926/[docs]-update-js-client-docs-to-describe-the-non-singleton-client

How has this been tested?

tests

package.json

src/i-client-config.ts

src/index.ts

typotter · 2025-01-31T19:41:48Z

src/index.ts

+    }
+  }
+
+  public waitForReady(): Promise<void> {


new method! 🎉

what does "ready" mean in this context? adding comments is likely to help, also we should always do it for public APIs anyways

renamed to waitForInitialization

waitForConfiguration to be in line with multiplatform's analog PollerThread::waitForConfiguration

src/index.ts

typotter · 2025-01-31T19:42:41Z

src/index.ts

-    if (!EppoJSClient.initialized) {
+  private ensureInitialized() {
+    if (!this.initialized) {
+      // TODO: check super.isInitialized?


EppoClient.initialized also exists, but means something different than it does here.

what does it mean and how is that different than this? consider renaming either if so

the super method checks that all the config stores are initialized while this this.initialized is true when all the initialization workload is done so they are pretty much the same.
I think we can move to deprecate EppoJSClient.initialized and defer to super.isInitialized().

typotter · 2025-01-31T19:43:39Z

src/index.ts

+  /**
+   * Tracks pending initialization. After an initialization completes, the value is removed from the map.
+   */
+  private static initializationPromise: Promise<EppoJSClient> | null = null;
+
+  /**
+   * This method is part of a bridge from using a singleton to independent instances. More specifically, it exists so
+   * that the init method can access the private field, `readyResolver`. It should not be called by any
+   * methods other than the `init` method. There are limited guards in place; the behaviour if called inappropriately
+   * is undefined.
+   *
+   * It also keeps code that relies on internal details of EppoJSClient colocated in the class.
+   *
+   * @internal
+   *
+   * @param client
+   * @param config
+   */
+  static async initializeClient(
+    client: EppoJSClient,
+    config: IClientConfig,
+  ): Promise<EppoJSClient> {
+    validation.validateNotBlank(config.apiKey, 'API key required');
+
+    // If there is already an init in progress for this apiKey, return that.
+    if (!EppoJSClient.initializationPromise) {
+      EppoJSClient.initializationPromise = explicitInit(config, client).then((client) => {
+        // Resolve the ready promise if it exists
+        if (client.readyPromiseResolver) {
+          client.readyPromiseResolver();
+          client.readyPromiseResolver = null;
+        }
+        return client;
+      });
+    }
+
+    const readyClient = await EppoJSClient.initializationPromise;
+    EppoJSClient.initializationPromise = null;
+
+    return readyClient;
+  }
 }


This is the old init method and initialization buffer tracker.
Moved the method to a static member of EppoJSClient so that it can access the readyResolver and notify waitForReady

src/index.ts

typotter · 2025-01-31T19:46:45Z

src/index.ts

 /**
 * Initializes the Eppo client with configuration parameters.
 * This method should be called once on application startup.
 * If an initialization is in process, calling `init` will return the in-progress
 * `Promise<EppoClient>`. Once the initialization completes, calling `init` again will kick off the
 * initialization routine (if `forceReinitialization` is `true`).
+ *
+ *
+ * @deprecated


controversial, I know.
willing to negotiate

Seems like a minor change for the end user if the argument interface stays identical

The @deprecated annotation is here to help push devs to using the new construct + wait paradigm. This method will be removed and the argument interface for the new constructor is slightly different sdkKey vs apiKey

src/index.ts

typotter · 2025-02-14T17:11:07Z

Several false starts and iterations later, we're ready for another review. Note: this PR is now stacked on #170 where changes are made just to how the singleton is referenced, leaving the focus of this PR on waitForConfiguration and buildAndInit.

aarsilv · 2025-02-16T05:17:15Z

src/i-client-config.ts

@@ -165,4 +189,77 @@ export interface IClientConfig extends IBaseRequestConfig {
     */
    maxQueueSize?: number;
  };
+};
+
+export type IStorageOptions = {


Perfect thanks! And now that I think about it if the have the same API it's actually probably not too bad if they are messing with eachother's persistent storage anyways as they should be using same configuration

aarsilv · 2025-02-16T05:20:11Z

src/index.ts

+
+  /**
+   * Resolved when the client is initialized
+   * @private


super minor, but does this annotation really add anything given the private keyword two lines later?

nope. eager IDE.

aarsilv · 2025-02-16T05:22:44Z

src/index.ts

@@ -620,6 +657,7 @@ export async function init(config: IClientConfig): Promise<EppoJSClient> {
 /**
 * Used to access a singleton SDK client instance.
 * Use the method after calling init() to initialize the client.
+ * @deprecated


consider adding what the user should do instead after @deprecated (e.g., why is this deprecated)

Undeprecated the singleton (for now)

felipecsl

Main feedback is around documentation and providing alternative APIs for what's been deprecated. I'm ready to approve after that, great work!

felipecsl · 2025-02-18T18:03:25Z

docs/js-client-sdk.eppojsclient.initialized.md

@@ -4,6 +4,10 @@

 ## EppoJSClient.initialized property

+> Warning: This API is now obsolete.


did you mean deprecated instead of obsolete?

I'm not sure whereyarn docs is getting this text from

felipecsl · 2025-02-18T18:03:42Z

docs/js-client-sdk.getinstance.md

@@ -4,6 +4,10 @@

 ## getInstance() function

+> Warning: This API is now obsolete.


same question

also whenever deprecating something, we should always propose an alternative so users are not left guessing.

This file is auto-generated, so the text is out of my hands. I have, however, updated all of the deprecated tags with an alternative. thank you

felipecsl · 2025-02-18T18:05:09Z

src/i-client-config.ts

-   */
-  forceReinitialize?: boolean;
-
+export type IEventOptions = {


this needs docs

felipecsl · 2025-02-18T18:05:44Z

src/i-client-config.ts

@@ -165,4 +189,77 @@ export interface IClientConfig extends IBaseRequestConfig {
     */
    maxQueueSize?: number;
  };
+};
+
+export type IStorageOptions = {


documentation for this type missing

felipecsl · 2025-02-18T18:06:07Z

src/i-client-config.ts

+  ILoggers &
+  IEventOptions &
+  IStorageOptions &
+  IPollingOptions;


i love this! thanks for organizing

felipecsl · 2025-02-18T18:07:58Z

src/index.ts

@@ -109,10 +111,57 @@ export class EppoJSClient extends EppoClient {
    isObfuscated: true,
  });

+  /**
+   * @deprecated


alternative?

documented!

felipecsl · 2025-02-18T18:08:48Z

src/index.ts

+   * Resolved when the client is initialized
+   * @private
+   */
+  private readonly initializedPromise: Promise<void>;


nit: i'd rename to initializationPromise or simply initPromise

good point. It's not an initialized promise, it's a promise signalling when it is initialized.

typotter · 2025-02-21T06:45:22Z

Thank you, @rasendubi @felipecsl @aarsilv for you reviews and patience as we explore this change.

I have made a key change - the singleton init and getInstance are no longer deprecated. I still fell that's the right direction to take, but for now, let's ship this feature and continue to polish afterwards.

PTAL

felipecsl · 2025-02-21T23:20:49Z

src/index.ts

+   * Initialization happens outside the constructor, so we can't assign `initPromise` to the result
+   * of initialization. Instead, we call the resolver when `init` is complete.
+   */
+  private initializedPromiseResolver: () => void = () => null;


nit: initPromiseResolver

typotter added 3 commits January 30, 2025 12:13

detatched construction

e20ef73

combine new and old constructors

50e66aa

use spark for md5 instead of non-exported member from common

de9f653

typotter commented Jan 31, 2025

View reviewed changes

package.json Outdated Show resolved Hide resolved

typotter changed the title ~~Tp/namespace~~ feat: non-singleton EppoJSClient Jan 31, 2025

typotter added 2 commits January 31, 2025 12:13

update to latest common, use exported members

fa5baab

doc comments

953c4e4

typotter commented Jan 31, 2025

View reviewed changes

src/i-client-config.ts Outdated Show resolved Hide resolved

typotter added 2 commits January 31, 2025 12:33

wip

159df11

skip initial config for now

a73bf0c

typotter force-pushed the tp/namespace branch from 5c466e9 to a73bf0c Compare January 31, 2025 19:35

exports

7e5abe1

typotter commented Jan 31, 2025

View reviewed changes

src/index.ts Outdated Show resolved Hide resolved

waitForReady

92cdd1d

typotter commented Jan 31, 2025

View reviewed changes

src/index.ts Outdated Show resolved Hide resolved

typotter commented Jan 31, 2025

View reviewed changes

clean up offline init method

c4b2717

typotter commented Jan 31, 2025

View reviewed changes

src/index.ts Outdated Show resolved Hide resolved

typotter commented Jan 31, 2025

View reviewed changes

src/index.ts Outdated Show resolved Hide resolved

typotter commented Jan 31, 2025

View reviewed changes

src/index.ts Show resolved Hide resolved

typotter commented Jan 31, 2025

View reviewed changes

src/index.ts Outdated Show resolved Hide resolved

typotter commented Jan 31, 2025

View reviewed changes

src/index.ts Outdated Show resolved Hide resolved

typotter added 2 commits January 31, 2025 12:49

no need to export

ddab6c0

DOCS

d55d23d

typotter requested review from aarsilv, felipecsl and rasendubi January 31, 2025 19:54

typotter added 11 commits February 14, 2025 09:12

docs

febb3f8

move members

212e26e

refactor wip

a943e90

chore: Move initialization code from static to the instance

ba219f2

docs

5333574

lint

aab1009

docs

f93fa61

docs

030aa33

merge fixes

e61ec6c

fix the horrible diff and merge artifacts

a000205

docs

6f1a68e

typotter commented Feb 14, 2025

View reviewed changes

src/index.ts Show resolved Hide resolved

typotter requested a review from rasendubi February 14, 2025 17:09

cleamup merge

654ffaa

aarsilv reviewed Feb 16, 2025

View reviewed changes

Base automatically changed from typo/no-singleton to main February 18, 2025 17:41

typotter added 2 commits February 18, 2025 10:49

merge main

74498b9

docs

9176d21

felipecsl reviewed Feb 18, 2025

View reviewed changes

typotter added 3 commits February 20, 2025 22:45

merge main

a179e32

chore: lint

0734752

undeprecate

fb76db9

typotter changed the title ~~feat: non-singleton EppoJSClient~~ feat: buildAndInit for isolated client instances Feb 21, 2025

typotter added 4 commits February 20, 2025 23:12

chore: additional comments

a384132

chore: update docs

3ae0ec7

chore: deprecate static EppoJSClient.initialized

98bd24a

v3.12.0

2d45fe5

felipecsl approved these changes Feb 21, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: buildAndInit for isolated client instances #166

feat: buildAndInit for isolated client instances #166

typotter commented Jan 31, 2025 •

edited

Loading

typotter Jan 31, 2025

felipecsl Feb 3, 2025

typotter Feb 5, 2025

typotter Feb 14, 2025

typotter Jan 31, 2025

felipecsl Feb 3, 2025

typotter Feb 5, 2025

typotter Jan 31, 2025

typotter Jan 31, 2025

sameerank Feb 3, 2025

typotter Feb 4, 2025

typotter commented Feb 14, 2025

aarsilv Feb 16, 2025

aarsilv Feb 16, 2025

typotter Feb 21, 2025

aarsilv Feb 16, 2025

typotter Feb 21, 2025

felipecsl left a comment

felipecsl Feb 18, 2025

typotter Feb 21, 2025

felipecsl Feb 18, 2025

felipecsl Feb 18, 2025

typotter Feb 21, 2025

felipecsl Feb 18, 2025

typotter Feb 21, 2025

felipecsl Feb 18, 2025

felipecsl Feb 18, 2025

felipecsl Feb 18, 2025

typotter Feb 21, 2025 •

edited

Loading

felipecsl Feb 18, 2025

typotter Feb 21, 2025

typotter commented Feb 21, 2025 •

edited

Loading

felipecsl Feb 21, 2025

		@@ -4,6 +4,10 @@

		## EppoJSClient.initialized property

		> Warning: This API is now obsolete.

		@@ -4,6 +4,10 @@

		## getInstance() function

		> Warning: This API is now obsolete.

feat: buildAndInit for isolated client instances #166

Are you sure you want to change the base?

feat: buildAndInit for isolated client instances #166

Conversation

typotter commented Jan 31, 2025 • edited Loading

labels: mergeable

Motivation and Context

Description

How has this been documented?

How has this been tested?

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

typotter commented Feb 14, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

felipecsl left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

typotter Feb 21, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

typotter commented Feb 21, 2025 • edited Loading

Choose a reason for hiding this comment

typotter commented Jan 31, 2025 •

edited

Loading

typotter Feb 21, 2025 •

edited

Loading

typotter commented Feb 21, 2025 •

edited

Loading