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

package/src/JavaScriptSDK/BaseTelemetryPlugin.ts

@@ -12,8 +12,9 @@ import { ITelemetryItem } from "../JavaScriptSDK.Interfaces/ITelemetryItem";
 import { IProcessTelemetryContext, IProcessTelemetryUnloadContext } from "../JavaScriptSDK.Interfaces/IProcessTelemetryContext";
 import { ITelemetryPluginChain } from "../JavaScriptSDK.Interfaces/ITelemetryPluginChain";
 import { createProcessTelemetryContext, createProcessTelemetryUnloadContext } from "./ProcessTelemetryContext";
-import { arrForEach, isArray, isFunction, isNullOrUndefined, setValue } from "./HelperFuncs";
+import { arrForEach, isArray, isFunction, isNullOrUndefined, proxyFunctionAs, setValue } from "./HelperFuncs";
 import { strExtensionConfig } from "./Constants";
+import { createUnloadHandlerContainer, IUnloadHandlerContainer, UnloadHandler } from "./UnloadHandlerContainer";
 import { IInstrumentHook } from "../JavaScriptSDK.Interfaces/IInstrumentHooks";
 import { ITelemetryUnloadState } from "../JavaScriptSDK.Interfaces/ITelemetryUnloadState";
 import { TelemetryUnloadReason } from "../JavaScriptSDK.Enums/TelemetryUnloadReason";
@@ -93,6 +94,7 @@ export abstract class BaseTelemetryPlugin implements ITelemetryPlugin {
         let _isinitialized: boolean;
         let _rootCtx: IProcessTelemetryContext; // Used as the root context, holding the current config and initialized core
         let _nextPlugin: ITelemetryPlugin | ITelemetryPluginChain; // Used for backward compatibility where plugins don't call the main pipeline
+        let _unloadHandlerContainer: IUnloadHandlerContainer;
         let _hooks: IInstrumentHook[];
 
         _initDefaults();
@@ -120,11 +122,12 @@ export abstract class BaseTelemetryPlugin implements ITelemetryPlugin {
                     isAsync: false
                 };
 
-
                 function _unloadCallback() {
                     if (!unloadDone) {
                         unloadDone = true;
 
+                        _unloadHandlerContainer.run(theUnloadCtx, unloadState);
+
                         // Remove all instrumentation hooks
                         arrForEach(_hooks, (fn) => {
                             fn.rm();
@@ -158,6 +161,8 @@ export abstract class BaseTelemetryPlugin implements ITelemetryPlugin {
                     }
                 }
             };
+
+            proxyFunctionAs(_self, "_addUnloadCb", () => _unloadHandlerContainer, "add");
         });
 
         // These are added after the dynamicProto so that are not moved to the prototype
@@ -240,6 +245,7 @@ export abstract class BaseTelemetryPlugin implements ITelemetryPlugin {
             _rootCtx = null;
             _nextPlugin = null;
             _hooks = [];
+            _unloadHandlerContainer = createUnloadHandlerContainer();
         }
     }
 
