launchdarkly-js-sdk-common 5.1.0 → 5.3.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',
@@ -590,6 +588,14 @@ declare module 'launchdarkly-js-sdk-common' {
      * The key of the failed prerequisite flag, if the kind was `'PREREQUISITE_FAILED'`.
      */
     prerequisiteKey?: string;
+
+    /**
+     * Whether the evaluation was part of an experiment.
+     *
+     * This is true if the evaluation resulted in an experiment rollout and served one of
+     * the variations in the experiment. Otherwise it is false or undefined.
+     */
+    inExperiment?: boolean;
   }
 
   /**
@@ -666,7 +672,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 +680,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 +695,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 +735,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 +785,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
@@ -909,7 +928,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 +946,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 +990,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 +1003,30 @@ 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;
+
+    /**
+     * If `true`, then the inspector will be ran synchronously with evaluation.
+     * Synchronous inspectors execute inline with evaluation and care should be taken to ensure
+     * they have minimal performance overhead.
+     */
+    synchronous?: boolean,
 
     /**
      * This method is called when a flag is accessed via a variation method, or it can be called based on actions in
@@ -1015,22 +1038,27 @@ 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;
+
+    /**
+     * If `true`, then the inspector will be ran synchronously with flag updates.
+     */
+    synchronous?: boolean,
 
     /**
      * This method is called when the flags in the store are replaced with new flags. It will contain all flags
@@ -1039,24 +1067,28 @@ 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;
+
+    /**
+     * If `true`, then the inspector will be ran synchronously with flag updates.
+     */
+    synchronous?: boolean,
 
     /**
      * This method is called when a flag is updated. It will not be called
@@ -1067,19 +1099,24 @@ 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;
+
+    /**
+     * If `true`, then the inspector will be ran synchronously with identification.
+     */
+    synchronous?: boolean,
 
     /**
      * This method will be called when an identify operation completes.
@@ -1087,6 +1124,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;
 }

package/.ldrelease/config.yml

@@ -1,25 +0,0 @@
-version: 2
-
-repo:
-  public: js-sdk-common
-  private: js-sdk-common-private
-
-branches:
-  - name: main
-    description: 5.x
-  - name: 4.x
-  - name: 3.x
-
-publications:
-  - url: https://www.npmjs.com/package/launchdarkly-js-sdk-common
-    description: npm
-
-jobs:
-  - docker:
-      image: node:12-buster
-    template:
-      name: npm
-
-documentation:
-  gitHubPages: true
-  title: LaunchDarkly Javascript SDK Core Components

package/docs/typedoc.js

@@ -1,11 +0,0 @@
-module.exports = {
-  out: '/tmp/project-releaser/project/docs/build/html',
-  exclude: [
-    '**/node_modules/**',
-    'test-types.ts'
-  ],
-  name: "LaunchDarkly Javascript SDK Core Components (4.0.2)",
-  readme: 'none',                // don't add a home page with a copy of README.md
-  entryPoints: "/tmp/project-releaser/project/typings.d.ts",
-  entryPointStrategy: "expand"
-};