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

package/dist/applicationinsights-web.d.ts

@@ -1,5 +1,5 @@
 /*
- * Microsoft.ApplicationInsights, 2.8.0-beta.2203-02
+ * Microsoft.ApplicationInsights, 2.8.0-beta.2203-03
  * Copyright (c) Microsoft and contributors. All rights reserved.
  *
  * Microsoft Application Insights Team
@@ -417,11 +417,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;
     }
 
@@ -491,6 +506,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
@@ -1050,15 +1070,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 IAppInsightsDeprecated {
@@ -2736,6 +2777,7 @@ declare namespace ApplicationInsights {
          * (unless it's also been re-initialized)
          */
         setEnabled: (isEnabled: boolean) => void;
+        remove: (isAsync?: boolean, removeCb?: (removed?: boolean) => void) => void;
     }
 
     interface ILocation {
@@ -4604,6 +4646,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
          */
@@ -4789,7 +4835,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
     }
 
     class Trace extends MessageData implements ISerializable {
@@ -4809,6 +4867,8 @@ declare namespace ApplicationInsights {
         });
     }
 
+    type UnloadHandler = (itemCtx: IProcessTelemetryUnloadContext, unloadState: ITelemetryUnloadState) => void;
+
     const Util: IUtil;
 
     interface XDomainRequest extends XMLHttpRequestEventTarget {

package/dist/applicationinsights-web.js

@@ -1,5 +1,5 @@
 /*!
- * Application Insights JavaScript SDK - Web, 2.8.0-beta.2203-02
+ * Application Insights JavaScript SDK - Web, 2.8.0-beta.2203-03
  * Copyright (c) Microsoft and contributors. All rights reserved.
  */
 (function (global, factory) {
@@ -813,7 +813,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;
         });
@@ -1642,8 +1642,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: {
@@ -2359,6 +2362,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() {
@@ -2366,6 +2393,7 @@
             var _isinitialized;
             var _rootCtx;
             var _nextPlugin;
+            var _unloadHandlerContainer;
             var _hooks;
             _initDefaults();
             dynamicProto(BaseTelemetryPlugin, _self, function (_self) {
@@ -2387,6 +2415,7 @@
                     function _unloadCallback() {
                         if (!unloadDone) {
                             unloadDone = true;
+                            _unloadHandlerContainer.run(theUnloadCtx, unloadState);
                             arrForEach(_hooks, function (fn) {
                                 fn.rm();
                             });
@@ -2415,6 +2444,7 @@
                         }
                     }
                 };
+                proxyFunctionAs(_self, "_addUnloadCb", function () { return _unloadHandlerContainer; }, "add");
             });
             _self.diagLog = function (itemCtx) {
                 return _getTelCtx(itemCtx).diagLog();
@@ -2471,6 +2501,7 @@
                 _rootCtx = null;
                 _nextPlugin = null;
                 _hooks = [];
+                _unloadHandlerContainer = createUnloadHandlerContainer();
             }
         }
         return BaseTelemetryPlugin;
@@ -2540,6 +2571,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);
     }
@@ -2569,6 +2602,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 = {},
@@ -2593,15 +2636,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");
                     }
@@ -2614,8 +2662,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;
                     }
@@ -2640,7 +2687,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 {
@@ -2655,14 +2702,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 () {
@@ -2719,10 +2766,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  });
@@ -2740,8 +2857,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);
@@ -2794,6 +2913,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);
+                                });
                             }
                         };
                     }
@@ -2809,6 +2942,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) {
@@ -2843,6 +3016,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;
@@ -5818,7 +6004,7 @@
             config.disableFlushOnUnload = stringToBoolOrDefault(config.disableFlushOnUnload, config.disableFlushOnBeforeUnload);
             return config;
         };
-        ApplicationInsights.Version = "2.8.0-beta.2203-02";
+        ApplicationInsights.Version = "2.8.0-beta.2203-03";
         return ApplicationInsights;
     }(BaseTelemetryPlugin));
     var Timing = /** @class */ (function () {
@@ -6125,7 +6311,7 @@
         }
     }
     var EnvelopeCreator = {
-        Version: "2.8.0-beta.2203-02"
+        Version: "2.8.0-beta.2203-03"
     };
     function DependencyEnvelopeCreator(logger, telemetryItem, customUndefinedValue) {
         EnvelopeCreatorInit(logger, telemetryItem);
@@ -7394,7 +7580,7 @@
         return Device;
     }());
 
-    var Version = "2.8.0-beta.2203-02";
+    var Version = "2.8.0-beta.2203-03";
     var Internal = /** @class */ (function () {
         function Internal(config) {
             this.sdkVersion = (config.sdkExtension && config.sdkExtension() ? config.sdkExtension() + "_" : "") + "javascript:" + Version;