@microsoft/applicationinsights-core-js 2.8.0-beta.2203-02 → 2.8.0-beta.2203-05

package/dist/applicationinsights-core-js.rollup.d.ts

@@ -1,5 +1,5 @@
 /*
- * Microsoft Application Insights Core Javascript SDK, 2.8.0-beta.2203-02
+ * Microsoft Application Insights Core Javascript SDK, 2.8.0-beta.2203-05
  * Copyright (c) Microsoft and contributors. All rights reserved.
  *
  * Microsoft Application Insights Team
@@ -24,9 +24,11 @@ import { strShimUndefined as strUndefined } from '@microsoft/applicationinsights
  * Get all of the registered events on the target object, this is primarily used for testing cleanup but may also be used by
  * applications to remove their own events
  * @param target - The EventTarget that has registered events
- * @param evtName - [Optional] The name of the event to return the registered handlers and full name (with namespaces)
+ * @param eventName - [Optional] The name of the event to return the registered handlers and full name (with namespaces)
+ * @param evtNamespace - [Optional] Additional namespace(s) to append to the event listeners so they can be uniquely identified and removed based on this namespace,
+ * if the eventName also includes a namespace the namespace(s) are merged into a single namespace
  */
-export declare function __getRegisteredEvents(target: any, evtName?: string): _IRegisteredEvents[];
+export declare function __getRegisteredEvents(target: any, eventName?: string, evtNamespace?: string | string[]): _IRegisteredEvents[];
 
 /**
  * Trys to add an event handler for the specified event to the window, body and document
@@ -195,12 +197,34 @@ export declare class BaseCore implements IAppInsightsCore {
      * @returns - A ITelemetryInitializerHandler to enable the initializer to be removed
      */
     addTelemetryInitializer(telemetryInitializer: TelemetryInitializerFunction): ITelemetryInitializerHandler | void;
+    /**
+     * Unload and Tear down the SDK and any initialized plugins, after calling this the SDK will be considered
+     * to be un-initialized and non-operational, re-initializing the SDK should only be attempted if the previous
+     * unload call return `true` stating that all plugins reported that they also unloaded, the recommended
+     * approach is to create a new instance and initialize that instance.
+     * This is due to possible unexpected side effects caused by plugins not supporting unload / teardown, unable
+     * to successfully remove any global references or they may just be completing the unload process asynchronously.
+     */
+    unload(isAsync?: boolean, unloadComplete?: (unloadState: ITelemetryUnloadState) => void, cbTimeout?: number): void;
     getPlugin<T extends IPlugin = IPlugin>(pluginIdentifier: string): ILoadedPlugin<T>;
+    addPlugin<T extends IPlugin = ITelemetryPlugin>(plugin: T, replaceExisting: boolean, doAsync: boolean, addCb?: (added?: boolean) => void): void;
     /**
      * Returns the unique event namespace that should be used
      */
     evtNamespace(): string;
+    /**
+     * Add an unload handler that will be called when the SDK is being unloaded
+     * @param handler - the handler
+     */
+    addUnloadCb(handler: UnloadHandler): void;
     protected releaseQueue(): void;
+    /**
+     * Hook for Core extensions to allow them to update their own configuration before updating all of the plugins.
+     * @param updateCtx - The plugin update context
+     * @param updateState - The Update State
+     * @returns boolean - True means the extension class will call updateState otherwise the Core will
+     */
+    protected _updateHook?(updateCtx: IProcessTelemetryUpdateContext, updateState: ITelemetryUpdateState): void | boolean;
 }
 
 /**
@@ -257,6 +281,14 @@ export declare abstract class BaseTelemetryPlugin implements ITelemetryPlugin {
      * @returns boolean - true if the plugin has or will call asyncCallback, this allows the plugin to perform any asynchronous operations.
      */
     protected _doTeardown?: (unloadCtx?: IProcessTelemetryUnloadContext, unloadState?: ITelemetryUnloadState, asyncCallback?: () => void) => void | boolean;
