feat: Refine CJS/ESM build configuration for browser SDK.

packages/sdk/browser/contract-tests/entity/src/makeLogger.ts

@@ -2,19 +2,19 @@ import { LDLogger } from '@launchdarkly/js-client-sdk';
 
 export function makeLogger(tag: string): LDLogger {
   return {
-    debug(message, ...args: any[]) {
+    debug(message: any, ...args: any[]) {
       // eslint-disable-next-line no-console
       console.debug(`${new Date().toISOString()} [${tag}]: ${message}`, ...args);
     },
-    info(message, ...args: any[]) {
+    info(message: any, ...args: any[]) {
       // eslint-disable-next-line no-console
       console.info(`${new Date().toISOString()} [${tag}]: ${message}`, ...args);
     },
-    warn(message, ...args: any[]) {
+    warn(message: any, ...args: any[]) {
       // eslint-disable-next-line no-console
       console.warn(`${new Date().toISOString()} [${tag}]: ${message}`, ...args);
     },
-    error(message, ...args: any[]) {
+    error(message: any, ...args: any[]) {
       // eslint-disable-next-line no-console
       console.error(`${new Date().toISOString()} [${tag}]: ${message}`, ...args);
     },

packages/sdk/browser/package.json

@@ -16,18 +16,38 @@
     "feature management",
     "sdk"
   ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
-    "types": "./dist/src/index.d.ts",
-    "require": "./dist/index.cjs.js",
-    "import": "./dist/index.es.js"
+    ".": {
+      "require": {
+        "types": "./dist/index.d.cts",
+        "require": "./dist/index.cjs"
+      },
+      "import": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js"
+      }
+    },
+    "./compat": {
+      "require": {
+        "types": "./dist/compat.d.cts",
+        "require": "./dist/compat.cjs"
+      },
+      "import": {
+        "types": "./dist/compat.d.ts",
+        "import": "./dist/compat.js"
+      }
+    }
   },
-  "type": "module",
   "files": [
     "dist"
   ],
   "scripts": {
     "clean": "rimraf dist",
-    "build": "tsc --noEmit && rollup -c rollup.config.js",
+    "build": "tsup",
     "lint": "eslint . --ext .ts,.tsx",
     "prettier": "prettier --write '**/*.@(js|ts|tsx|json|css)' --ignore-path ../../../.prettierignore",
     "test": "npx jest --runInBand",
@@ -39,11 +59,6 @@
   },
   "devDependencies": {
     "@jest/globals": "^29.7.0",
-    "@rollup/plugin-commonjs": "^25.0.0",
-    "@rollup/plugin-json": "^6.1.0",
-    "@rollup/plugin-node-resolve": "^15.0.2",
-    "@rollup/plugin-terser": "^0.4.3",
-    "@rollup/plugin-typescript": "^11.1.1",
     "@trivago/prettier-plugin-sort-imports": "^4.1.1",
     "@types/jest": "^29.5.11",
     "@typescript-eslint/eslint-plugin": "^6.20.0",
@@ -59,9 +74,8 @@
     "jest-environment-jsdom": "^29.7.0",
     "prettier": "^3.0.0",
     "rimraf": "^5.0.5",
-    "rollup": "^3.23.0",
-    "rollup-plugin-visualizer": "^5.12.0",
     "ts-jest": "^29.1.1",
+    "tsup": "^8.3.5",
     "typedoc": "0.25.0",
     "typescript": "^5.5.3"
   }

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

@@ -0,0 +1,142 @@
+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 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>;
+
+  /**
+   * Returns a Promise that tracks the client's initialization state.
+   *
+   * The returned Promise will be resolved once the client has either successfully initialized
+   * or failed to initialize (e.g. due to an invalid environment key or a server error). It will
+   * never be rejected.
+   *
+   * ```
+   *     // using async/await
+   *     await client.waitUntilReady();
+   *     doSomethingWithClient();
+   * ```
+   *
+   * If you want to distinguish between these success and failure conditions, use
+   * {@link waitForInitialization} instead.
+   *
+   * If you prefer to use event listeners ({@link on}) rather than Promises, you can listen on the
+   * client for a `"ready"` event, which will be fired in either case.
+   *
+   * @returns
+   *   A Promise that will be resolved once the client is no longer trying to initialize.
+   * @deprecated Please use {@link waitForInitialization} instead. This method will always
+   * cause a warning to be logged because it is implemented via waitForInitialization.
+   */
+  waitUntilReady(): 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;
+}