Make the main entry point's API surface area uniform + expose cache and config fetcher implementations + provide extension points to change request/reponse headers

adams85 · adams85 · commit 384e3d660169 · 2025-05-10T12:31:13.000+02:00
diff --git a/extra-checks/ts-compat-check/index.ts b/extra-checks/ts-compat-check/index.ts
@@ -1,4 +1,3 @@
 import "../../lib/esm/browser";
 import "../../lib/esm/chromium-extension";
-import "../../lib/esm/deno";
 import "../../lib/esm/node";
diff --git a/extra-checks/ts-compat-check/shims.d.ts b/extra-checks/ts-compat-check/shims.d.ts
@@ -0,0 +1,14 @@
+declare module "http" {
+    export class IncomingMessage { }
+    export class OutgoingHttpHeaders { }
+}
+
+declare module "@cloudflare/workers-types/2023-03-01" {
+    
+}
+
+declare namespace chrome {
+    export namespace storage {
+        export class LocalStorageArea { }
+    }
+}
diff --git a/src/browser/LocalStorageConfigCache.ts b/src/browser/LocalStorageConfigCache.ts
@@ -3,7 +3,7 @@ import { ExternalConfigCache } from "../ConfigCatCache";
 import type { OptionsBase } from "../ConfigCatClientOptions";
 
 export class LocalStorageConfigCache implements IConfigCatCache {
-  static tryGetFactory(): ((options: OptionsBase) => IConfigCache) | undefined {
+  private static tryGetFactory(): ((options: OptionsBase) => IConfigCache) | undefined {
     const localStorage = getLocalStorage();
     if (localStorage) {
       return options => new ExternalConfigCache(new LocalStorageConfigCache(localStorage), options.logger);
diff --git a/src/browser/XmlHttpRequestConfigFetcher.ts b/src/browser/XmlHttpRequestConfigFetcher.ts
@@ -4,7 +4,7 @@ import type { FetchRequest, IConfigCatConfigFetcher } from "../ConfigFetcher";
 import { FetchError, FetchResponse } from "../ConfigFetcher";
 
 export class XmlHttpRequestConfigFetcher implements IConfigCatConfigFetcher {
-  static getFactory(): (options: OptionsBase) => IConfigCatConfigFetcher {
+  private static getFactory(): (options: OptionsBase) => IConfigCatConfigFetcher {
     return options => {
       const configFetcher = new XmlHttpRequestConfigFetcher();
       configFetcher.logger = options.logger;
@@ -67,13 +67,13 @@ export class XmlHttpRequestConfigFetcher implements IConfigCatConfigFetcher {
     });
   }
 
-  private setRequestHeaders(httpRequest: XMLHttpRequest, headers: ReadonlyArray<[string, string]>) {
+  protected setRequestHeaders(httpRequest: XMLHttpRequest, headers: ReadonlyArray<[string, string]>): void {
     for (const [name, value] of headers) {
       httpRequest.setRequestHeader(name, value);
     }
   }
 
-  private getResponseHeaders(httpRequest: XMLHttpRequest): [string, string][] {
+  protected getResponseHeaders(httpRequest: XMLHttpRequest): [string, string][] {
     const headers: [string, string][] = [];
     extractHeader("ETag", httpRequest, headers);
     extractHeader("CF-RAY", httpRequest, headers);
diff --git a/src/browser/index.root.ts b/src/browser/index.root.ts
@@ -1,4 +1,41 @@
+import type { IConfigCatClient } from "../ConfigCatClient";
+import type { OptionsForPollingMode, PollingMode } from "../ConfigCatClientOptions";
+import { getClient as getClientImpl } from ".";
+
 /* Package public API for browsers or separate packages that implement a ConfigCat SDK. */
 
+/**
+ * Returns an instance of `ConfigCatClient` for the specified SDK Key.
+ * @remarks This method returns a single, shared instance per each distinct SDK Key.
+ * That is, a new client object is created only when there is none available for the specified SDK Key.
+ * Otherwise, the already created instance is returned (in which case the `pollingMode` and `options` arguments are ignored).
+ * So, please keep in mind that when you make multiple calls to this method using the same SDK Key, you may end up with multiple references to the same client object.
+ * @param sdkKey SDK Key to access the ConfigCat config.
+ * @param pollingMode The polling mode to use.
+ * @param options Options for the specified polling mode.
+ */
+export const getClient: <TMode extends PollingMode | undefined>(
+  sdkKey: string, pollingMode?: TMode, options?: OptionsForPollingMode<TMode>
+) => IConfigCatClient = getClientImpl;
+
+export { createConsoleLogger, createFlagOverridesFromMap, disposeAllClients } from "../index.pubternals.core";
+
+export type { INodeAutoPollOptions, INodeLazyLoadingOptions, INodeManualPollOptions } from "../node";
+
+export type { IJSAutoPollOptions, IJSLazyLoadingOptions, IJSManualPollOptions } from ".";
+
+export type { OptionsForPollingMode };
+
+export { LocalStorageConfigCache } from "./LocalStorageConfigCache";
+
+export { IndexedDBConfigCache } from "../shared/IndexedDBConfigCache";
+
+export { XmlHttpRequestConfigFetcher } from "./XmlHttpRequestConfigFetcher";
+
+export { FetchApiConfigFetcher } from "../shared/FetchApiConfigFetcher";
+
+export type { NodeHttpConfigFetcher } from "../node/NodeHttpConfigFetcher";
+
 export * as Internals from "../index.pubternals";
-export * from ".";
+
+export * from "..";
diff --git a/src/browser/index.ts b/src/browser/index.ts
@@ -31,9 +31,9 @@ export function getClient<TMode extends PollingMode | undefined>(sdkKey: string,
     defaultCacheFactory: typeof localStorage !== "undefined"
       // NOTE: The IndexedDB API is asynchronous, so it's not possible to check here if it actually works. For this reason,
       // we'd rather not fall back to IndexedDB if LocalStorage doesn't work. (In that case, IndexedDB is unlikely to work anyway.)
-      ? LocalStorageConfigCache.tryGetFactory()
-      : IndexedDBConfigCache.tryGetFactory(),
-    configFetcherFactory: XmlHttpRequestConfigFetcher.getFactory(),
+      ? LocalStorageConfigCache["tryGetFactory"]()
+      : IndexedDBConfigCache["tryGetFactory"](),
+    configFetcherFactory: XmlHttpRequestConfigFetcher["getFactory"](),
   });
 }
 
@@ -60,4 +60,12 @@ export type OptionsForPollingMode<TMode extends PollingMode | undefined> =
     TMode extends undefined ? IJSAutoPollOptions :
     never;
 
+export { LocalStorageConfigCache };
+
+export { IndexedDBConfigCache };
+
+export { XmlHttpRequestConfigFetcher };
+
+export { FetchApiConfigFetcher } from "../shared/FetchApiConfigFetcher";
+
 export * from "..";
diff --git a/src/bun/index.ts b/src/bun/index.ts
@@ -24,7 +24,7 @@ export function getClient<TMode extends PollingMode | undefined>(sdkKey: string,
       sdkType: "ConfigCat-UnifiedJS-Bun",
       sdkVersion: CONFIGCAT_SDK_VERSION,
       eventEmitterFactory: () => new EventEmitter(),
-      configFetcherFactory: NodeHttpConfigFetcher.getFactory(),
+      configFetcherFactory: NodeHttpConfigFetcher["getFactory"](),
     });
 }
 
@@ -49,4 +49,8 @@ export type OptionsForPollingMode<TMode extends PollingMode | undefined> =
   TMode extends undefined ? IBunAutoPollOptions :
   never;
 
+export { NodeHttpConfigFetcher };
+
+export { FetchApiConfigFetcher } from "../shared/FetchApiConfigFetcher";
+
 export * from "..";
diff --git a/src/chromium-extension/ChromeLocalStorageConfigCache.ts b/src/chromium-extension/ChromeLocalStorageConfigCache.ts
@@ -5,7 +5,7 @@ import type { OptionsBase } from "../ConfigCatClientOptions";
 /* eslint-disable @typescript-eslint/no-deprecated */
 
 export class ChromeLocalStorageConfigCache implements IConfigCatCache {
-  static tryGetFactory(): ((options: OptionsBase) => IConfigCache) | undefined {
+  private static tryGetFactory(): ((options: OptionsBase) => IConfigCache) | undefined {
     const localStorage = getChromeLocalStorage();
     if (localStorage) {
       return options => new ExternalConfigCache(new ChromeLocalStorageConfigCache(localStorage), options.logger);
diff --git a/src/chromium-extension/index.ts b/src/chromium-extension/index.ts
@@ -28,8 +28,8 @@ export function getClient<TMode extends PollingMode | undefined>(sdkKey: string,
     sdkType: "ConfigCat-UnifiedJS-ChromiumExtension",
     sdkVersion: CONFIGCAT_SDK_VERSION,
     eventEmitterFactory: () => new DefaultEventEmitter(),
-    defaultCacheFactory: ChromeLocalStorageConfigCache.tryGetFactory() ?? IndexedDBConfigCache.tryGetFactory(),
-    configFetcherFactory: FetchApiConfigFetcher.getFactory(),
+    defaultCacheFactory: ChromeLocalStorageConfigCache["tryGetFactory"]() ?? IndexedDBConfigCache["tryGetFactory"](),
+    configFetcherFactory: FetchApiConfigFetcher["getFactory"](),
   });
 }
 
@@ -56,4 +56,10 @@ export type OptionsForPollingMode<TMode extends PollingMode | undefined> =
     TMode extends undefined ? IJSAutoPollOptions :
     never;
 
+export { ChromeLocalStorageConfigCache };
+
+export { IndexedDBConfigCache };
+
+export { FetchApiConfigFetcher };
+
 export * from "..";
diff --git a/src/cloudflare-worker/CloudflareConfigCache.ts b/src/cloudflare-worker/CloudflareConfigCache.ts
@@ -11,7 +11,7 @@ declare const caches: typeof cloudflare.caches;
 declare const Response: typeof cloudflare.Response;
 
 export class CloudflareConfigCache implements IConfigCatCache {
-  static tryGetFactory(): ((options: OptionsBase) => IConfigCache) | undefined {
+  private static tryGetFactory(): ((options: OptionsBase) => IConfigCache) | undefined {
     const cache = getCloudflareCache();
     if (cache) {
       return options => new ExternalConfigCache(new CloudflareConfigCache(cache), options.logger);
diff --git a/src/cloudflare-worker/index.ts b/src/cloudflare-worker/index.ts
@@ -29,8 +29,8 @@ export function getClient<TMode extends PollingMode | undefined>(sdkKey: string,
     sdkType: "ConfigCat-UnifiedJS-CloudflareWorker",
     sdkVersion: CONFIGCAT_SDK_VERSION,
     eventEmitterFactory: () => new DefaultEventEmitter(),
-    defaultCacheFactory: CloudflareConfigCache.tryGetFactory(),
-    configFetcherFactory: FetchApiConfigFetcher.getFactory(),
+    defaultCacheFactory: CloudflareConfigCache["tryGetFactory"](),
+    configFetcherFactory: FetchApiConfigFetcher["getFactory"](),
   });
 }
 
@@ -106,4 +106,8 @@ export type OptionsForPollingMode<TMode extends PollingMode | undefined> =
     TMode extends undefined ? IJSAutoPollOptions :
     never;
 
+export { CloudflareConfigCache };
+
+export { FetchApiConfigFetcher };
+
 export * from "..";
diff --git a/src/deno/index.ts b/src/deno/index.ts
@@ -24,7 +24,7 @@ export function getClient<TMode extends PollingMode | undefined>(sdkKey: string,
       sdkType: "ConfigCat-UnifiedJS-Deno",
       sdkVersion: CONFIGCAT_SDK_VERSION,
       eventEmitterFactory: () => new DefaultEventEmitter(),
-      configFetcherFactory: FetchApiConfigFetcher.getFactory(),
+      configFetcherFactory: FetchApiConfigFetcher["getFactory"](),
     });
 }
 
@@ -49,4 +49,6 @@ export type OptionsForPollingMode<TMode extends PollingMode | undefined> =
   TMode extends undefined ? IDenoAutoPollOptions :
   never;
 
+export { FetchApiConfigFetcher };
+
 export * from "..";
diff --git a/src/index.pubternals.ts b/src/index.pubternals.ts
@@ -23,11 +23,3 @@ export { FetchResult, FetchStatus } from "./ConfigFetcher";
 export type { IEventEmitter, IEventProvider } from "./EventEmitter";
 
 export { DefaultEventEmitter } from "./DefaultEventEmitter";
-
-export { LocalStorageConfigCache } from "./browser/LocalStorageConfigCache";
-
-export { IndexedDBConfigCache } from "./shared/IndexedDBConfigCache";
-
-export { XmlHttpRequestConfigFetcher } from "./browser/XmlHttpRequestConfigFetcher";
-
-export { FetchApiConfigFetcher } from "./shared/FetchApiConfigFetcher";
diff --git a/src/node/NodeHttpConfigFetcher.ts b/src/node/NodeHttpConfigFetcher.ts
@@ -14,7 +14,7 @@ export interface INodeHttpConfigFetcherOptions {
 }
 
 export class NodeHttpConfigFetcher implements IConfigCatConfigFetcher {
-  static getFactory(fetcherOptions?: INodeHttpConfigFetcherOptions): (options: OptionsBase) => IConfigCatConfigFetcher {
+  private static getFactory(fetcherOptions?: INodeHttpConfigFetcherOptions): (options: OptionsBase) => IConfigCatConfigFetcher {
     return options => {
       const configFetcher = new NodeHttpConfigFetcher(fetcherOptions);
       configFetcher.logger = options.logger;
@@ -126,7 +126,7 @@ export class NodeHttpConfigFetcher implements IConfigCatConfigFetcher {
     });
   }
 
-  private setRequestHeaders(requestOptions: { headers?: http.OutgoingHttpHeaders }, headers: ReadonlyArray<[string, string]>) {
+  protected setRequestHeaders(requestOptions: { headers?: http.OutgoingHttpHeaders }, headers: ReadonlyArray<[string, string]>): void {
     if (headers.length) {
       const currentHeaders = requestOptions.headers ??= {};
       for (const [name, value] of headers) {
@@ -142,7 +142,7 @@ export class NodeHttpConfigFetcher implements IConfigCatConfigFetcher {
     }
   }
 
-  private getResponseHeaders(httpResponse: http.IncomingMessage): [string, string][] {
+  protected getResponseHeaders(httpResponse: http.IncomingMessage): [string, string][] {
     const headers: [string, string][] = [];
     extractHeader("etag", httpResponse, headers);
     extractHeader("cf-ray", httpResponse, headers);
diff --git a/src/node/index.root.ts b/src/node/index.root.ts
@@ -1,4 +1,41 @@
+import type { IConfigCatClient } from "../ConfigCatClient";
+import type { OptionsForPollingMode, PollingMode } from "../ConfigCatClientOptions";
+import { getClient as getClientImpl } from ".";
+
 /* Package public API for Node.js or separate packages that implement a ConfigCat SDK. */
 
+/**
+ * Returns an instance of `ConfigCatClient` for the specified SDK Key.
+ * @remarks This method returns a single, shared instance per each distinct SDK Key.
+ * That is, a new client object is created only when there is none available for the specified SDK Key.
+ * Otherwise, the already created instance is returned (in which case the `pollingMode` and `options` arguments are ignored).
+ * So, please keep in mind that when you make multiple calls to this method using the same SDK Key, you may end up with multiple references to the same client object.
+ * @param sdkKey SDK Key to access the ConfigCat config.
+ * @param pollingMode The polling mode to use.
+ * @param options Options for the specified polling mode.
+ */
+export const getClient: <TMode extends PollingMode | undefined>(
+  sdkKey: string, pollingMode?: TMode, options?: OptionsForPollingMode<TMode>
+) => IConfigCatClient = getClientImpl;
+
+export { createConsoleLogger, createFlagOverridesFromMap, disposeAllClients } from "../index.pubternals.core";
+
+export type { INodeAutoPollOptions, INodeLazyLoadingOptions, INodeManualPollOptions } from ".";
+
+export type { IJSAutoPollOptions, IJSLazyLoadingOptions, IJSManualPollOptions } from "../browser";
+
+export type { OptionsForPollingMode };
+
+export { LocalStorageConfigCache } from "../browser/LocalStorageConfigCache";
+
+export { IndexedDBConfigCache } from "../shared/IndexedDBConfigCache";
+
+export { XmlHttpRequestConfigFetcher } from "../browser/XmlHttpRequestConfigFetcher";
+
+export { FetchApiConfigFetcher } from "../shared/FetchApiConfigFetcher";
+
+export { NodeHttpConfigFetcher } from "./NodeHttpConfigFetcher";
+
 export * as Internals from "../index.pubternals";
-export * from ".";
+
+export * from "..";
diff --git a/src/node/index.ts b/src/node/index.ts
@@ -25,7 +25,7 @@ export function getClient<TMode extends PollingMode | undefined>(sdkKey: string,
       sdkType: "ConfigCat-UnifiedJS-Node",
       sdkVersion: CONFIGCAT_SDK_VERSION,
       eventEmitterFactory: () => new EventEmitter(),
-      configFetcherFactory: NodeHttpConfigFetcher.getFactory(options),
+      configFetcherFactory: NodeHttpConfigFetcher["getFactory"](options),
     });
 }
 
@@ -50,4 +50,6 @@ export type OptionsForPollingMode<TMode extends PollingMode | undefined> =
   TMode extends undefined ? INodeAutoPollOptions :
   never;
 
+export { NodeHttpConfigFetcher };
+
 export * from "..";
diff --git a/src/shared/FetchApiConfigFetcher.ts b/src/shared/FetchApiConfigFetcher.ts
@@ -4,7 +4,7 @@ import type { FetchRequest, IConfigCatConfigFetcher } from "../ConfigFetcher";
 import { FetchError, FetchResponse } from "../ConfigFetcher";
 
 export class FetchApiConfigFetcher implements IConfigCatConfigFetcher {
-  static getFactory(): (options: OptionsBase) => IConfigCatConfigFetcher {
+  private static getFactory(): (options: OptionsBase) => IConfigCatConfigFetcher {
     return options => {
       const configFetcher = new FetchApiConfigFetcher();
       configFetcher.logger = options.logger;
@@ -64,13 +64,13 @@ export class FetchApiConfigFetcher implements IConfigCatConfigFetcher {
     }
   }
 
-  private setRequestHeaders(requestInit: { headers?: [string, string][] }, headers: ReadonlyArray<[string, string]>) {
+  protected setRequestHeaders(requestInit: { headers?: [string, string][] }, headers: ReadonlyArray<[string, string]>): void {
     if (headers.length) {
       (requestInit.headers ??= []).push(...headers);
     }
   }
 
-  private getResponseHeaders(httpResponse: Response): [string, string][] {
+  protected getResponseHeaders(httpResponse: Response): [string, string][] {
     const headers: [string, string][] = [];
     extractHeader("ETag", httpResponse, headers);
     extractHeader("CF-RAY", httpResponse, headers);
diff --git a/src/shared/IndexedDBConfigCache.ts b/src/shared/IndexedDBConfigCache.ts
@@ -7,7 +7,7 @@ const OBJECT_STORE_NAME = "configCache";
 type DBConnectionFactory = () => Promise<IDBDatabase>;
 
 export class IndexedDBConfigCache implements IConfigCatCache {
-  static tryGetFactory(): ((options: OptionsBase) => IConfigCache) | undefined {
+  private static tryGetFactory(): ((options: OptionsBase) => IConfigCache) | undefined {
     const dbConnectionFactory = getDBConnectionFactory();
     if (dbConnectionFactory) {
       return options => new ExternalConfigCache(new IndexedDBConfigCache(dbConnectionFactory), options.logger);
diff --git a/test/browser/index.ts b/test/browser/index.ts
@@ -35,7 +35,7 @@ class BrowserPlatform extends PlatformAbstractions<IJSAutoPollOptions, IJSManual
     });
   }
 
-  createConfigFetcher(options: OptionsBase, platformOptions?: IJSOptions) { return XmlHttpRequestConfigFetcher.getFactory()(options); }
+  createConfigFetcher(options: OptionsBase, platformOptions?: IJSOptions) { return XmlHttpRequestConfigFetcher["getFactory"]()(options); }
 
   createKernel(setupKernel?: (kernel: IConfigCatKernel) => IConfigCatKernel, options?: IJSOptions) {
     const kernel: IConfigCatKernel = {
@@ -45,7 +45,7 @@ class BrowserPlatform extends PlatformAbstractions<IJSAutoPollOptions, IJSManual
       configFetcherFactory: o => this.createConfigFetcher(o, options),
     };
     setupKernel ??= kernel => {
-      kernel.defaultCacheFactory = LocalStorageConfigCache.tryGetFactory();
+      kernel.defaultCacheFactory = LocalStorageConfigCache["tryGetFactory"]();
       return kernel;
     };
     return setupKernel(kernel);
diff --git a/test/bun/index.ts b/test/bun/index.ts
@@ -29,7 +29,7 @@ class BunPlatform extends PlatformAbstractions<IBunAutoPollOptions, IBunManualPo
 
   readFileUtf8(path: string) { return fs.readFileSync(path, "utf8"); }
 
-  createConfigFetcher(options: OptionsBase, platformOptions?: IBunOptions) { return NodeHttpConfigFetcher.getFactory()(options); }
+  createConfigFetcher(options: OptionsBase, platformOptions?: IBunOptions) { return NodeHttpConfigFetcher["getFactory"]()(options); }
 
   createKernel(setupKernel?: (kernel: IConfigCatKernel) => IConfigCatKernel, options?: IBunOptions) {
     const kernel: IConfigCatKernel = {
diff --git a/test/chromium-extension/index.ts b/test/chromium-extension/index.ts
@@ -23,7 +23,7 @@ class ChromiumExtensionPlatform extends PlatformAbstractions<IJSAutoPollOptions,
     }
   }
 
-  createConfigFetcher(options: OptionsBase, platformOptions?: IJSOptions) { return FetchApiConfigFetcher.getFactory()(options); }
+  createConfigFetcher(options: OptionsBase, platformOptions?: IJSOptions) { return FetchApiConfigFetcher["getFactory"]()(options); }
 
   createKernel(setupKernel?: (kernel: IConfigCatKernel) => IConfigCatKernel, options?: IJSOptions) {
     const kernel: IConfigCatKernel = {
@@ -33,7 +33,7 @@ class ChromiumExtensionPlatform extends PlatformAbstractions<IJSAutoPollOptions,
       configFetcherFactory: o => this.createConfigFetcher(o, options),
     };
     setupKernel ??= kernel => {
-      kernel.defaultCacheFactory = ChromeLocalStorageConfigCache.tryGetFactory();
+      kernel.defaultCacheFactory = ChromeLocalStorageConfigCache["tryGetFactory"]();
       return kernel;
     };
     return setupKernel(kernel);
diff --git a/test/cloudflare-worker/index.ts b/test/cloudflare-worker/index.ts
diff --git a/test/deno/index.ts b/test/deno/index.ts
diff --git a/test/node/index.ts b/test/node/index.ts
diff --git a/tsconfig.mocha.node.json b/tsconfig.mocha.node.json