+    /**
+     * Extension hook to allow implementations to perform some additional update operations before the BaseTelemetryPlugin finishes it's removal
+     * @param updateCtx - This is the context that should be used during updating.
+     * @param updateState - The details / state of the update process, it holds details like the current and previous configuration.
+     * @param asyncCallback - An optional callback that the plugin must call if it returns true to inform the caller that it has completed any async update operations.
+     * @returns boolean - true if the plugin has or will call asyncCallback, this allows the plugin to perform any asynchronous operations.
+     */
+    protected _doUpdate?: (updateCtx?: IProcessTelemetryUpdateContext, updateState?: ITelemetryUpdateState, asyncCallback?: () => void) => void | boolean;
     constructor();
     initialize(config: IConfiguration, core: IAppInsightsCore, extensions: IPlugin[], pluginChain?: ITelemetryPluginChain): void;
     /**
@@ -269,6 +301,18 @@ export declare abstract class BaseTelemetryPlugin implements ITelemetryPlugin {
      */
     teardown(unloadCtx?: IProcessTelemetryUnloadContext, unloadState?: ITelemetryUnloadState): void | boolean;
     abstract processTelemetry(env: ITelemetryItem, itemCtx?: IProcessTelemetryContext): void;
+    /**
+     * The the plugin should re-evaluate configuration and update any cached configuration settings.
+     * @param updateCtx - This is the context that should be used during updating.
+     * @param updateState - The details / state of the update process, it holds details like the current and previous configuration.
+     * @returns boolean - true if the plugin has or will call updateCtx.processNext(), this allows the plugin to perform any asynchronous operations.
+     */
+    update(updateCtx: IProcessTelemetryUpdateContext, updateState: ITelemetryUpdateState): void | boolean;
+    /**
+     * Add an unload handler that will be called when the SDK is being unloaded
+     * @param handler - the handler
+     */
+    protected _addUnloadCb(handler: UnloadHandler): void;
     /**
      * Add this hook so that it is automatically removed during unloading
      * @param hooks - The single hook or an array of IInstrumentHook objects
@@ -311,11 +355,17 @@ export declare function createEnumStyle<T>(values: T): T;
  * @param plugins - The plugin instances that will be executed
  * @param config - The current config
  * @param core - The current core instance
+ * @param startAt - Identifies the next plugin to execute, if null there is no "next" plugin and if undefined it should assume the start of the chain
  */
 export declare function createProcessTelemetryContext(telemetryChain: ITelemetryPluginChain, config: IConfiguration, core: IAppInsightsCore, startAt?: IPlugin): IProcessTelemetryContext;
 
 export declare function createUniqueNamespace(name: string, includeVersion?: boolean): string;
 
+export declare function createUnloadHandlerContainer(): {
+    add: (handler: UnloadHandler) => void;
+    run: (unloadCtx: IProcessTelemetryUnloadContext, unloadState: ITelemetryUnloadState) => void;
+};
+
 /**
  * Return the current time via the Date now() function (if available) and falls back to (new Date()).getTime() if now() is unavailable (IE8 or less)
  * https://caniuse.com/#search=Date.now
@@ -787,18 +837,39 @@ export declare interface IAppInsightsCore extends IPerfManagerProvider {
      * Return a new instance of the IProcessTelemetryContext for processing events
      */
     getProcessTelContext(): IProcessTelemetryContext;
+    /**
+     * Unload and Tear down the SDK and any initialized plugins, after calling this the SDK will be considered
+     * to be un-initialized and non-operational, re-initializing the SDK should only be attempted if the previous
+     * unload call return `true` stating that all plugins reported that they also unloaded, the recommended
+     * approach is to create a new instance and initialize that instance.
+     * This is due to possible unexpected side effects caused by plugins not supporting unload / teardown, unable
+     * to successfully remove any global references or they may just be completing the unload process asynchronously.
+     */
+    unload(isAsync?: boolean, unloadComplete?: () => void): void;
     /**
      * Find and return the (first) plugin with the specified identifier if present
      * @param pluginIdentifier
      */
     getPlugin<T extends IPlugin = IPlugin>(pluginIdentifier: string): ILoadedPlugin<T>;
+    /**
+     * Add a new plugin to the installation
+     * @param plugin - The new plugin to add
+     * @param replaceExisting - should any existing plugin be replaced
+     * @param doAsync - Should the add be performed asynchronously
+     */
+    addPlugin<T extends IPlugin = ITelemetryPlugin>(plugin: T, replaceExisting: boolean, doAsync: boolean, addCb?: (added?: boolean) => void): void;
     /**
      * Returns the unique event namespace that should be used when registering events
      */
     evtNamespace(): string;
+    /**
+     * Add a handler that will be called when the SDK is being unloaded
+     * @param handler - the handler
+     */
+    addUnloadCb(handler: UnloadHandler): void;
 }
 
