feat: Add a module for increased backward compatibility.

Author: kinyoklion

packages/sdk/browser/__tests__/compat/LDClientCompatImpl.test.ts

@@ -0,0 +1,149 @@
+import { jest } from '@jest/globals';
+
+import { LDContext, LDFlagSet, LDLogger } from '@launchdarkly/js-client-sdk-common';
+
+const mockBrowserClient = {
+  identify: jest.fn(),
+  allFlags: jest.fn(),
+  close: jest.fn(),
+  flush: jest.fn(),
+  _emitter: jest.fn(() => ({
+    emit: jest.fn(),
+    on: jest.fn(),
+    off: jest.fn(),
+  })),
+};
+
+jest.unstable_mockModule('../../src/BrowserClient', () => ({
+  __esModule: true,
+  BrowserClient: jest.fn(),
+}));
+
+const { default: LDClientCompatImpl } = await import('../../src/compat/LDClientCompatImpl');
+
+describe('given a LDClientCompatImpl client with mocked browser client', () => {
+  // @ts-ignore
+  let client: LDClientCompatImpl;
+  // let mockBrowserClient: jest.Mocked<BrowserClient>;
+  let mockLogger: LDLogger;
+
+  beforeEach(() => {
+    // mockBrowserClient = {
+    //   identify: jest.fn(),
+    //   allFlags: jest.fn(),
+    //   close: jest.fn(),
+    //   flush: jest.fn(),
+    // } as unknown as jest.Mocked<BrowserClient>;
+
+    // (BrowserClient as jest.MockedClass<typeof BrowserClient>).mockImplementation(
+    //   () => mockBrowserClient,
+    // );
+    mockLogger = {
+      error: jest.fn(),
+      warn: jest.fn(),
+      info: jest.fn(),
+      debug: jest.fn(),
+    };
+    client = new LDClientCompatImpl(
+      'env-key',
+      { kind: 'user', key: 'user-key' },
+      { logger: mockLogger },
+    );
+  });
+
+  it('should return a promise from identify when no callback is provided', async () => {
+    const context: LDContext = { kind: 'user', key: 'new-user' };
+    const mockFlags: LDFlagSet = { flag1: true, flag2: false };
+    // @ts-ignore
+    mockBrowserClient.identify.mockResolvedValue(undefined);
+    mockBrowserClient.allFlags.mockReturnValue(mockFlags);
+
+    const result = await client.identify(context);
+
+    expect(mockBrowserClient.identify).toHaveBeenCalledWith(context, { hash: undefined });
+    expect(result).toEqual(mockFlags);
+  });
+
+  it('should call the callback when provided to identify', (done) => {
+    const context: LDContext = { kind: 'user', key: 'new-user' };
+    const mockFlags: LDFlagSet = { flag1: true, flag2: false };
+    // @ts-ignore
+    mockBrowserClient.identify.mockResolvedValue(undefined);
+    mockBrowserClient.allFlags.mockReturnValue(mockFlags);
+
+    // @ts-ignore
+    client.identify(context, undefined, (err, flags) => {
+      expect(err).toBeNull();
+      expect(flags).toEqual(mockFlags);
+      done();
+    });
+  });
+
+  it('should return a promise from close when no callback is provided', async () => {
+    // @ts-ignore
+    mockBrowserClient.close.mockResolvedValue();
+
+    await expect(client.close()).resolves.toBeUndefined();
+    expect(mockBrowserClient.close).toHaveBeenCalled();
+  });
+
+  it('should call the callback when provided to close', (done) => {
+    // @ts-ignore
+    mockBrowserClient.close.mockResolvedValue();
+
+    client.close(() => {
+      expect(mockBrowserClient.close).toHaveBeenCalled();
+      done();
+    });
+  });
+
+  it('should return a promise from flush when no callback is provided', async () => {
+    // @ts-ignore
+    mockBrowserClient.flush.mockResolvedValue({ result: true });
+
+    await expect(client.flush()).resolves.toBeUndefined();
+    expect(mockBrowserClient.flush).toHaveBeenCalled();
+  });
+
+  it('should call the callback when provided to flush', (done) => {
+    // @ts-ignore
+    mockBrowserClient.flush.mockResolvedValue({ result: true });
+
+    client.flush(() => {
+      expect(mockBrowserClient.flush).toHaveBeenCalled();
+      done();
+    });
+  });
+
+  // it('should resolve immediately if the client is already initialized', async () => {
+  //   mockBrowserClient.waitForInitialization.mockResolvedValue(undefined);
+
+  //   await expect(client.waitForInitialization()).resolves.toBeUndefined();
+  //   expect(mockBrowserClient.waitForInitialization).toHaveBeenCalledWith({ noTimeout: true });
+  // });
+
+  // it('should log a warning when no timeout is specified for waitForInitialization', async () => {
+  //   mockBrowserClient.waitForInitialization.mockResolvedValue(undefined);
+
+  //   await client.waitForInitialization();
+
+  //   expect(mockLogger.warn).toHaveBeenCalledWith(
+  //     expect.stringContaining('The waitForInitialization function was called without a timeout specified.')
+  //   );
+  // });
+
+  // it('should apply a timeout when specified for waitForInitialization', async () => {
+  //   mockBrowserClient.waitForInitialization.mockResolvedValue(undefined);
+
+  //   await client.waitForInitialization(5);
+
+  //   expect(mockBrowserClient.waitForInitialization).toHaveBeenCalledWith({ timeout: 5 });
+  // });
+
+  // it('should reject with a timeout error when initialization takes too long', async () => {
+  //   mockBrowserClient.waitForInitialization.mockRejectedValue(new Error('Timeout'));
+
+  //   await expect(client.waitForInitialization(1)).rejects.toThrow('Timeout');
+  //   expect(mockLogger.error).toHaveBeenCalledWith(expect.stringContaining('waitForInitialization timed out'));
+  // });
+});

