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

package/dist/applicationinsights-core-js.api.md

@@ -60,7 +60,10 @@ export function attachEvent(obj: any, eventNameWithoutOn: string, handlerRef: an
 export class BaseCore implements IAppInsightsCore {
     constructor();
     addNotificationListener(listener: INotificationListener): void;
+    // (undocumented)
+    addPlugin<T extends IPlugin = ITelemetryPlugin>(plugin: T, replaceExisting: boolean, doAsync: boolean, addCb?: (added?: boolean) => void): void;
     addTelemetryInitializer(telemetryInitializer: TelemetryInitializerFunction): ITelemetryInitializerHandler | void;
+    addUnloadCb(handler: UnloadHandler): void;
     // (undocumented)
     config: IConfiguration;
     // (undocumented)
@@ -99,12 +102,14 @@ export class BaseCore implements IAppInsightsCore {
     stopPollingInternalLogs(): void;
     // (undocumented)
     track(telemetryItem: ITelemetryItem): void;
+    unload(isAsync?: boolean, unloadComplete?: () => void): void;
 }
 
 // @public
 export abstract class BaseTelemetryPlugin implements ITelemetryPlugin {
     constructor();
     protected _addHook(hooks: IInstrumentHook | IInstrumentHook[]): void;
+    protected _addUnloadCb(handler: UnloadHandler): void;
     core: IAppInsightsCore;
     diagLog: (itemCtx?: IProcessTelemetryContext) => IDiagnosticLogger;
     // Warning: (ae-forgotten-export) The symbol "IProcessTelemetryUnloadContext" needs to be exported by the entry point applicationinsights-core-js.d.ts
@@ -148,6 +153,12 @@ export function createProcessTelemetryContext(telemetryChain: ITelemetryPluginCh
 // @public (undocumented)
 export function createUniqueNamespace(name: string, includeVersion?: boolean): string;
 
+// @public (undocumented)
+export function createUnloadHandlerContainer(): {
+    add: (handler: UnloadHandler) => void;
+    run: (unloadCtx: IProcessTelemetryUnloadContext, unloadState: ITelemetryUnloadState) => void;
+};
+
 // @public
 export function dateNow(): number;
 
@@ -466,7 +477,9 @@ export function hasWindow(): boolean;
 // @public (undocumented)
 export interface IAppInsightsCore extends IPerfManagerProvider {
     addNotificationListener?(listener: INotificationListener): void;
+    addPlugin<T extends IPlugin = ITelemetryPlugin>(plugin: T, replaceExisting: boolean, doAsync: boolean, addCb?: (added?: boolean) => void): void;
     addTelemetryInitializer(telemetryInitializer: TelemetryInitializerFunction): ITelemetryInitializerHandler | void;
+    addUnloadCb(handler: UnloadHandler): void;
     // (undocumented)
     config: IConfiguration;
     evtNamespace(): string;
@@ -489,6 +502,7 @@ export interface IAppInsightsCore extends IPerfManagerProvider {
     stopPollingInternalLogs?(): void;
     // (undocumented)
     track(telemetryItem: ITelemetryItem): void;
+    unload(isAsync?: boolean, unloadComplete?: () => void): void;
 }
 
 // @public
@@ -995,6 +1009,14 @@ export interface ITelemetryUnloadState {
     reason: TelemetryUnloadReason;
 }
 
+// @public (undocumented)
+export interface IUnloadHandlerContainer {
+    // (undocumented)
+    add: (handler: UnloadHandler) => void;
+    // (undocumented)
+    run: (itemCtx: IProcessTelemetryUnloadContext, unloadState: ITelemetryUnloadState) => void;
+}
+
 // @public
 export function _legacyCookieMgr(config?: IConfiguration, logger?: IDiagnosticLogger): ICookieMgr;
 
@@ -1158,6 +1180,7 @@ export const enum SendRequestReason {
     NormalSchedule = 1,
     Resumed = 4,
     Retry = 5,
+    SdkUnload = 6,
     SyncEvent = 3,
     Undefined = 0,
     Unload = 2
@@ -1225,6 +1248,9 @@ export function uaDisallowsSameSiteNone(userAgent: string): boolean;
 // @public (undocumented)
 export const Undefined = "undefined";
 
+// @public (undocumented)
+export type UnloadHandler = (itemCtx: IProcessTelemetryUnloadContext, unloadState: ITelemetryUnloadState) => void;
+
 // @public (undocumented)
 export function useXDomainRequest(): boolean | undefined;
 

package/dist/applicationinsights-core-js.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-03
  * Copyright (c) Microsoft and contributors. All rights reserved.
  *
  * Microsoft Application Insights Team
@@ -189,11 +189,26 @@ declare namespace ApplicationInsights {
          * @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;
     }
 
@@ -263,6 +278,11 @@ declare namespace ApplicationInsights {
          */
         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
@@ -305,11 +325,17 @@ declare namespace ApplicationInsights {
      * @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
      */
     function createProcessTelemetryContext(telemetryChain: ITelemetryPluginChain, config: IConfiguration, core: IAppInsightsCore, startAt?: IPlugin): IProcessTelemetryContext;
 
     function createUniqueNamespace(name: string, includeVersion?: boolean): string;
 
+    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
@@ -781,15 +807,36 @@ declare namespace ApplicationInsights {
          * 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;
     }
 
     interface IBaseProcessingContext {
@@ -1491,6 +1538,7 @@ declare namespace ApplicationInsights {
          * (unless it's also been re-initialized)
          */
         setEnabled: (isEnabled: boolean) => void;
+        remove: (isAsync?: boolean, removeCb?: (removed?: boolean) => void) => void;
     }
 
     /**
@@ -2102,6 +2150,11 @@ declare namespace ApplicationInsights {
         flushComplete?: boolean;
     }
 
+    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.
@@ -2522,6 +2575,10 @@ declare namespace ApplicationInsights {
          * The event(s) being sent as a retry
          */
         Retry = 5,
+        /**
+         * The SDK is unloading
+         */
+        SdkUnload = 6,
         /**
          * Maximum batch size would be exceeded
          */
@@ -2617,7 +2674,19 @@ declare namespace ApplicationInsights {
         /**
          * 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
     }
 
     function throwError(message: string): never;
@@ -2631,6 +2700,8 @@ declare namespace ApplicationInsights {
 
     const Undefined = "undefined";
 
+    type UnloadHandler = (itemCtx: IProcessTelemetryUnloadContext, unloadState: ITelemetryUnloadState) => void;
+
     function useXDomainRequest(): boolean | undefined;
 
     

package/dist/applicationinsights-core-js.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-03
  * Copyright (c) Microsoft and contributors. All rights reserved.
  */
 (function (global, factory) {
@@ -833,7 +833,7 @@
         objForEachKey(values, function (field, value) {
             enumClass[field] = value;
             if (!isUndefined(enumClass[value])) {
-                throwError("Value: [" + value + "] already exists for " + field);
+                throwError("[" + value + "] exists for " + field);
             }
             enumClass[value] = field;
         });
@@ -1676,8 +1676,11 @@
         return createTelemetryProxyChain([startAt], config, core);
     }
     function _createInternalContext(telemetryChain, config, core, startAt) {
-        var _nextProxy = startAt ? _getNextProxyStart(telemetryChain, config, core, startAt) : telemetryChain;
+        var _nextProxy = null;
         var _onComplete = [];
+        if (startAt !== null) {
+            _nextProxy = startAt ? _getNextProxyStart(telemetryChain, config, core, startAt) : telemetryChain;
+        }
         var context = {
             _next: _moveNext,
             ctx: {
@@ -2401,6 +2404,30 @@
         return channelQueue;
     }
 
+    function createUnloadHandlerContainer() {
+        var handlers = [];
+        function _addHandler(handler) {
+            if (handler) {
+                handlers.push(handler);
+            }
+        }
+        function _runHandlers(unloadCtx, unloadState) {
+            arrForEach(handlers, function (handler) {
+                try {
+                    handler(unloadCtx, unloadState);
+                }
+                catch (e) {
+                    unloadCtx.diagLog().throwInternal(2 , 73 , "Unexpected error calling unload handler - " + dumpObj(e));
+                }
+            });
+            handlers = [];
+        }
+        return {
+            add: _addHandler,
+            run: _runHandlers
+        };
+    }
+
     var strGetPlugin = "getPlugin";
     var BaseTelemetryPlugin = /** @class */ (function () {
         function BaseTelemetryPlugin() {
@@ -2408,6 +2435,7 @@
             var _isinitialized;
             var _rootCtx;
             var _nextPlugin;
+            var _unloadHandlerContainer;
             var _hooks;
             _initDefaults();
             dynamicProto(BaseTelemetryPlugin, _self, function (_self) {
@@ -2429,6 +2457,7 @@
                     function _unloadCallback() {
                         if (!unloadDone) {
                             unloadDone = true;
+                            _unloadHandlerContainer.run(theUnloadCtx, unloadState);
                             arrForEach(_hooks, function (fn) {
                                 fn.rm();
                             });
@@ -2457,6 +2486,7 @@
                         }
                     }
                 };
+                proxyFunctionAs(_self, "_addUnloadCb", function () { return _unloadHandlerContainer; }, "add");
             });
             _self.diagLog = function (itemCtx) {
                 return _getTelCtx(itemCtx).diagLog();
@@ -2513,6 +2543,7 @@
                 _rootCtx = null;
                 _nextPlugin = null;
                 _hooks = [];
+                _unloadHandlerContainer = createUnloadHandlerContainer();
             }
         }
         return BaseTelemetryPlugin;
@@ -2582,6 +2613,8 @@
 
     var strValidationError = "Plugins must provide initialize method";
     var strNotificationManager = "_notificationManager";
+    var strSdkUnloadingError = "SDK is still unloading...";
+    var strSdkNotInitialized = "SDK is not initialized";
     function _createPerfManager(core, notificationMgr) {
         return new PerfManager(notificationMgr);
     }
@@ -2611,6 +2644,16 @@
             core: coreExtensions
         };
     }
+    function _isPluginPresent(thePlugin, plugins) {
+        var exists = false;
+        arrForEach(plugins, function (plugin) {
+            if (plugin === thePlugin) {
+                exists = true;
+                return -1;
+            }
+        });
+        return exists;
+    }
     function _createDummyNotificationManager() {
         var _a;
         return objCreateFn((_a = {},
@@ -2635,15 +2678,20 @@
             var _channelControl;
             var _channelConfig;
             var _channelQueue;
+            var _isUnloading;
             var _telemetryInitializerPlugin;
             var _internalLogsEventName;
             var _evtNamespace;
+            var _unloadHandlers;
             var _debugListener;
             var _internalLogPoller = 0;
             dynamicProto(BaseCore, this, function (_self) {
                 _initDefaults();
                 _self.isInitialized = function () { return _isInitialized; };
                 _self.initialize = function (config, extensions, logger, notificationManager) {
+                    if (_isUnloading) {
+                        throwError(strSdkUnloadingError);
+                    }
                     if (_self.isInitialized()) {
                         throwError("Core should not be initialized more than once");
                     }
@@ -2656,8 +2704,7 @@
                     _initDebugListener(config);
                     _initPerfManager(config);
                     config.extensions = isNullOrUndefined(config.extensions) ? [] : config.extensions;
-                    var extConfig = getSetValue(config, strExtensionConfig);
-                    extConfig.NotificationManager = notificationManager;
+                    _initExtConfig(config);
                     if (logger) {
                         _self.logger = logger;
                     }
@@ -2682,7 +2729,7 @@
                     setValue(telemetryItem, strIKey, _self.config.instrumentationKey, null, isNotTruthy);
                     setValue(telemetryItem, "time", toISOString(new Date()), null, isNotTruthy);
                     setValue(telemetryItem, "ver", "4.0", null, isNullOrUndefined);
-                    if (_self.isInitialized()) {
+                    if (!_isUnloading && _self.isInitialized()) {
                         _createTelCtx().processNext(telemetryItem);
                     }
                     else {
@@ -2697,14 +2744,14 @@
                     }
                     return _notificationManager;
                 };
-                _self.addNotificationListener = function (listener) {
+                _self[strAddNotificationListener] = function (listener) {
                     if (_notificationManager) {
-                        _notificationManager.addNotificationListener(listener);
+                        _notificationManager[strAddNotificationListener](listener);
                     }
                 };
-                _self.removeNotificationListener = function (listener) {
+                _self[strRemoveNotificationListener] = function (listener) {
                     if (_notificationManager) {
-                        _notificationManager.removeNotificationListener(listener);
+                        _notificationManager[strRemoveNotificationListener](listener);
                     }
                 };
                 _self.getCookieMgr = function () {
@@ -2761,10 +2808,80 @@
                     }
                 };
                 proxyFunctions(_self, function () { return _telemetryInitializerPlugin; }, ["addTelemetryInitializer"]);
+                _self.unload = function (isAsync, unloadComplete, cbTimeout) {
+                    if (isAsync === void 0) { isAsync = true; }
+                    if (!_isInitialized) {
+                        throwError(strSdkNotInitialized);
+                    }
+                    if (_isUnloading) {
+                        throwError(strSdkUnloadingError);
+                    }
+                    var unloadState = {
+                        reason: 50 ,
+                        isAsync: isAsync,
+                        flushComplete: false
+                    };
+                    var processUnloadCtx = createProcessTelemetryUnloadContext(_getPluginChain(), _self.config, _self);
+                    processUnloadCtx.onComplete(function () {
+                        _initDefaults();
+                        unloadComplete && unloadComplete(unloadState);
+                    }, _self);
+                    function _doUnload(flushComplete) {
+                        unloadState.flushComplete = flushComplete;
+                        _isUnloading = true;
+                        _unloadHandlers.run(processUnloadCtx, unloadState);
+                        _self.stopPollingInternalLogs();
+                        processUnloadCtx.processNext(unloadState);
+                    }
+                    if (_channelControl) {
+                        _channelControl.flush(isAsync, _doUnload, 6 , cbTimeout);
+                    }
+                    else {
+                        _doUnload(true);
+                    }
+                };
                 _self.getPlugin = _getPlugin;
+                _self.addPlugin = function (plugin, replaceExisting, isAsync, addCb) {
+                    if (isAsync === void 0) { isAsync = true; }
+                    if (!plugin) {
+                        addCb && addCb(false);
+                        _logOrThrowError(strValidationError);
+                        return;
+                    }
+                    var existingPlugin = _getPlugin(plugin.identifier);
+                    if (existingPlugin && !replaceExisting) {
+                        addCb && addCb(false);
+                        _logOrThrowError("Plugin [" + plugin.identifier + "] is already loaded!");
+                        return;
+                    }
+                    function _addPlugin(removed) {
+                        _configExtensions.push(plugin);
+                        _initPluginChain(_self.config);
+                        addCb && addCb(true);
+                    }
+                    if (existingPlugin) {
+                        var removedPlugins = [existingPlugin.plugin];
+                        var unloadState = {
+                            reason: 2 ,
+                            isAsync: isAsync
+                        };
+                        _removePlugins(removedPlugins, unloadState, function (removed) {
+                            if (!removed) {
+                                addCb && addCb(false);
+                            }
+                            else {
+                                _addPlugin();
+                            }
+                        });
+                    }
+                    else {
+                        _addPlugin();
+                    }
+                };
                 _self.evtNamespace = function () {
                     return _evtNamespace;
                 };
+                proxyFunctionAs(_self, "addUnloadCb", function () { return _unloadHandlers; }, "add");
                 function _initDefaults() {
                     _isInitialized = false;
                     _self.logger = new DiagnosticLogger({ loggingLevelConsole: 1  });
@@ -2782,8 +2899,10 @@
                     _channelControl = null;
                     _channelConfig = null;
                     _channelQueue = null;
+                    _isUnloading = false;
                     _internalLogsEventName = null;
                     _evtNamespace = createUniqueNamespace("AIBaseCore", true);
+                    _unloadHandlers = createUnloadHandlerContainer();
                 }
                 function _createTelCtx() {
                     return createProcessTelemetryContext(_getPluginChain(), _self.config, _self);
@@ -2836,6 +2955,20 @@
                             isEnabled: function () {
                                 var pluginState = _getPluginState(thePlugin);
                                 return !pluginState[strTeardown] && !pluginState[strDisabled];
+                            },
+                            remove: function (isAsync, removeCb) {
+                                if (isAsync === void 0) { isAsync = true; }
+                                var pluginsToRemove = [thePlugin];
+                                var unloadState = {
+                                    reason: 1 ,
+                                    isAsync: isAsync
+                                };
+                                _removePlugins(pluginsToRemove, unloadState, function (removed) {
+                                    if (removed) {
+                                        _initPluginChain(_self.config);
+                                    }
+                                    removeCb && removeCb(removed);
+                                });
                             }
                         };
                     }
@@ -2851,6 +2984,46 @@
                     }
                     return _pluginChain;
                 }
+                function _removePlugins(thePlugins, unloadState, removeComplete) {
+                    if (thePlugins && thePlugins.length > 0) {
+                        var unloadChain = createTelemetryProxyChain(thePlugins, _self.config, _self);
+                        var unloadCtx = createProcessTelemetryUnloadContext(unloadChain, _self.config, _self);
+                        unloadCtx.onComplete(function () {
+                            var removed = false;
+                            var newConfigExtensions = [];
+                            arrForEach(_configExtensions, function (plugin, idx) {
+                                if (!_isPluginPresent(plugin, thePlugins)) {
+                                    newConfigExtensions.push(plugin);
+                                }
+                                else {
+                                    removed = true;
+                                }
+                            });
+                            _configExtensions = newConfigExtensions;
+                            var newChannelConfig = [];
+                            if (_channelConfig) {
+                                arrForEach(_channelConfig, function (queue, idx) {
+                                    var newQueue = [];
+                                    arrForEach(queue, function (channel) {
+                                        if (!_isPluginPresent(channel, thePlugins)) {
+                                            newQueue.push(channel);
+                                        }
+                                        else {
+                                            removed = true;
+                                        }
+                                    });
+                                    newChannelConfig.push(newQueue);
+                                });
+                                _channelConfig = newChannelConfig;
+                            }
+                            removeComplete && removeComplete(removed);
+                        });
+                        unloadCtx.processNext(unloadState);
+                    }
+                    else {
+                        removeComplete(false);
+                    }
+                }
                 function _flushInternalLogs() {
                     var queue = _self.logger ? _self.logger.queue : [];
                     if (queue) {
@@ -2885,6 +3058,19 @@
                         setValue(_self.config, "createPerfMgr", _createPerfManager);
                     }
                 }
+                function _initExtConfig(config) {
+                    var extConfig = getSetValue(config, strExtensionConfig);
+                    extConfig.NotificationManager = _notificationManager;
+                }
+                function _logOrThrowError(message) {
+                    var logger = _self.logger;
+                    if (logger) {
+                        logger.throwInternal(2 , 73 , message);
+                    }
+                    else {
+                        throwError(message);
+                    }
+                }
             });
         }
         return BaseCore;
@@ -3699,6 +3885,7 @@
     exports.createEnumStyle = createEnumStyle;
     exports.createProcessTelemetryContext = createProcessTelemetryContext;
     exports.createUniqueNamespace = createUniqueNamespace;
+    exports.createUnloadHandlerContainer = createUnloadHandlerContainer;
     exports.dateNow = dateNow;
     exports.deleteCookie = deleteCookie;
     exports.detachEvent = detachEvent;