-declare interface IBaseProcessingContext {
+export declare interface IBaseProcessingContext {
     /**
      * The current core instance for the request
      */
@@ -1463,6 +1534,11 @@ export declare interface IInstrumentHooks {
  * You must always supply the error callback
  */
 export declare interface IInstrumentHooksCallbacks {
+    /**
+     * [Optional] Namespace details (same as the namespace used for events), useful for debugging and testing to
+     * identify the source of the instrumented hooks
+     */
+    ns?: string | string[];
     /**
      * The hook callback to call before the original function is called
      */
@@ -1497,6 +1573,7 @@ declare interface ILoadedPlugin<T extends IPlugin> {
      * (unless it's also been re-initialized)
      */
     setEnabled: (isEnabled: boolean) => void;
+    remove: (isAsync?: boolean, removeCb?: (removed?: boolean) => void) => void;
 }
 
 /**
@@ -1876,10 +1953,10 @@ export declare interface IProcessTelemetryContext extends IBaseProcessingContext
 }
 
 /**
- * The current context for the current call to processTelemetry(), used to support sharing the same plugin instance
- * between multiple AppInsights instances
+ * The current context for the current call to teardown() implementations, used to support when plugins are being removed
+ * or the SDK is being unloaded.
  */
-declare interface IProcessTelemetryUnloadContext extends IBaseProcessingContext {
+export declare interface IProcessTelemetryUnloadContext extends IBaseProcessingContext {
     /**
      * This Plugin has finished unloading, so unload the next one
      * @param uploadState - The state of the unload process
@@ -1896,6 +1973,27 @@ declare interface IProcessTelemetryUnloadContext extends IBaseProcessingContext
     createNew: (plugins?: IPlugin[] | ITelemetryPluginChain, startAt?: IPlugin) => IProcessTelemetryUnloadContext;
 }
 
+/**
+ * The current context for the current call to the plugin update() implementations, used to support the notifications
+ * for when plugins are added, removed or the configuration was changed.
+ */
+export declare interface IProcessTelemetryUpdateContext extends IBaseProcessingContext {
+    /**
+     * This Plugin has finished unloading, so unload the next one
+     * @param updateState - The update State
+     * @returns boolean (true) if there is no more plugins to process otherwise false or undefined (void)
+     */
+    processNext: (updateState: ITelemetryUpdateState) => boolean | void;
+    /**
+     * Create a new context using the core and config from the current instance, returns a new instance of the same type
+     * @param plugins - The execution order to process the plugins, if null or not supplied
+     *                  then the current execution order will be copied.
+     * @param startAt - The plugin to start processing from, if missing from the execution
+     *                  order then the next plugin will be NOT set.
+     */
+    createNew: (plugins?: IPlugin[] | ITelemetryPluginChain, startAt?: IPlugin) => IProcessTelemetryUpdateContext;
+}
+
 export declare interface _IRegisteredEvents {
     name: string;
     handler: any;
@@ -2100,6 +2198,15 @@ declare interface ITelemetryProcessor {
      * to later plugins (vs appending items to the telemetry item)
      */
     processTelemetry: (env: ITelemetryItem, itemCtx?: IProcessTelemetryContext) => void;
+    /**
+     * The the plugin should re-evaluate configuration and update any cached configuration settings or
+     * plugins. If implemented this method will be called whenever a plugin is added or removed and if
+     * the configuration has bee updated.
+     * @param updateCtx - This is the context that should be used during updating.
+     * @param updateState - The details / state of the update process, it holds details like the current and previous configuration.
+     * @returns boolean - true if the plugin has or will call updateCtx.processNext(), this allows the plugin to perform any asynchronous operations.
+     */
+    update?: (updateCtx: IProcessTelemetryUpdateContext, updateState: ITelemetryUpdateState) => void | boolean;
 }
 
 export declare interface ITelemetryUnloadState {
@@ -2108,6 +2215,32 @@ export declare interface ITelemetryUnloadState {
     flushComplete?: boolean;
 }
 
+export declare interface ITelemetryUpdateState {
+    /**
+     * Identifies the reason for the update notification, this is a bitwise numeric value
+     */
+    reason: TelemetryUpdateReason;
+    /**
+     * If this is a configuration update this was the previous configuration that was used
+     */
+    /**
+     * If this is a configuration update is the new configuration that is being used
+     */
+    /**
+     * This holds a collection of plugins that have been added (if the reason identifies that one or more plugins have been added)
+     */
+    added?: IPlugin[];
+    /**
+     * This holds a collection of plugins that have been removed (if the reason identifies that one or more plugins have been removed)
+     */
+    removed?: IPlugin[];
+}
+
+export declare interface IUnloadHandlerContainer {
+    add: (handler: UnloadHandler) => void;
+    run: (itemCtx: IProcessTelemetryUnloadContext, unloadState: ITelemetryUnloadState) => void;
+}
+
 /**
  * Helper to support backward compatibility for users that use the legacy cookie handling functions and the use the internal
  * CoreUtils._canUseCookies global flag to enable/disable cookies usage.
@@ -2229,7 +2362,9 @@ export declare function objDefineAccessors<T>(target: any, prop: string, getProp
  * @param obj5 - object to merge.
  * @returns The extended first object.
  */
-export declare function objExtend<T1, T2, T3, T4, T5, T6>(obj?: boolean | T1, obj2?: T2, obj3?: T3, obj4?: T4, obj5?: T5, obj6?: T6): T1 & T2 & T3 & T4 & T5 & T6;
+export declare function objExtend<T2, T3, T4, T5, T6>(deepExtend?: boolean, obj2?: T2, obj3?: T3, obj4?: T4, obj5?: T5, obj6?: T6): T2 & T3 & T4 & T5 & T6;
+
+export declare function objExtend<T1, T2, T3, T4, T5, T6>(obj1?: T1, obj2?: T2, obj3?: T3, obj4?: T4, obj5?: T5, obj6?: T6): T1 & T2 & T3 & T4 & T5 & T6;
 
 /**
  * This is a helper function for the equivalent of arForEach(objKeys(target), callbackFn), this is a
@@ -2528,6 +2663,10 @@ export declare const enum SendRequestReason {
      * The event(s) being sent as a retry
      */
     Retry = 5,
+    /**
+     * The SDK is unloading
+     */
+    SdkUnload = 6,
     /**
      * Maximum batch size would be exceeded
      */
@@ -2619,15 +2758,59 @@ export declare type TelemetryInitializerFunction = <T extends ITelemetryItem>(it
 /**
  * The TelemetryUnloadReason enumeration contains the possible reasons for why a plugin is being unloaded / torndown().
  */
-declare const enum TelemetryUnloadReason {
+export declare const enum TelemetryUnloadReason {
     /**
      * Teardown has been called without any context.
      */
-    ManualTeardown = 0
+    ManualTeardown = 0,
+    /**
+     * Just this plugin is being removed
+     */
+    PluginUnload = 1,
+    /**
+     * This instance of the plugin is being removed and replaced
+     */
+    PluginReplace = 2,
+    /**
+     * The entire SDK is being unloaded
+     */
+    SdkUnload = 50
+}
+
+/**
+ * The TelemetryUpdateReason enumeration contains a set of bit-wise values that specify the reason for update request.
+ */
+export declare const enum TelemetryUpdateReason {
+    /**
+     * Unknown.
+     */
+    Unknown = 0,
+    /**
+     * The configuration has ben updated or changed
+     */
+    /**
+     * One or more plugins have been added
+     */
+    PluginAdded = 16,
+    /**
+     * One or more plugins have been removed
+     */
+    PluginRemoved = 32
 }
 
 export declare function throwError(message: string): never;
 
+/**
+ * This is a helper method which will call throwInternal on the passed logger, will throw exceptions in
+ * debug mode or attempt to log the error as a console warning. This helper is provided mostly to better
+ * support minification as logger.throwInternal() will not compress the publish "throwInternal" used throughout
+ * the code.
+ * @param logger - The Diagnostic Logger instance to use.
+ * @param severity {LoggingSeverity} - The severity of the log message
+ * @param message {_InternalLogMessage} - The log message.
+ */
+export declare function _throwInternal(logger: IDiagnosticLogger, severity: LoggingSeverity, msgId: _InternalMessageId, msg: string, properties?: Object, isUserAct?: boolean): void;
+
 /**
  * Convert a date to I.S.O. format in IE8
  */
@@ -2637,6 +2820,8 @@ export declare function uaDisallowsSameSiteNone(userAgent: string): boolean;
 
 export declare const Undefined = "undefined";
 
+export declare type UnloadHandler = (itemCtx: IProcessTelemetryUnloadContext, unloadState: ITelemetryUnloadState) => void;
+
 export declare function useXDomainRequest(): boolean | undefined;
 
 export { }

package/dist-esm/JavaScriptSDK/AppInsightsCore.js

@@ -1,5 +1,5 @@
 /*
- * Application Insights JavaScript SDK - Core, 2.8.0-beta.2203-02
+ * Application Insights JavaScript SDK - Core, 2.8.0-beta.2203-05
  * Copyright (c) Microsoft and contributors. All rights reserved.
  */
 import { __extendsFn as __extends } from "@microsoft/applicationinsights-shims";