launchdarkly-js-sdk-common 5.0.3 → 5.2.0

package/typings.d.ts

@@ -118,7 +118,7 @@ declare module 'launchdarkly-js-sdk-common' {
      * These are used to send metadata about the SDK (such as the version). They
      * are also used to send the application.id and application.version set in
      * the options.
-     * 
+     *
      * This defaults to true (custom headers will be sent). One reason you might
      * want to set it to false is that the presence of custom headers causes
      * browsers to make an extra OPTIONS request (a CORS preflight check) before
@@ -161,12 +161,12 @@ declare module 'launchdarkly-js-sdk-common' {
      * Specifies a list of attribute names (either built-in or custom) which should be marked as
      * private, and not sent to LaunchDarkly in analytics events. You can also specify this on a
      * per-context basis with {@link LDContextMeta.privateAttributes}.
-     * 
+     *
      * Any contexts sent to LaunchDarkly with this configuration active will have attributes with
      * these names removed in analytic events. This is in addition to any attributes that were
      * marked as private for an individual context with {@link LDContextMeta.privateAttributes}.
      * Setting {@link LDOptions.allAttributesPrivate} to true overrides this.
-     * 
+     *
      * If and only if a parameter starts with a slash, it is interpreted as a slash-delimited path
      * that can denote a nested property within a JSON object. For instance, "/address/street" means
      * that if there is an attribute called "address" that is a JSON object, and one of the object's
@@ -254,24 +254,24 @@ declare module 'launchdarkly-js-sdk-common' {
     application?: {
       /**
        * A unique identifier representing the application where the LaunchDarkly SDK is running.
-       * 
+       *
        * This can be specified as any string value as long as it only uses the following characters: ASCII letters,
        * ASCII digits, period, hyphen, underscore. A string containing any other characters will be ignored.
-       * 
+       *
        * Example: `authentication-service`
        */
       id?: string;
 
       /**
        * A unique identifier representing the version of the application where the LaunchDarkly SDK is running.
-       * 
+       *
        * This can be specified as any string value as long as it only uses the following characters: ASCII letters,
        * ASCII digits, period, hyphen, underscore. A string containing any other characters will be ignored.
-       * 
+       *
        * Example: `1.0.0` (standard version string) or `abcdef` (sha prefix)
        */
       version?: string;
-    }
+    };
 
     /**
      * Inspectors can be used for collecting information for monitoring, analytics, and debugging.
@@ -284,35 +284,34 @@ declare module 'launchdarkly-js-sdk-common' {
    * They cannot be addressed in targeting rules.
    */
   export interface LDContextMeta {
-
     /**
-     * 
+     *
      * Designate any number of Context attributes, or properties within them, as private: that is,
      * their values will not be sent to LaunchDarkly in analytics events.
-     * 
+     *
      * Each parameter can be a simple attribute name, such as "email". Or, if the first character is
      * a slash, the parameter is interpreted as a slash-delimited path to a property within a JSON
      * object, where the first path component is a Context attribute name and each following
      * component is a nested property name: for example, suppose the attribute "address" had the
      * following JSON object value:
-     * 
+     *
      * ```
      * 	{"street": {"line1": "abc", "line2": "def"}}
      * ```
-     * 
+     *
      * Using ["/address/street/line1"] in this case would cause the "line1" property to be marked as
      * private. This syntax deliberately resembles JSON Pointer, but other JSON Pointer features
      * such as array indexing are not supported for Private.
-     * 
+     *
      * This action only affects analytics events that involve this particular Context. To mark some
      * (or all) Context attributes as private for all users, use the overall configuration for the
      * SDK.
      * See {@link LDOptions.allAttributesPrivate} and {@link LDOptions.privateAttributes}.
-     * 
+     *
      * The attributes "kind" and "key", and the "_meta" attributes cannot be made private.
-     * 
+     *
      * In this example, firstName is marked as private, but lastName is not:
-     * 
+     *
      * ```
      * const context = {
      *   kind: 'org',
@@ -320,11 +319,11 @@ declare module 'launchdarkly-js-sdk-common' {
      *   firstName: 'Pierre',
      *   lastName: 'Menard',
      *   _meta: {
-     *     privateAttributes: ['firstName'], 
+     *     privateAttributes: ['firstName'],
      *   }
      * };
      * ```
-     * 
+     *
      * This is a metadata property, rather than an attribute that can be addressed in evaluations:
      * that is, a rule clause that references the attribute name "privateAttributes", will not use
      * this value, but would use a "privateAttributes" attribute set on the context.
@@ -370,12 +369,11 @@ declare module 'launchdarkly-js-sdk-common' {
     [attribute: string]: any;
   }
 
-
   /**
    * A context which represents a single kind.
-   * 
+   *
    * For a single kind context the 'kind' may not be 'multi'.
-   * 
+   *
    * ```
    * const myOrgContext = {
    *   kind: 'org',
@@ -383,7 +381,7 @@ declare module 'launchdarkly-js-sdk-common' {
    *   someAttribute: 'my-attribute-value'
    * };
    * ```
-   * 
+   *
    * The above context would be a single kind context representing an organization. It has a key
    * for that organization, and a single attribute 'someAttribute'.
    */
@@ -396,9 +394,9 @@ declare module 'launchdarkly-js-sdk-common' {
 
   /**
    * A context which represents multiple kinds. Each kind having its own key and attributes.
-   * 
+   *
    * A multi-context must contain `kind: 'multi'` at the root.
-   * 
+   *
    * ```
    * const myMultiContext = {
    *   // Multi-contexts must be of kind 'multi'.
@@ -421,7 +419,7 @@ declare module 'launchdarkly-js-sdk-common' {
    *   }
    * };
    * ```
-   * 
+   *
    * The above multi-context contains both an 'org' and a 'user'. Each with their own key,
    * attributes, and _meta attributes.
    */
@@ -429,15 +427,15 @@ declare module 'launchdarkly-js-sdk-common' {
     /**
      * The kind of the context.
      */
-    kind: "multi",
+    kind: 'multi';
 
     /**
      * The contexts which compose this multi-kind context.
-     * 
+     *
      * These should be of type LDContextCommon. "multi" is to allow
      * for the top level "kind" attribute.
      */
-    [kind: string]: "multi" | LDContextCommon;
+    [kind: string]: 'multi' | LDContextCommon;
   }
 
   /**
@@ -452,13 +450,13 @@ declare module 'launchdarkly-js-sdk-common' {
    * The LDUser object is currently supported for ease of upgrade.
    * In order to convert an LDUser into a LDSingleKindContext the following changes should
    * be made.
-   * 
+   *
    * 1.) Add a kind to the object. `kind: 'user'`.
-   * 
+   *
    * 2.) Move custom attributes to the top level of the object.
-   * 
+   *
    * 3.) Move `privateAttributeNames` to `_meta.privateAttributes`.
-   * 
+   *
    * ```
    * const LDUser: user = {
    *   key: '1234',
@@ -467,7 +465,7 @@ declare module 'launchdarkly-js-sdk-common' {
    *     myAttr: 'value'
    *   }
    * }
-   * 
+   *
    * const LDSingleKindContext: context = {
    *   kind: 'user',
    *   key: '1234',
@@ -666,7 +664,7 @@ declare module 'launchdarkly-js-sdk-common' {
      *
      * ```
      *     // using Promise then() and catch() handlers
-     *     client.waitForInitialization().then(() => {
+     *     client.waitForInitialization(5).then(() => {
      *         doSomethingWithSuccessfullyInitializedClient();
      *     }).catch(err => {
      *         doSomethingForFailedStartup(err);
@@ -674,7 +672,7 @@ declare module 'launchdarkly-js-sdk-common' {
      *
      *     // using async/await
      *     try {
-     *         await client.waitForInitialization();
+     *         await client.waitForInitialization(5);
      *         doSomethingWithSuccessfullyInitializedClient();
      *     } catch (err) {
      *         doSomethingForFailedStartup(err);
@@ -689,11 +687,20 @@ declare module 'launchdarkly-js-sdk-common' {
      * 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.
+     *   fails or the specified timeout elapses.
      */
-    waitForInitialization(): Promise<void>;
+    waitForInitialization(timeout?: number): Promise<void>;
 
     /**
      * Identifies a context to LaunchDarkly.
@@ -720,7 +727,11 @@ declare module 'launchdarkly-js-sdk-common' {
      *   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>;
+    identify(
+      context: LDContext,
+      hash?: string,
+      onDone?: (err: Error | null, flags: LDFlagSet | null) => void
+    ): Promise<LDFlagSet>;
 
     /**
      * Returns the client's current context.
@@ -766,7 +777,7 @@ declare module 'launchdarkly-js-sdk-common' {
      * Determines the variation of a feature flag for a context, along with information about how it was
      * calculated.
      *
-     * Note that this will only work if you have set `evaluationExplanations` to true in {@link LDOptions}.
+     * Note that this will only work if you have set `evaluationReasons` to true in {@link LDOptions}.
      * Otherwise, the `reason` property of the result will be null.
      *
      * The `reason` property of the result will also be included in analytics events, if you are
@@ -848,14 +859,14 @@ declare module 'launchdarkly-js-sdk-common' {
     off(key: string, callback: (...args: any[]) => void, context?: any): void;
 
     /**
-     * Track page events to use in goals or A/B tests.
+     * Track page events to use in metrics (goals) or Experimentation.
      *
      * LaunchDarkly automatically tracks pageviews and clicks that are specified in the
-     * Goals section of their dashboard. This can be used to track custom goals or other
-     * events that do not currently have goals.
+     * Metrics section of their dashboard. This can be used to track custom metrics or other
+     * events that do not currently have metrics.
      *
      * @param key
-     *   The name of the event, which may correspond to a goal in A/B tests.
+     *   The name of the event, which may correspond to a metric in experiments.
      * @param data
      *   Additional information to associate with the event.
      * @param metricValue
@@ -909,7 +920,7 @@ declare module 'launchdarkly-js-sdk-common' {
    * @param formatter An optional function equivalent to Node's util.format, allowing
    *   for parameter substitution in log messages. If this is omitted, parameter
    *   substitution is not available.
-   * 
+   *
    * @example
    * This example shows how to use `basicLogger` in your SDK options to enable console
    * logging only at `warn` and `error` levels.
@@ -927,7 +938,7 @@ declare module 'launchdarkly-js-sdk-common' {
    *     logger: ld.basicLogger({ destination: console.error }),
    *   };
    * ```
-   * 
+   *
    * @ignore (don't need to show this separately in TypeDoc output; each SDK should provide its own
    *   basicLogger function that delegates to this and sets the formatter parameter)
    */
@@ -971,7 +982,7 @@ declare module 'launchdarkly-js-sdk-common' {
      * Setting this property to anything other than a function will cause SDK
      * initialization to fail.
      */
-    destination?: (line: string) => void,
+    destination?: (line: string) => void;
   }
 
   /**
@@ -984,26 +995,23 @@ declare module 'launchdarkly-js-sdk-common' {
    */
   export type LDLogLevel = 'debug' | 'info' | 'warn' | 'error' | 'none';
 
-  export function getContextKeys(
-    context: LDContext,
-    logger?: LDLogger,
-  ): {[attribute: string]: string} | undefined;
+  export function getContextKeys(context: LDContext, logger?: LDLogger): { [attribute: string]: string } | undefined;
 
   /**
    * Callback interface for collecting information about the SDK at runtime.
-   * 
+   *
    * This interface is used to collect information about flag usage.
-   * 
+   *
    * This interface should not be used by the application to access flags for the purpose of controlling application
    * flow. It is intended for monitoring, analytics, or debugging purposes.
    */
   export interface LDInspectionFlagUsedHandler {
-    type: 'flag-used',
+    type: 'flag-used';
 
     /**
      * Name of the inspector. Will be used for logging issues with the inspector.
      */
-    name: string,
+    name: string;
 
     /**
      * This method is called when a flag is accessed via a variation method, or it can be called based on actions in
@@ -1015,22 +1023,22 @@ declare module 'launchdarkly-js-sdk-common' {
 
   /**
    * Callback interface for collecting information about the SDK at runtime.
-   * 
+   *
    * This interface is used to collect information about flag data. In order to understand the
    * current flag state it should be combined with {@link LDInspectionFlagValueChangedHandler}.
-   * This interface will get the initial flag information, and 
+   * This interface will get the initial flag information, and
    * {@link LDInspectionFlagValueChangedHandler} will provide changes to individual flags.
-   * 
+   *
    * This interface should not be used by the application to access flags for the purpose of controlling application
    * flow. It is intended for monitoring, analytics, or debugging purposes.
    */
   export interface LDInspectionFlagDetailsChangedHandler {
-    type: 'flag-details-changed',
+    type: 'flag-details-changed';
 
     /**
      * Name of the inspector. Will be used for logging issues with the inspector.
      */
-    name: string,
+    name: string;
 
     /**
      * This method is called when the flags in the store are replaced with new flags. It will contain all flags
@@ -1039,24 +1047,23 @@ declare module 'launchdarkly-js-sdk-common' {
     method: (details: Record<string, LDEvaluationDetail>) => void;
   }
 
-
   /**
    * Callback interface for collecting information about the SDK at runtime.
-   * 
+   *
    * This interface is used to collect changes to flag data, but does not provide the initial
    * data. It can be combined with {@link LDInspectionFlagValuesChangedHandler} to track the
    * entire flag state.
-   * 
+   *
    * This interface should not be used by the application to access flags for the purpose of controlling application
    * flow. It is intended for monitoring, analytics, or debugging purposes.
    */
   export interface LDInspectionFlagDetailChangedHandler {
-    type: 'flag-detail-changed',
+    type: 'flag-detail-changed';
 
     /**
      * Name of the inspector. Will be used for logging issues with the inspector.
      */
-    name: string,
+    name: string;
 
     /**
      * This method is called when a flag is updated. It will not be called
@@ -1067,19 +1074,19 @@ declare module 'launchdarkly-js-sdk-common' {
 
   /**
    * Callback interface for collecting information about the SDK at runtime.
-   * 
+   *
    * This interface is used to track current identity state of the SDK.
-   * 
+   *
    * This interface should not be used by the application to access flags for the purpose of controlling application
    * flow. It is intended for monitoring, analytics, or debugging purposes.
    */
   export interface LDInspectionIdentifyHandler {
-    type: 'client-identity-changed',
+    type: 'client-identity-changed';
 
     /**
      * Name of the inspector. Will be used for logging issues with the inspector.
      */
-    name: string,
+    name: string;
 
     /**
      * This method will be called when an identify operation completes.
@@ -1087,6 +1094,9 @@ declare module 'launchdarkly-js-sdk-common' {
     method: (context: LDContext) => void;
   }
 
-  export type LDInspection = LDInspectionFlagUsedHandler | LDInspectionFlagDetailsChangedHandler
-    | LDInspectionFlagDetailChangedHandler | LDInspectionIdentifyHandler;
+  export type LDInspection =
+    | LDInspectionFlagUsedHandler
+    | LDInspectionFlagDetailsChangedHandler
+    | LDInspectionFlagDetailChangedHandler
+    | LDInspectionIdentifyHandler;
 }