@@ -262,6 +268,14 @@ export abstract class BaseTelemetryPlugin implements ITelemetryPlugin {
 
     public abstract processTelemetry(env: ITelemetryItem, itemCtx?: IProcessTelemetryContext): void;
 
+    /**
+     * Add an unload handler that will be called when the SDK is being unloaded
+     * @param handler - the handler
+     */
+    protected _addUnloadCb(handler: UnloadHandler): void {
+        // @DynamicProtoStub -- DO NOT add any code as this will be removed during packaging
+    }
+
     /**
      * Add this hook so that it is automatically removed during unloading
      * @param hooks - The single hook or an array of IInstrumentHook objects

package/src/JavaScriptSDK/HelperFuncs.ts

@@ -836,7 +836,7 @@ export function createEnumStyle<T>(values: T) {
         enumClass[field] = value;
         // Add Reverse lookup
         if (!isUndefined(enumClass[value])) {
-            throwError("Value: [" + value + "] already exists for " + field);
+            throwError("[" + value + "] exists for " + field);
         }
         enumClass[value] = field;
     });

package/src/JavaScriptSDK/ProcessTelemetryContext.ts

@@ -55,12 +55,25 @@ function _getNextProxyStart(proxy: ITelemetryPluginChain, config: IConfiguration
     return createTelemetryProxyChain([startAt], config, core);
 }
 
+/**
+ * @ignore
+ * @param telemetryChain
+ * @param config
+ * @param core
+ * @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
+ * @returns
+ */
 function _createInternalContext<T extends IBaseProcessingContext>(telemetryChain: ITelemetryPluginChain, config: IConfiguration, core:IAppInsightsCore, startAt?: IPlugin): IInternalContext<T> {
     // We have a special case where we want to start execution from this specific plugin
     // or we simply reuse the existing telemetry plugin chain (normal execution case)
-    let _nextProxy: ITelemetryPluginChain = startAt ? _getNextProxyStart(telemetryChain, config, core, startAt) : telemetryChain;
+    let _nextProxy: ITelemetryPluginChain = null;  // By Default set as no next plugin
     let _onComplete: OnCompleteCallback[] = [];
 
+    if (startAt !== null) {
+        // There is no next element (null) vs not defined (undefined) so use the full chain
+        _nextProxy = startAt ? _getNextProxyStart(telemetryChain, config, core, startAt) : telemetryChain;
+    }
+
     let context: IInternalContext<T> = {
         _next: _moveNext,
         ctx: {
@@ -192,9 +205,9 @@ function _createInternalContext<T extends IBaseProcessingContext>(telemetryChain
  * @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 function createProcessTelemetryContext(telemetryChain: ITelemetryPluginChain, config: IConfiguration, core:IAppInsightsCore, startAt?: IPlugin): IProcessTelemetryContext {
-
     let internalContext: IInternalContext<IProcessTelemetryContext> = _createInternalContext<IProcessTelemetryContext>(telemetryChain, config, core, startAt);
     let context = internalContext.ctx;
 
@@ -225,6 +238,7 @@ export function createProcessTelemetryContext(telemetryChain: ITelemetryPluginCh
  * @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 function createProcessTelemetryUnloadContext(telemetryChain: ITelemetryPluginChain, config: IConfiguration, core:IAppInsightsCore, startAt?: IPlugin): IProcessTelemetryUnloadContext {
     let internalContext: IInternalContext<IProcessTelemetryUnloadContext> = _createInternalContext<IProcessTelemetryUnloadContext>(telemetryChain, config, core, startAt);

package/src/JavaScriptSDK/UnloadHandlerContainer.ts

@@ -0,0 +1,44 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import { eLoggingSeverity, _eInternalMessageId } from "../JavaScriptSDK.Enums/LoggingEnums";
+import { IProcessTelemetryUnloadContext } from "../JavaScriptSDK.Interfaces/IProcessTelemetryContext";
+import { ITelemetryUnloadState } from "../JavaScriptSDK.Interfaces/ITelemetryUnloadState";
+import { dumpObj } from "./EnvUtils";
+import { arrForEach } from "./HelperFuncs";
+
+export type UnloadHandler = (itemCtx: IProcessTelemetryUnloadContext, unloadState: ITelemetryUnloadState) => void;
+
+export interface IUnloadHandlerContainer {
+    add: (handler: UnloadHandler) => void;
+    run: (itemCtx: IProcessTelemetryUnloadContext, unloadState: ITelemetryUnloadState) => void
+}
+
+export function createUnloadHandlerContainer() {
+    let handlers: UnloadHandler[] = [];
+
+    function _addHandler(handler: UnloadHandler) {
+        if (handler) {
+            handlers.push(handler);
+        }
+    }
+
+    function _runHandlers(unloadCtx: IProcessTelemetryUnloadContext, unloadState: ITelemetryUnloadState) {
+        arrForEach(handlers, (handler) => {
+            try {
+                handler(unloadCtx, unloadState);
+            } catch (e) {
+                unloadCtx.diagLog().throwInternal(
+                    eLoggingSeverity.WARNING,
+                    _eInternalMessageId.PluginException,
+                    "Unexpected error calling unload handler - " + dumpObj(e));
+            }
+        });
+        handlers = [];
+    }
+
+    return {
+        add: _addHandler,
+        run: _runHandlers
+    }
+}

package/src/JavaScriptSDK.Enums/SendRequestReason.ts

@@ -38,6 +38,11 @@ export 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

package/src/JavaScriptSDK.Enums/TelemetryUnloadReason.ts

@@ -13,15 +13,15 @@
     /**
      * Just this plugin is being removed
      */
-    //PluginUnload = 1,
+    PluginUnload = 1,
 
     /**
      * This instance of the plugin is being removed and replaced
      */
-    //PluginReplace = 2,
+    PluginReplace = 2,
 
     /**
      * The entire SDK is being unloaded
      */
-    //SdkUnload = 50
+    SdkUnload = 50
 }

package/src/JavaScriptSDK.Interfaces/IAppInsightsCore.ts

@@ -2,7 +2,7 @@
 // Licensed under the MIT License.
 import { ITelemetryItem } from "./ITelemetryItem";
 import { IChannelControls } from "./IChannelControls";
-import { IPlugin } from "./ITelemetryPlugin";
+import { IPlugin, ITelemetryPlugin } from "./ITelemetryPlugin";
 import { IConfiguration } from "./IConfiguration";
 import { INotificationManager } from "./INotificationManager";
 import { INotificationListener } from "./INotificationListener";
@@ -11,6 +11,7 @@ import { IProcessTelemetryContext } from "./IProcessTelemetryContext";
 import { IPerfManagerProvider } from "./IPerfManager";
 import { ICookieMgr } from "./ICookieMgr";
 import { ITelemetryInitializerHandler, TelemetryInitializerFunction } from "./ITelemetryInitializers";
+import { UnloadHandler } from "../applicationinsights-core-js";
 
 export interface ILoadedPlugin<T extends IPlugin> {
     plugin: T;
@@ -29,6 +30,8 @@ export interface ILoadedPlugin<T extends IPlugin> {
      * (unless it's also been re-initialized)
      */
     setEnabled: (isEnabled: boolean) => void;
+
+    remove: (isAsync?: boolean, removeCb?: (removed?: boolean) => void) => void;
 }
 
 export interface IAppInsightsCore extends IPerfManagerProvider {
@@ -106,14 +109,38 @@ export interface IAppInsightsCore extends IPerfManagerProvider {
      */
     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;
+ }

package/types/JavaScriptSDK/BaseCore.d.ts

@@ -1,6 +1,6 @@
 import { IAppInsightsCore, ILoadedPlugin } from "../JavaScriptSDK.Interfaces/IAppInsightsCore";
 import { IConfiguration } from "../JavaScriptSDK.Interfaces/IConfiguration";
-import { IPlugin } from "../JavaScriptSDK.Interfaces/ITelemetryPlugin";
+import { IPlugin, ITelemetryPlugin } from "../JavaScriptSDK.Interfaces/ITelemetryPlugin";
 import { IChannelControls } from "../JavaScriptSDK.Interfaces/IChannelControls";
 import { ITelemetryItem } from "../JavaScriptSDK.Interfaces/ITelemetryItem";
 import { INotificationManager } from "../JavaScriptSDK.Interfaces/INotificationManager";
@@ -10,6 +10,7 @@ import { IProcessTelemetryContext } from "../JavaScriptSDK.Interfaces/IProcessTe
 import { IPerfManager } from "../JavaScriptSDK.Interfaces/IPerfManager";
 import { ICookieMgr } from "../JavaScriptSDK.Interfaces/ICookieMgr";
 import { ITelemetryInitializerHandler, TelemetryInitializerFunction } from "../JavaScriptSDK.Interfaces/ITelemetryInitializers";
+import { UnloadHandler } from "./UnloadHandlerContainer";
 export declare class BaseCore implements IAppInsightsCore {
     static defaultConfig: IConfiguration;
     config: IConfiguration;
@@ -60,10 +61,25 @@ 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?: () => void): 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;
 }

package/types/JavaScriptSDK/BaseTelemetryPlugin.d.ts

@@ -5,6 +5,7 @@ import { IPlugin, ITelemetryPlugin } from "../JavaScriptSDK.Interfaces/ITelemetr
 import { ITelemetryItem } from "../JavaScriptSDK.Interfaces/ITelemetryItem";
 import { IProcessTelemetryContext, IProcessTelemetryUnloadContext } from "../JavaScriptSDK.Interfaces/IProcessTelemetryContext";
 import { ITelemetryPluginChain } from "../JavaScriptSDK.Interfaces/ITelemetryPluginChain";
+import { UnloadHandler } from "./UnloadHandlerContainer";
 import { IInstrumentHook } from "../JavaScriptSDK.Interfaces/IInstrumentHooks";
 import { ITelemetryUnloadState } from "../JavaScriptSDK.Interfaces/ITelemetryUnloadState";
 /**
@@ -73,6 +74,11 @@ export declare abstract class BaseTelemetryPlugin implements ITelemetryPlugin {
      */
     teardown(unloadCtx?: IProcessTelemetryUnloadContext, unloadState?: ITelemetryUnloadState): void | boolean;
     abstract processTelemetry(env: ITelemetryItem, itemCtx?: IProcessTelemetryContext): void;
+    /**
+     * 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

package/types/JavaScriptSDK/ProcessTelemetryContext.d.ts

@@ -10,6 +10,7 @@ import { IDiagnosticLogger } from "../JavaScriptSDK.Interfaces/IDiagnosticLogger
  * @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;
 /**
@@ -17,6 +18,7 @@ export declare function createProcessTelemetryContext(telemetryChain: ITelemetry
  * @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 createProcessTelemetryUnloadContext(telemetryChain: ITelemetryPluginChain, config: IConfiguration, core: IAppInsightsCore, startAt?: IPlugin): IProcessTelemetryUnloadContext;
 /**

package/types/JavaScriptSDK/UnloadHandlerContainer.d.ts

@@ -0,0 +1,11 @@
+import { IProcessTelemetryUnloadContext } from "../JavaScriptSDK.Interfaces/IProcessTelemetryContext";
+import { ITelemetryUnloadState } from "../JavaScriptSDK.Interfaces/ITelemetryUnloadState";
+export declare type UnloadHandler = (itemCtx: IProcessTelemetryUnloadContext, unloadState: ITelemetryUnloadState) => void;
+export interface IUnloadHandlerContainer {
+    add: (handler: UnloadHandler) => void;
+    run: (itemCtx: IProcessTelemetryUnloadContext, unloadState: ITelemetryUnloadState) => void;
+}
+export declare function createUnloadHandlerContainer(): {
+    add: (handler: UnloadHandler) => void;
+    run: (unloadCtx: IProcessTelemetryUnloadContext, unloadState: ITelemetryUnloadState) => void;
+};

package/types/JavaScriptSDK.Enums/SendRequestReason.d.ts

@@ -30,6 +30,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
      */

package/types/JavaScriptSDK.Enums/TelemetryUnloadReason.d.ts

@@ -5,5 +5,17 @@ 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
 }

package/types/JavaScriptSDK.Interfaces/IAppInsightsCore.d.ts

@@ -1,6 +1,6 @@
 import { ITelemetryItem } from "./ITelemetryItem";
 import { IChannelControls } from "./IChannelControls";
-import { IPlugin } from "./ITelemetryPlugin";
+import { IPlugin, ITelemetryPlugin } from "./ITelemetryPlugin";
 import { IConfiguration } from "./IConfiguration";
 import { INotificationManager } from "./INotificationManager";
 import { INotificationListener } from "./INotificationListener";
@@ -9,6 +9,7 @@ import { IProcessTelemetryContext } from "./IProcessTelemetryContext";
 import { IPerfManagerProvider } from "./IPerfManager";
 import { ICookieMgr } from "./ICookieMgr";
 import { ITelemetryInitializerHandler, TelemetryInitializerFunction } from "./ITelemetryInitializers";
+import { UnloadHandler } from "../applicationinsights-core-js";
 export interface ILoadedPlugin<T extends IPlugin> {
     plugin: T;
     /**
@@ -24,6 +25,7 @@ export interface ILoadedPlugin<T extends IPlugin> {
      * (unless it's also been re-initialized)
      */
     setEnabled: (isEnabled: boolean) => void;
+    remove: (isAsync?: boolean, removeCb?: (removed?: boolean) => void) => void;
 }
 export interface IAppInsightsCore extends IPerfManagerProvider {
     config: IConfiguration;
@@ -72,13 +74,34 @@ export 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;
 }

package/types/applicationinsights-core-js.d.ts

@@ -36,4 +36,5 @@ export { IDbgExtension } from "./JavaScriptSDK.Interfaces/IDbgExtension";
 export { getDebugListener, getDebugExt } from "./JavaScriptSDK/DbgExtensionUtils";
 export { TelemetryInitializerFunction, ITelemetryInitializerHandler, ITelemetryInitializerContainer } from "./JavaScriptSDK.Interfaces/ITelemetryInitializers";
 export { createUniqueNamespace } from "./JavaScriptSDK/DataCacheHelper";
+export { UnloadHandler, IUnloadHandlerContainer, createUnloadHandlerContainer } from "./JavaScriptSDK/UnloadHandlerContainer";
 export { ITelemetryUnloadState } from "./JavaScriptSDK.Interfaces/ITelemetryUnloadState";