The LaunchDarkly SDK client object.

Create this object with init. Applications should configure the client at startup time and continue to use it throughout the lifetime of the application, rather than creating instances on the fly.

Hierarchy

  • LDClient

Methods

  • Builds an object that encapsulates the state of all feature flags for a given context. This includes the flag values and also metadata that can be used on the front end. This method does not send analytics events back to LaunchDarkly.

    The most common use case for this method is to bootstrap a set of client-side feature flags from a back-end service. Call the toJSON() method of the returned object to convert it to the data structure used by the client-side SDK.

    Parameters

    • context: LDContext

      The context requesting the feature flags.

    • Optional options: LDFlagsStateOptions

      Optional LDFlagsStateOptions to determine how the state is computed.

      Optional
    • Optional callback: ((err, res) => void)

      A Node-style callback to receive the result (as an LDFlagsState). If omitted, you will receive a Promise instead.

      Optional
        • (err, res): void
        • Parameters

          Returns void

    Returns Promise<LDFlagsState>

    If you provided a callback, then nothing. Otherwise, a Promise which will be resolved with the result as an LDFlagsState.

  • Determines the boolean variation of a feature flag for a context.

    If the flag variation does not have a boolean value, defaultValue is returned.

    Parameters

    • key: string

      The unique key of the feature flag.

    • context: LDContext

      The context requesting the flag. The client will generate an analytics event to register this context with LaunchDarkly if the context does not already exist.

    • defaultValue: boolean

      The default value of the flag, to be used if the value is not available from LaunchDarkly.

    Returns Promise<boolean>

    A Promise which will be resolved with the result value.

  • Determines the boolean variation of a feature flag for a context, along with information about how it was calculated.

    The reason property of the result will also be included in analytics events, if you are capturing detailed event data for this flag.

    If the flag variation does not have a boolean value, defaultValue is returned. The reason will indicate an error of the type WRONG_KIND in this case.

    For more information, see the SDK reference guide.

    Parameters

    • key: string

      The unique key of the feature flag.

    • context: LDContext

      The context requesting the flag. The client will generate an analytics event to register this context with LaunchDarkly if the context does not already exist.

    • defaultValue: boolean

      The default value of the flag, to be used if the value is not available from LaunchDarkly.

    Returns Promise<LDEvaluationDetailTyped<boolean>>

    A Promise which will be resolved with the result (as an ).

  • Flushes all pending analytics events.

    Normally, batches of events are delivered in the background at intervals determined by the flushInterval property of LDOptions. Calling flush() triggers an immediate delivery. However, like Node I/O in general, this is still an asynchronous operation so you must still use Promise chaining, a callback, or async/await to detect when it has finished or failed.

    Parameters

    • Optional callback: ((err, res) => void)

      A function which will be called when the flush completes (meaning that all pending events have been delivered to LaunchDarkly). If omitted, you will receive a Promise instead.

      Optional
        • (err, res): void
        • Parameters

          • err: null | Error
          • res: boolean

          Returns void

    Returns Promise<void>

    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.

  • Identifies a context to LaunchDarkly.

    This simply creates an analytics event that will transmit the given user properties to LaunchDarkly, so that the context will be visible on your dashboard even if you have not evaluated any flags for that user. It has no other effect.

    If the context is omitted or has no key, the client will log a warning and will not send an event.

    Parameters

    • context: LDContext

      The context properties. Must contain at least the key property.

    Returns void

  • Tests whether the client has completed initialization.

    If this returns false, it means that the client has not yet successfully connected to LaunchDarkly. It might still be in the process of starting up, or it might be attempting to reconnect after an unsuccessful attempt, or it might have received an unrecoverable error (such as an invalid SDK key) and given up.

    Returns boolean

    True if the client has successfully initialized.

  • Determines the variation of a feature flag for a context.

    This version may be favored in TypeScript versus variation because it returns an unknown type instead of any. unknown will require a cast before usage.

    Parameters

    • key: string

      The unique key of the feature flag.

    • context: LDContext

      The context requesting the flag. The client will generate an analytics event to register this context with LaunchDarkly if the context does not already exist.

    • defaultValue: unknown

      The default value of the flag, to be used if the value is not available from LaunchDarkly.

    Returns Promise<unknown>

    A Promise which will be resolved with the result value.

  • Determines the variation of a feature flag for a context, along with information about how it was calculated.

    The reason property of the result will also be included in analytics events, if you are capturing detailed event data for this flag.

    This version may be favored in TypeScript versus variation because it returns an unknown type instead of any. unknown will require a cast before usage.

    For more information, see the SDK reference guide.

    Parameters

    • key: string

      The unique key of the feature flag.

    • context: LDContext

      The context requesting the flag. The client will generate an analytics event to register this context with LaunchDarkly if the context does not already exist.

    • defaultValue: unknown

      The default value of the flag, to be used if the value is not available from LaunchDarkly.

    Returns Promise<LDEvaluationDetailTyped<unknown>>

    If you provided a callback, then nothing. Otherwise, a Promise which will be resolved with the result (as an).

  • Returns the migration stage of the migration feature flag for the given evaluation context.

    If the evaluated value of the flag cannot be converted to an LDMigrationStage, then the default value will be returned and error will be logged.

    Parameters

    • key: string

      The unique key of the feature flag.

    • context: LDContext

      The context requesting the flag. The client will generate an analytics event to register this context with LaunchDarkly if the context does not already exist.

    • defaultValue: LDMigrationStage

      The default value of the flag, to be used if the value is not available from LaunchDarkly.

    Returns Promise<LDMigrationVariation>

    A Promise which will be resolved with the result (as anLDMigrationVariation).

  • Determines the numeric variation of a feature flag for a context.

    If the flag variation does not have a numeric value, defaultValue is returned.

    Parameters

    • key: string

      The unique key of the feature flag.

    • context: LDContext

      The context requesting the flag. The client will generate an analytics event to register this context with LaunchDarkly if the context does not already exist.

    • defaultValue: number

      The default value of the flag, to be used if the value is not available from LaunchDarkly.

    Returns Promise<number>

    A Promise which will be resolved with the result value.

  • Determines the numeric variation of a feature flag for a context, along with information about how it was calculated.

    The reason property of the result will also be included in analytics events, if you are capturing detailed event data for this flag.

    If the flag variation does not have a numeric value, defaultValue is returned. The reason will indicate an error of the type WRONG_KIND in this case.

    For more information, see the SDK reference guide.

    Parameters

    • key: string

      The unique key of the feature flag.

    • context: LDContext

      The context requesting the flag. The client will generate an analytics event to register this context with LaunchDarkly if the context does not already exist.

    • defaultValue: number

      The default value of the flag, to be used if the value is not available from LaunchDarkly.

    Returns Promise<LDEvaluationDetailTyped<number>>

    A Promise which will be resolved with the result (as an ).

  • Determines the string variation of a feature flag for a context.

    If the flag variation does not have a string value, defaultValue is returned.

    Parameters

    • key: string

      The unique key of the feature flag.

    • context: LDContext

      The context requesting the flag. The client will generate an analytics event to register this context with LaunchDarkly if the context does not already exist.

    • defaultValue: string

      The default value of the flag, to be used if the value is not available from LaunchDarkly.

    Returns Promise<string>

    A Promise which will be resolved with the result value.

  • Determines the string variation of a feature flag for a context, along with information about how it was calculated.

    The reason property of the result will also be included in analytics events, if you are capturing detailed event data for this flag.

    If the flag variation does not have a string value, defaultValue is returned. The reason will indicate an error of the type WRONG_KIND in this case.

    For more information, see the SDK reference guide.

    Parameters

    • key: string

      The unique key of the feature flag.

    • context: LDContext

      The context requesting the flag. The client will generate an analytics event to register this context with LaunchDarkly if the context does not already exist.

    • defaultValue: string

      The default value of the flag, to be used if the value is not available from LaunchDarkly.

    Returns Promise<LDEvaluationDetailTyped<string>>

    A Promise which will be resolved with the result (as an ).

  • Tracks that a context performed an event.

    LaunchDarkly automatically tracks pageviews and clicks that are specified in the Metrics section of the dashboard. This can be used to track custom metrics (goals) or other events that do not currently have metrics.

    Note that event delivery is asynchronous, so the event may not actually be sent until later; see flush.

    If the context is omitted or has no key, the client will log a warning and will not send an event.

    Parameters

    • key: string

      The name of the event, which may correspond to a metric in Experimentation.

    • context: LDContext

      The context to track.

    • Optional data: any

      Optional additional information to associate with the event.

      Optional
    • Optional metricValue: number

      A numeric value used by the LaunchDarkly experimentation feature in numeric custom metrics. Can be omitted if this event is used by only non-numeric metrics. This field will also be returned as part of the custom event for Data Export.

      Optional

    Returns void

  • Determines the variation of a feature flag for a context.

    Parameters

    • key: string

      The unique key of the feature flag.

    • context: LDContext

      The context requesting the flag. The client will generate an analytics event to register this context with LaunchDarkly if the context does not already exist.

    • defaultValue: any

      The default value of the flag, to be used if the value is not available from LaunchDarkly.

    • Optional callback: ((err, res) => void)

      A Node-style callback to receive the result value. If omitted, you will receive a Promise instead.

      Optional
        • (err, res): void
        • Parameters

          • err: any
          • res: any

          Returns void

    Returns Promise<any>

    If you provided a callback, then nothing. Otherwise, a Promise which will be resolved with the result value.

  • Determines the variation of a feature flag for a context, along with information about how it was calculated.

    The reason property of the result will also be included in analytics events, if you are capturing detailed event data for this flag.

    For more information, see the SDK reference guide.

    Parameters

    • key: string

      The unique key of the feature flag.

    • context: LDContext

      The context requesting the flag. The client will generate an analytics event to register this context with LaunchDarkly if the context does not already exist.

    • defaultValue: any

      The default value of the flag, to be used if the value is not available from LaunchDarkly.

    • Optional callback: ((err, res) => void)

      A Node-style callback to receive the result (as an LDEvaluationDetail). If omitted, you will receive a Promise instead.

      Optional

    Returns Promise<LDEvaluationDetail>

    If you provided a callback, then nothing. Otherwise, a Promise which will be resolved with the result (as anLDEvaluationDetail).

  • 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 failed unrecoverably (for instance, if it detects that the SDK key is invalid). Keep in mind that unhandled Promise rejections can be fatal in Node, so if you call this method, be sure to attach a rejection handler to it (or, if using async/await, a catch block).

    Note that you can also use event listeners (on) for the same purpose: the event "ready" indicates success, and "failed" indicates failure.

    This method takes an optional parameters which include a timeout. The timeout controls how long a specific call to waitForInitialization will wait before rejecting its promise. If a subsequent call is made to waitForInitialization with a timeout, then it will again wait up to that maximum time.

    Regardless of whether you continue to wait, the SDK will still retry all connection failures indefinitely unless it gets an unrecoverable error as described above.

    Waiting indefinitely, or depending only on the "ready" or "failed" events can result in an application waiting indefinitely. It is recommended to use a timeout which is reasonable for your application.

    Parameters

    Returns Promise<LDClient>

    A Promise that will be resolved if the client initializes successfully, or rejected if it fails. If successful, the result is the same client object. It is not recommended to use the returned client object. It will be removed in a future version.

    Example

    This example shows use of Promise chaining methods for specifying handlers:

      client.waitForInitialization({timeoutSeconds: 10}).then(() => {
    // do whatever is appropriate if initialization has succeeded
    }).catch(err => {
    // do whatever is appropriate if initialization has failed or timed out
    })

    Example

    This example shows use of async/await syntax for specifying handlers:

      try {
    await client.waitForInitialization({timeoutSeconds: 10});
    // do whatever is appropriate if initialization has succeeded
    } catch (err) {
    // do whatever is appropriate if initialization has failed or timed out
    }

Generated using TypeDoc