packages/sdk/browser/jest.config.js

@@ -5,4 +5,5 @@ export default {
   testEnvironment: 'jest-environment-jsdom',
   testPathIgnorePatterns: ['./dist', './src'],
   testMatch: ['**.test.ts'],
+  setupFiles: ['./setup-jest.js'],
 };

packages/sdk/browser/package.json

@@ -17,9 +17,16 @@
     "sdk"
   ],
   "exports": {
-    "types": "./dist/src/index.d.ts",
-    "require": "./dist/index.cjs.js",
-    "import": "./dist/index.es.js"
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "require": "./dist/index.cjs.js",
+      "import": "./dist/index.es.js"
+    },
+    "./compat": {
+      "types": "./dist/src/compat/index.d.ts",
+      "require": "./dist/compat.cjs.js",
+      "import": "./dist/compat.es.js"
+    }
   },
   "type": "module",
   "files": [

packages/sdk/browser/rollup.config.js

@@ -5,19 +5,17 @@ import terser from '@rollup/plugin-terser';
 import typescript from '@rollup/plugin-typescript';
 import { visualizer } from 'rollup-plugin-visualizer';
 
-const getSharedConfig = (format, file) => ({
-  input: 'src/index.ts',
-  output: [
-    {
-      format: format,
-      sourcemap: true,
-      file: file,
-    },
-  ],
-  onwarn: (warning) => {
-    if (warning.code !== 'CIRCULAR_DEPENDENCY') {
-      console.error(`(!) ${warning.message}`);
-    }
+const getSharedConfig = (format, extension) => ({
+  input: {
+    index: 'src/index.ts',
+    compat: 'src/compat/index.ts'
+  },
+  output:
+  {
+    format: format,
+    sourcemap: true,
+    dir: 'dist',
+    entryFileNames: '[name]' + extension
   },
 });
 
@@ -35,7 +33,7 @@ const terserOpts = {
 
 export default [
   {
-    ...getSharedConfig('es', 'dist/index.es.js'),
+    ...getSharedConfig('es', '.es.js'),
     plugins: [
       typescript({
         module: 'esnext',
@@ -52,7 +50,7 @@ export default [
     ],
   },
   {
-    ...getSharedConfig('cjs', 'dist/index.cjs.js'),
+    ...getSharedConfig('cjs', '.cjs.js'),
     plugins: [typescript(), common(), resolve(), terser(terserOpts), json()],
   },
 ];

packages/sdk/browser/setup-jest.js

@@ -0,0 +1,23 @@
+import { TextEncoder, TextDecoder } from 'node:util';
+import * as crypto from 'crypto';
+
+global.TextEncoder = TextEncoder;
+
+Object.assign(window, { TextDecoder, TextEncoder });
+
+Object.defineProperty(global.self, "crypto", {
+  value: {
+    getRandomValues: (arr) => crypto.randomBytes(arr.length),
+    subtle: {
+      digest: (algorithm, data) => {
+        return new Promise((resolve, reject) =>
+          resolve(
+            crypto.createHash(algorithm.toLowerCase().replace("-", ""))
+              .update(data)
+              .digest()
+          )
+        );
+      },
+    },
+  },
+});

packages/sdk/browser/src/compat/LDClientCompat.ts

@@ -0,0 +1,122 @@
+import { LDContext, LDFlagSet } from '@launchdarkly/js-client-sdk-common';
+import { LDClient as LDCLientBrowser } from '../BrowserClient';
+
+/**
+ * Compatibility interface. This interface extends the base LDCLient interface with functions
+ * that improve backwards compatibility.
+ *
+ * If starting a new project please import the root package instead of `/compat`.
+ *
+ * In the `[email protected]` package a number of functions had the return typings
+ * incorrect. Any function which optionally returned a promise based on a callback had incorrect
+ * typings. Those have been corrected in this implementation.
+ */
+export interface LDClient extends Omit<LDCLientBrowser, 'close' | 'flush' | 'identify'> {
+  /**
+ * Identifies a context to LaunchDarkly.
+ *
+ * Unlike the server-side SDKs, the client-side JavaScript SDKs maintain a current context state,
+ * which is set at initialization time. You only need to call `identify()` if the context has changed
+ * since then.
+ *
+ * Changing the current context also causes all feature flag values to be reloaded. Until that has
+ * finished, calls to {@link variation} will still return flag values for the previous context. You can
+ * use a callback or a Promise to determine when the new flag values are available.
+ *
+ * @param context
+ *   The context properties. Must contain at least the `key` property.
+ * @param hash
+ *   The signed context key if you are using [Secure Mode](https://docs.launchdarkly.com/sdk/features/secure-mode#configuring-secure-mode-in-the-javascript-client-side-sdk).
+ * @param onDone
+ *   A function which will be called as soon as the flag values for the new context are available,
+ *   with two parameters: an error value (if any), and an {@link LDFlagSet} containing the new values
+ *   (which can also be obtained by calling {@link variation}). If the callback is omitted, you will
+ *   receive a Promise instead.
+ * @returns
+ *   If you provided a callback, then nothing. Otherwise, a Promise which resolve once the flag
+ *   values for the new context are available, providing an {@link LDFlagSet} containing the new values
+ *   (which can also be obtained by calling {@link variation}).
+ */
+  identify(
+    context: LDContext,
+    hash?: string,
+    onDone?: (err: Error | null, flags: LDFlagSet | null) => void
+  ): Promise<LDFlagSet> | undefined;
+
+  /**
+   * Returns a Promise that tracks the client's initialization state.
+   *
+   * The Promise will be resolved if the client successfully initializes, or rejected if client
+   * initialization has irrevocably failed (for instance, if it detects that the SDK key is invalid).
+   *
+   * ```
+   *     // using Promise then() and catch() handlers
+   *     client.waitForInitialization(5).then(() => {
+   *         doSomethingWithSuccessfullyInitializedClient();
+   *     }).catch(err => {
+   *         doSomethingForFailedStartup(err);
+   *     });
+   *
+   *     // using async/await
+   *     try {
+   *         await client.waitForInitialization(5);
+   *         doSomethingWithSuccessfullyInitializedClient();
+   *     } catch (err) {
+   *         doSomethingForFailedStartup(err);
+   *     }
+   * ```
+   *
+   * It is important that you handle the rejection case; otherwise it will become an unhandled Promise
+   * rejection, which is a serious error on some platforms. The Promise is not created unless you
+   * request it, so if you never call `waitForInitialization()` then you do not have to worry about
+   * unhandled rejections.
+   *
+   * Note that you can also use event listeners ({@link on}) for the same purpose: the event `"initialized"`
+   * indicates success, and `"failed"` indicates failure.
+   *
+   * @param timeout
+   *  The amount of time, in seconds, to wait for initialization before rejecting the promise.
+   *  Using a large timeout is not recommended. If you use a large timeout and await it, then
+   *  any network delays will cause your application to wait a long time before
+   *  continuing execution.
+   *
+   *  If no timeout is specified, then the returned promise will only be resolved when the client
+   *  successfully initializes or initialization fails.
+   *
+   * @returns
+   *   A Promise that will be resolved if the client initializes successfully, or rejected if it
+   *   fails or the specified timeout elapses.
+   */
+  waitForInitialization(timeout?: number): Promise<void>;
+
+  /**
+   * Shuts down the client and releases its resources, after delivering any pending analytics
+   * events.
+   *
+   * @param onDone
+   *   A function which will be called when the operation completes. If omitted, you
+   *   will receive a Promise instead.
+   *
+   * @returns
+   *   If you provided a callback, then nothing. Otherwise, a Promise which resolves once
+   *   closing is finished. It will never be rejected.
+   */
+  close(onDone?: () => void): Promise<void> | undefined;
+
+  /**
+   * Flushes all pending analytics events.
+   *
+   * Normally, batches of events are delivered in the background at intervals determined by the
+   * `flushInterval` property of {@link LDOptions}. Calling `flush()` triggers an immediate delivery.
+   *
+   * @param onDone
+   *   A function which will be called when the flush completes. If omitted, you
+   *   will receive a Promise instead.
+   *
+   * @returns
+   *   If you provided a callback, then nothing. Otherwise, a Promise which resolves once
+   *   flushing is finished. Note that the Promise will be rejected if the HTTP request
+   *   fails, so be sure to attach a rejection handler to it.
+   */
+  flush(onDone?: () => void): Promise<void> | undefined;
+}