flagsmith-nodejs 5.1.0 → 6.0.0

package/build/esm/sdk/index.js

@@ -6,7 +6,7 @@ import { ANALYTICS_ENDPOINT, AnalyticsProcessor } from './analytics.js';
 import { FlagsmithAPIError } from './errors.js';
 import { Flags } from './models.js';
 import { EnvironmentDataPollingManager } from './polling_manager.js';
-import { generateIdentitiesData, retryFetch } from './utils.js';
+import { Deferred, generateIdentitiesData, retryFetch } from './utils.js';
 import { getIdentitySegments } from '../flagsmith-engine/segments/evaluators.js';
 import { pino } from 'pino';
 export { AnalyticsProcessor } from './analytics.js';
@@ -15,6 +15,30 @@ export { DefaultFlag, Flags } from './models.js';
 export { EnvironmentDataPollingManager } from './polling_manager.js';
 const DEFAULT_API_URL = 'https://edge.api.flagsmith.com/api/v1/';
 const DEFAULT_REQUEST_TIMEOUT_SECONDS = 10;
+/**
+ * A client for evaluating Flagsmith feature flags.
+ *
+ * Flags are evaluated remotely by the Flagsmith API over HTTP by default.
+ * To evaluate flags locally, create the client using {@link FlagsmithConfig.enableLocalEvaluation} and a server-side SDK key.
+ *
+ * @example
+ * import { Flagsmith, Flags, DefaultFlag } from 'flagsmith-nodejs'
+ *
+ * const flagsmith = new Flagsmith({
+ *   environmentKey: 'your_sdk_key',
+ *   defaultFlagHandler: (flagKey: string) => { new DefaultFlag(...) },
+ * });
+ *
+ * // Fetch the current environment flags
+ * const environmentFlags: Flags = flagsmith.getEnvironmentFlags()
+ * const isFooEnabled: boolean = environmentFlags.isFeatureEnabled('foo')
+ *
+ * // Evaluate flags for any identity
+ * const identityFlags: Flags = flagsmith.getIdentityFlags('my_user_123', {'vip': true})
+ * const bannerVariation: string = identityFlags.getFeatureValue('banner_flag')
+ *
+ * @see FlagsmithConfig
+*/
 export class Flagsmith {
     environmentKey = undefined;
     apiUrl = undefined;
@@ -40,61 +64,30 @@ export class Flagsmith {
     analyticsProcessor;
     logger;
     customFetch;
+    requestRetryDelayMilliseconds;
     /**
-     * A Flagsmith client.
+     * Creates a new {@link Flagsmith} client.
      *
-     * Provides an interface for interacting with the Flagsmith http API.
-     * Basic Usage::
-     *
-     * import flagsmith from Flagsmith
-     * const flagsmith = new Flagsmith({environmentKey: '<your API key>'});
-     * const environmentFlags = flagsmith.getEnvironmentFlags();
-     * const featureEnabled = environmentFlags.isFeatureEnabled('foo');
-     * const identityFlags = flagsmith.getIdentityFlags('identifier', {'foo': 'bar'});
-     * const featureEnabledForIdentity = identityFlags.isFeatureEnabled("foo")
-     *
-     *  @param {string} data.environmentKey: The environment key obtained from Flagsmith interface
-     *      Required unless offlineMode is True.
-        @param {string} data.apiUrl: Override the URL of the Flagsmith API to communicate with
-        @param  data.customHeaders: Additional headers to add to requests made to the
-            Flagsmith API
-        @param {number} data.requestTimeoutSeconds: Number of seconds to wait for a request to
-            complete before terminating the request
-        @param {boolean} data.enableLocalEvaluation: Enables local evaluation of flags
-        @param {number} data.environmentRefreshIntervalSeconds: If using local evaluation,
-            specify the interval period between refreshes of local environment data
-        @param {number} data.retries: a urllib3.Retry object to use on all http requests to the
-            Flagsmith API
-        @param {boolean} data.enableAnalytics: if enabled, sends additional requests to the Flagsmith
-            API to power flag analytics charts
-        @param data.defaultFlagHandler: callable which will be used in the case where
-            flags cannot be retrieved from the API or a non-existent feature is
-            requested
-        @param data.logger: an instance of the pino Logger class to use for logging
-        @param {boolean} data.offlineMode: sets the client into offline mode. Relies on offlineHandler for
-            evaluating flags.
-        @param {BaseOfflineHandler} data.offlineHandler: provide a handler for offline logic. Used to get environment
-            document from another source when in offlineMode. Works in place of
-            defaultFlagHandler if offlineMode is not set and using remote evaluation.
-    */
-    constructor(data = {}) {
-        // if (!data.offlineMode && !data.environmentKey) {
-        //     throw new Error('ValueError: environmentKey is required.');
-        // }
+     * If using local evaluation, the environment will be fetched lazily when needed by any method. Polling the
+     * environment for updates will start after {@link environmentRefreshIntervalSeconds} once the client is created.
+     * @param data The {@link FlagsmithConfig} options for this client.
+     */
+    constructor(data) {
         this.agent = data.agent;
         this.customFetch = data.fetch ?? fetch;
         this.environmentKey = data.environmentKey;
-        this.apiUrl = data.apiUrl || this.apiUrl;
+        this.apiUrl = data.apiUrl || DEFAULT_API_URL;
         this.customHeaders = data.customHeaders;
         this.requestTimeoutMs =
             1000 * (data.requestTimeoutSeconds ?? DEFAULT_REQUEST_TIMEOUT_SECONDS);
+        this.requestRetryDelayMilliseconds = data.requestRetryDelayMilliseconds ?? 1000;
         this.enableLocalEvaluation = data.enableLocalEvaluation;
         this.environmentRefreshIntervalSeconds =
             data.environmentRefreshIntervalSeconds || this.environmentRefreshIntervalSeconds;
         this.retries = data.retries;
         this.enableAnalytics = data.enableAnalytics || false;
         this.defaultFlagHandler = data.defaultFlagHandler;
-        this.onEnvironmentChange = data.onEnvironmentChange;
+        this.onEnvironmentChange = (error, result) => data.onEnvironmentChange?.(error, result);
         this.logger = data.logger || pino();
         this.offlineMode = data.offlineMode || false;
         this.offlineHandler = data.offlineHandler;
@@ -105,9 +98,6 @@ export class Flagsmith {
         else if (this.defaultFlagHandler && this.offlineHandler) {
             throw new Error('ValueError: Cannot use both defaultFlagHandler and offlineHandler.');
         }
-        if (this.offlineHandler) {
-            this.environment = this.offlineHandler.getEnvironment();
-        }
         if (!!data.cache) {
             this.cache = data.cache;
         }
@@ -123,11 +113,12 @@ export class Flagsmith {
             this.environmentUrl = `${this.apiUrl}environment-document/`;
             if (this.enableLocalEvaluation) {
                 if (!this.environmentKey.startsWith('ser.')) {
-                    console.error('In order to use local evaluation, please generate a server key in the environment settings page.');
+                    throw new Error('Using local evaluation requires a server-side environment key');
+                }
+                if (this.environmentRefreshIntervalSeconds > 0) {
+                    this.environmentDataPollingManager = new EnvironmentDataPollingManager(this, this.environmentRefreshIntervalSeconds, this.logger);
+                    this.environmentDataPollingManager.start();
                 }
-                this.environmentDataPollingManager = new EnvironmentDataPollingManager(this, this.environmentRefreshIntervalSeconds);
-                this.environmentDataPollingManager.start();
-                this.updateEnvironment();
             }
             if (data.enableAnalytics) {
                 this.analyticsProcessor = new AnalyticsProcessor({
@@ -149,15 +140,22 @@ export class Flagsmith {
         if (!!cachedItem) {
             return cachedItem;
         }
-        if (this.enableLocalEvaluation && !this.offlineMode) {
-            return new Promise((resolve, reject) => this.environmentPromise.then(() => {
-                resolve(this.getEnvironmentFlagsFromDocument());
-            }).catch(e => reject(e)));
+        try {
+            if (this.enableLocalEvaluation || this.offlineMode) {
+                return await this.getEnvironmentFlagsFromDocument();
+            }
+            return await this.getEnvironmentFlagsFromApi();
         }
-        if (this.environment) {
-            return this.getEnvironmentFlagsFromDocument();
+        catch (error) {
+            if (!this.defaultFlagHandler) {
+                throw new Error('getEnvironmentFlags failed and no default flag handler was provided', { cause: error });
+            }
+            this.logger.error(error, 'getEnvironmentFlags failed');
+            return new Flags({
+                flags: {},
+                defaultFlagHandler: this.defaultFlagHandler
+            });
         }
-        return this.getEnvironmentFlagsFromApi();
     }
     /**
      * Get all the flags for the current environment for a given identity. Will also
@@ -179,15 +177,22 @@ export class Flagsmith {
             return cachedItem;
         }
         traits = traits || {};
-        if (this.enableLocalEvaluation) {
-            return new Promise((resolve, reject) => this.environmentPromise.then(() => {
-                resolve(this.getIdentityFlagsFromDocument(identifier, traits || {}));
-            }).catch(e => reject(e)));
+        try {
+            if (this.enableLocalEvaluation || this.offlineMode) {
+                return await this.getIdentityFlagsFromDocument(identifier, traits || {});
+            }
+            return await this.getIdentityFlagsFromApi(identifier, traits, transient);
         }
-        if (this.offlineMode) {
-            return this.getIdentityFlagsFromDocument(identifier, traits || {});
+        catch (error) {
+            if (!this.defaultFlagHandler) {
+                throw new Error('getIdentityFlags failed and no default flag handler was provided', { cause: error });
+            }
+            this.logger.error(error, 'getIdentityFlags failed');
+            return new Flags({
+                flags: {},
+                defaultFlagHandler: this.defaultFlagHandler
+            });
         }
-        return this.getIdentityFlagsFromApi(identifier, traits, transient);
     }
     /**
      * Get the segments for the current environment for a given identity. Will also
@@ -200,57 +205,59 @@ export class Flagsmith {
             Flagsmith, e.g. {"num_orders": 10}
      * @returns Segments that the given identity belongs to.
      */
-    getIdentitySegments(identifier, traits) {
+    async getIdentitySegments(identifier, traits) {
         if (!identifier) {
             throw new Error('`identifier` argument is missing or invalid.');
         }
+        if (!this.enableLocalEvaluation) {
+            this.logger.error('This function is only permitted with local evaluation.');
+            return Promise.resolve([]);
+        }
         traits = traits || {};
-        if (this.enableLocalEvaluation) {
-            return new Promise((resolve, reject) => {
-                return this.environmentPromise.then(() => {
-                    const identityModel = this.getIdentityModel(identifier, Object.keys(traits || {}).map(key => ({
-                        key,
-                        value: traits?.[key]
-                    })));
-                    const segments = getIdentitySegments(this.environment, identityModel);
-                    return resolve(segments);
-                }).catch(e => reject(e));
-            });
+        const environment = await this.getEnvironment();
+        const identityModel = this.getIdentityModel(environment, identifier, Object.keys(traits || {}).map(key => ({
+            key,
+            value: traits?.[key]
+        })));
+        return getIdentitySegments(environment, identityModel);
+    }
+    async fetchEnvironment() {
+        const deferred = new Deferred();
+        this.environmentPromise = deferred.promise;
+        try {
+            const environment = await this.getEnvironmentFromApi();
+            this.environment = environment;
+            if (environment.identityOverrides?.length) {
+                this.identitiesWithOverridesByIdentifier = new Map(environment.identityOverrides.map(identity => [identity.identifier, identity]));
+            }
+            deferred.resolve(environment);
+            return deferred.promise;
+        }
+        catch (error) {
+            deferred.reject(error);
+            return deferred.promise;
+        }
+        finally {
+            this.environmentPromise = undefined;
         }
-        console.error('This function is only permitted with local evaluation.');
-        return Promise.resolve([]);
     }
     /**
-     * Updates the environment state for local flag evaluation.
-     * Sets a local promise to prevent race conditions in getIdentityFlags / getIdentitySegments.
-     * You only need to call this if you wish to bypass environmentRefreshIntervalSeconds.
+     * Fetch the latest environment state from the Flagsmith API to use for local flag evaluation.
+     *
+     * If the environment is currently being fetched, calling this method will not cause additional fetches.
      */
     async updateEnvironment() {
         try {
-            const request = this.getEnvironmentFromApi();
-            if (!this.environmentPromise) {
-                this.environmentPromise = request.then(res => {
-                    this.environment = res;
-                });
+            if (this.environmentPromise) {
                 await this.environmentPromise;
+                return;
             }
-            else {
-                this.environment = await request;
-            }
-            if (this.environment.identityOverrides?.length) {
-                this.identitiesWithOverridesByIdentifier = new Map(this.environment.identityOverrides.map(identity => [
-                    identity.identifier,
-                    identity
-                ]));
-            }
-            if (this.onEnvironmentChange) {
-                this.onEnvironmentChange(null, this.environment);
-            }
+            const environment = await this.fetchEnvironment();
+            this.onEnvironmentChange(null, environment);
         }
         catch (e) {
-            if (this.onEnvironmentChange) {
-                this.onEnvironmentChange(e, this.environment);
-            }
+            this.logger.error(e, 'updateEnvironment failed');
+            this.onEnvironmentChange(e);
         }
     }
     async close() {
@@ -271,7 +278,7 @@ export class Flagsmith {
             method: method,
             body: JSON.stringify(body),
             headers: headers
-        }, this.retries, this.requestTimeoutMs, this.customFetch);
+        }, this.retries, this.requestTimeoutMs, this.requestRetryDelayMilliseconds, this.customFetch);
         if (data.status !== 200) {
             throw new FlagsmithAPIError(`Invalid request made to Flagsmith API. Response status code: ${data.status}`);
         }
@@ -281,6 +288,23 @@ export class Flagsmith {
      * This promise ensures that the environment is retrieved before attempting to locally evaluate.
      */
     environmentPromise;
+    /**
+     * Returns the current environment, fetching it from the API if needed.
+     *
+     * Calling this method concurrently while the environment is being fetched will not cause additional requests.
+     */
+    async getEnvironment() {
+        if (this.offlineHandler) {
+            return this.offlineHandler.getEnvironment();
+        }
+        if (this.environment) {
+            return this.environment;
+        }
+        if (!this.environmentPromise) {
+            this.environmentPromise = this.fetchEnvironment();
+        }
+        return this.environmentPromise;
+    }
     async getEnvironmentFromApi() {
         if (!this.environmentUrl) {
             throw new Error('`apiUrl` argument is missing or invalid.');
@@ -289,8 +313,9 @@ export class Flagsmith {
         return buildEnvironmentModel(environment_data);
     }
     async getEnvironmentFlagsFromDocument() {
+        const environment = await this.getEnvironment();
         const flags = Flags.fromFeatureStateModels({
-            featureStates: getEnvironmentFeatureStates(this.environment),
+            featureStates: getEnvironmentFeatureStates(environment),
             analyticsProcessor: this.analyticsProcessor,
             defaultFlagHandler: this.defaultFlagHandler
         });
@@ -300,11 +325,12 @@ export class Flagsmith {
         return flags;
     }
     async getIdentityFlagsFromDocument(identifier, traits) {
-        const identityModel = this.getIdentityModel(identifier, Object.keys(traits).map(key => ({
+        const environment = await this.getEnvironment();
+        const identityModel = this.getIdentityModel(environment, identifier, Object.keys(traits).map(key => ({
             key,
             value: traits[key]
         })));
-        const featureStates = getIdentityFeatureStates(this.environment, identityModel);
+        const featureStates = getIdentityFeatureStates(environment, identityModel);
         const flags = Flags.fromFeatureStateModels({
             featureStates: featureStates,
             analyticsProcessor: this.analyticsProcessor,
@@ -320,69 +346,41 @@ export class Flagsmith {
         if (!this.environmentFlagsUrl) {
             throw new Error('`apiUrl` argument is missing or invalid.');
         }
-        try {
-            const apiFlags = await this.getJSONResponse(this.environmentFlagsUrl, 'GET');
-            const flags = Flags.fromAPIFlags({
-                apiFlags: apiFlags,
-                analyticsProcessor: this.analyticsProcessor,
-                defaultFlagHandler: this.defaultFlagHandler
-            });
-            if (!!this.cache) {
-                await this.cache.set('flags', flags);
-            }
-            return flags;
-        }
-        catch (e) {
-            if (this.offlineHandler) {
-                return this.getEnvironmentFlagsFromDocument();
-            }
-            if (this.defaultFlagHandler) {
-                return new Flags({
-                    flags: {},
-                    defaultFlagHandler: this.defaultFlagHandler
-                });
-            }
-            throw e;
+        const apiFlags = await this.getJSONResponse(this.environmentFlagsUrl, 'GET');
+        const flags = Flags.fromAPIFlags({
+            apiFlags: apiFlags,
+            analyticsProcessor: this.analyticsProcessor,
+            defaultFlagHandler: this.defaultFlagHandler
+        });
+        if (!!this.cache) {
+            await this.cache.set('flags', flags);
         }
+        return flags;
     }
     async getIdentityFlagsFromApi(identifier, traits, transient = false) {
         if (!this.identitiesUrl) {
             throw new Error('`apiUrl` argument is missing or invalid.');
         }
-        try {
-            const data = generateIdentitiesData(identifier, traits, transient);
-            const jsonResponse = await this.getJSONResponse(this.identitiesUrl, 'POST', data);
-            const flags = Flags.fromAPIFlags({
-                apiFlags: jsonResponse['flags'],
-                analyticsProcessor: this.analyticsProcessor,
-                defaultFlagHandler: this.defaultFlagHandler
-            });
-            if (!!this.cache) {
-                await this.cache.set(`flags-${identifier}`, flags);
-            }
-            return flags;
-        }
-        catch (e) {
-            if (this.offlineHandler) {
-                return this.getIdentityFlagsFromDocument(identifier, traits);
-            }
-            if (this.defaultFlagHandler) {
-                return new Flags({
-                    flags: {},
-                    defaultFlagHandler: this.defaultFlagHandler
-                });
-            }
-            throw e;
+        const data = generateIdentitiesData(identifier, traits, transient);
+        const jsonResponse = await this.getJSONResponse(this.identitiesUrl, 'POST', data);
+        const flags = Flags.fromAPIFlags({
+            apiFlags: jsonResponse['flags'],
+            analyticsProcessor: this.analyticsProcessor,
+            defaultFlagHandler: this.defaultFlagHandler
+        });
+        if (!!this.cache) {
+            await this.cache.set(`flags-${identifier}`, flags);
         }
+        return flags;
     }
-    getIdentityModel(identifier, traits) {
+    getIdentityModel(environment, identifier, traits) {
         const traitModels = traits.map(trait => new TraitModel(trait.key, trait.value));
         let identityWithOverrides = this.identitiesWithOverridesByIdentifier?.get(identifier);
         if (identityWithOverrides) {
             identityWithOverrides.updateTraits(traitModels);
             return identityWithOverrides;
         }
-        return new IdentityModel('0', traitModels, [], this.environment.apiKey, identifier);
+        return new IdentityModel('0', traitModels, [], environment.apiKey, identifier);
     }
 }
 export default Flagsmith;

package/build/esm/sdk/polling_manager.d.ts

@@ -1,9 +1,11 @@
 import Flagsmith from './index.js';
+import { Logger } from 'pino';
 export declare class EnvironmentDataPollingManager {
     private interval?;
     private main;
     private refreshIntervalSeconds;
-    constructor(main: Flagsmith, refreshIntervalSeconds: number);
+    private logger;
+    constructor(main: Flagsmith, refreshIntervalSeconds: number, logger: Logger);
     start(): void;
     stop(): void;
 }

package/build/esm/sdk/polling_manager.js

@@ -2,16 +2,23 @@ export class EnvironmentDataPollingManager {
     interval;
     main;
     refreshIntervalSeconds;
-    constructor(main, refreshIntervalSeconds) {
+    logger;
+    constructor(main, refreshIntervalSeconds, logger) {
         this.main = main;
         this.refreshIntervalSeconds = refreshIntervalSeconds;
+        this.logger = logger;
     }
     start() {
         const updateEnvironment = () => {
             if (this.interval)
                 clearInterval(this.interval);
             this.interval = setInterval(async () => {
-                await this.main.updateEnvironment();
+                try {
+                    await this.main.updateEnvironment();
+                }
+                catch (error) {
+                    this.logger.error(error, 'failed to poll environment');
+                }
             }, this.refreshIntervalSeconds * 1000);
         };
         updateEnvironment();

package/build/esm/sdk/types.d.ts

@@ -21,24 +21,92 @@ export interface FlagsmithCache {
     set(key: string, value: Flags): Promise<void>;
 }
 export type Fetch = typeof fetch;
+/**
+ * The configuration options for a {@link Flagsmith} client.
+ */
 export interface FlagsmithConfig {
+    /**
+     * The environment's client-side or server-side key.
+     */
     environmentKey?: string;
+    /**
+     * The Flagsmith API URL. Set this if you are not using Flagsmith's public service, i.e. https://app.flagsmith.com.
+     *
+     * @default https://edge.api.flagsmith.com/api/v1/
+     */
     apiUrl?: string;
+    /**
+     * A custom {@link Dispatcher} to use when making HTTP requests.
+     */
     agent?: Dispatcher;
+    /**
+     * A custom {@link fetch} implementation to use when making HTTP requests.
+     */
     fetch?: Fetch;
-    customHeaders?: {
-        [key: string]: any;
-    };
+    /**
+     * Custom headers to use in all HTTP requests.
+     */
+    customHeaders?: HeadersInit;
+    /**
+     * The network request timeout duration, in seconds.
+     *
+     * @default 10
+     */
     requestTimeoutSeconds?: number;
+    /**
+     * The amount of time, in milliseconds, to wait before retrying failed network requests.
+     */
+    requestRetryDelayMilliseconds?: number;
+    /**
+     * If enabled, flags are evaluated locally using the environment state cached in memory.
+     *
+     * The client will lazily fetch the environment from the Flagsmith API, and poll it every {@link environmentRefreshIntervalSeconds}.
+     */
     enableLocalEvaluation?: boolean;
+    /**
+     * The time, in seconds, to wait before refreshing the cached environment state.
+     * @default 60
+     */
     environmentRefreshIntervalSeconds?: number;
+    /**
+     * How many times to retry any failed network request before giving up.
+     * @default 3
+     */
     retries?: number;
+    /**
+     * If enabled, the client will keep track of any flags evaluated using {@link Flags.isFeatureEnabled},
+     * {@link Flags.getFeatureValue} or {@link Flags.getFlag}, and periodically flush this data to the Flagsmith API.
+     */
     enableAnalytics?: boolean;
-    defaultFlagHandler?: (featureName: string) => DefaultFlag;
+    /**
+     * Used to return fallback values for flags when evaluation fails for any reason. If not provided and flag
+     * evaluation fails, an error will be thrown intsead.
+     *
+     * @param flagKey The key of the flag that failed to evaluate.
+     *
+     * @example
+     * // All flags disabled and with no value by default
+     * const defaultHandler = () => new DefaultFlag(undefined, false)
+     *
+     * // Enable only VIP flags by default
+     * const vipDefaultHandler = (key: string) => new Default(undefined, key.startsWith('vip_'))
+     */
+    defaultFlagHandler?: (flagKey: string) => DefaultFlag;
     cache?: FlagsmithCache;
-    onEnvironmentChange?: (error: Error | null, result: EnvironmentModel) => void;
+    /**
+     * A callback function to invoke whenever the cached environment is updated.
+     * @param error The error that occurred when the environment state failed to update, if any.
+     * @param result The updated environment state, if no error was thrown.
+     */
+    onEnvironmentChange?: (error: Error | null, result?: EnvironmentModel) => void;
     logger?: Logger;
+    /**
+     * If enabled, the client will work offline and not make any network requests. Requires {@link offlineHandler}.
+     */
     offlineMode?: boolean;
+    /**
+     * If {@link offlineMode} is enabled, this handler is used to calculate the values of all flags.
+     */
     offlineHandler?: BaseOfflineHandler;
 }
 export interface ITraitConfig {

package/build/esm/sdk/utils.d.ts

@@ -32,5 +32,28 @@ export declare function generateIdentitiesData(identifier: string, traits: Trait
 export declare const delay: (ms: number) => Promise<unknown>;
 export declare const retryFetch: (url: string, fetchOptions: RequestInit & {
     dispatcher?: Dispatcher;
-}, retries: number | undefined, timeoutMs: number | undefined, customFetch: Fetch) => Promise<Response>;
+}, retries: number | undefined, timeoutMs: number | undefined, retryDelayMs: number | undefined, customFetch: Fetch) => Promise<Response>;
+/**
+ * A deferred promise can be resolved or rejected outside its creation scope.
+ *
+ * @template T The type of the value that the deferred promise will resolve to.
+ *
+ * @example
+ * const deferred = new Deferred<string>()
+ *
+ * // Pass the promise somewhere
+ * performAsyncOperation(deferred.promise)
+ *
+ * // Resolve it when ready from anywhere
+ * deferred.resolve("Operation completed")
+ * deferred.failed("Error")
+ */
+export declare class Deferred<T> {
+    readonly promise: Promise<T>;
+    private resolvePromise;
+    private rejectPromise;
+    constructor(initial?: T);
+    resolve(value: T | PromiseLike<T>): void;
+    reject(reason?: unknown): void;
+}
 export {};