@microsoft/applicationinsights-core-js 2.8.0-nightly.2202-06 → 2.8.0-nightly.2204-06

package/src/JavaScriptSDK.Interfaces/IProcessTelemetryContext.ts

@@ -3,17 +3,21 @@
 "use strict";
 
 import { IAppInsightsCore } from "./IAppInsightsCore";
-import { IDiagnosticLogger } from "./IDiagnosticLogger";
 import { IConfiguration } from "./IConfiguration";
+import { IDiagnosticLogger } from "./IDiagnosticLogger";
 import { ITelemetryItem } from "./ITelemetryItem";
-import { IPlugin } from "./ITelemetryPlugin";
+import { IPlugin, ITelemetryPlugin } from "./ITelemetryPlugin";
 import { ITelemetryPluginChain } from "./ITelemetryPluginChain";
+import { ITelemetryUnloadState } from "./ITelemetryUnloadState";
+import { ITelemetryUpdateState } from "./ITelemetryUpdateState";
 
-/**
- * The current context for the current call to processTelemetry(), used to support sharing the same plugin instance
- * between multiple AppInsights instances
- */
-export interface IProcessTelemetryContext {
+export const enum GetExtCfgMergeType {
+    None = 0,
+    MergeDefaultOnly = 1,
+    MergeDefaultFromRootOrDefault = 2,
+}
+
+export interface IBaseProcessingContext {
     /**
      * The current core instance for the request
      */
@@ -27,12 +31,12 @@ export interface IProcessTelemetryContext {
     /**
      * Gets the current core config instance
      */
-    getCfg: ()=> IConfiguration;
+    getCfg: () => IConfiguration;
 
     /**
      * Gets the named extension config
      */
-    getExtCfg: <T>(identifier: string, defaultValue?:T|any) => T;
+    getExtCfg: <T>(identifier: string, defaultValue?: T | any, mergeDefault?: GetExtCfgMergeType) => T;
 
     /**
      * Gets the named config from either the named identifier extension or core config if neither exist then the
@@ -41,7 +45,7 @@ export interface IProcessTelemetryContext {
      * @param field The config field name
      * @param defaultValue The default value to return if no defined config exists
      */
-    getConfig: (identifier: string, field: string, defaultValue?: number | string | boolean) => number | string | boolean;
+    getConfig: (identifier: string, field: string, defaultValue?: number | string | boolean | string[] | RegExp[] | Function) => number | string | boolean | string[] | RegExp[] | Function;
 
     /**
      * Helper to allow plugins to check and possibly shortcut executing code only
@@ -57,20 +61,96 @@ export interface IProcessTelemetryContext {
     /**
      * Helper to set the next plugin proxy
      */
-    setNext: (nextCtx:ITelemetryPluginChain) => void;
+    setNext: (nextCtx: ITelemetryPluginChain) => void;
+
+    /**
+     * Synchronously iterate over the context chain running the callback for each plugin, once
+     * every plugin has been executed via the callback, any associated onComplete will be called.
+     * @param callback - The function call for each plugin in the context chain
+     */
+    iterate: <T extends ITelemetryPlugin = ITelemetryPlugin>(callback: (plugin: T) => void) => void;
+
+    /**
+     * Set the function to call when the current chain has executed all processNext or unloadNext items.
+     * @param onComplete - The onComplete to call
+     * @param that - The "this" value to use for the onComplete call, if not provided or undefined defaults to the current context
+     * @param args - Any additional arguments to pass to the onComplete function
+     */
+    onComplete: (onComplete: () => void, that?: any, ...args: any[]) => 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) => IBaseProcessingContext;
+}
+
+/**
+ * The current context for the current call to processTelemetry(), used to support sharing the same plugin instance
+ * between multiple AppInsights instances
+ */
+export interface IProcessTelemetryContext extends IBaseProcessingContext {
     /**
      * Call back for telemetry processing before it it is sent
      * @param env - This is the current event being reported
+     * @returns boolean (true) if there is no more plugins to process otherwise false or undefined (void)
+     */
+    processNext: (env: ITelemetryItem) => 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) => IProcessTelemetryContext;
+}
+
+/**
+ * The current context for the current call to teardown() implementations, used to support when plugins are being removed
+ * or the SDK is being unloaded.
+ */
+export interface IProcessTelemetryUnloadContext extends IBaseProcessingContext {
+
+    /**
+     * This Plugin has finished unloading, so unload the next one
+     * @param uploadState - The state of the unload process
+     * @returns boolean (true) if there is no more plugins to process otherwise false or undefined (void)
+     */
+    processNext: (unloadState: ITelemetryUnloadState) => 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) => 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 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: (env: ITelemetryItem) => void;
+    processNext: (updateState: ITelemetryUpdateState) => boolean | void;
 
     /**
-     * Create a new context using the core and config from the current instance
+     * 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) => IProcessTelemetryContext;
+     createNew: (plugins?: IPlugin[] | ITelemetryPluginChain, startAt?: IPlugin) => IProcessTelemetryUpdateContext;
 }

package/src/JavaScriptSDK.Interfaces/ITelemetryInitializers.ts

@@ -0,0 +1,16 @@
+import { ITelemetryItem } from "./ITelemetryItem";
+
+export declare type TelemetryInitializerFunction = <T extends ITelemetryItem>(item: T) => boolean | void;
+
+export interface ITelemetryInitializerHandler {
+    remove(): void;
+}
+
+export interface ITelemetryInitializerContainer {
+    /**
+     * Add a telemetry processor to decorate or drop telemetry events.
+     * @param telemetryInitializer - The Telemetry Initializer function
+     * @returns - A ITelemetryInitializerHandler to enable the initializer to be removed
+     */
+    addTelemetryInitializer(telemetryInitializer: TelemetryInitializerFunction): ITelemetryInitializerHandler | void;
+}

package/src/JavaScriptSDK.Interfaces/ITelemetryPlugin.ts

@@ -5,13 +5,12 @@
 import { ITelemetryItem } from "./ITelemetryItem";
 import { IConfiguration } from "./IConfiguration";
 import { IAppInsightsCore } from "./IAppInsightsCore";
-import { IProcessTelemetryContext } from "./IProcessTelemetryContext";
+import { IProcessTelemetryContext, IProcessTelemetryUnloadContext, IProcessTelemetryUpdateContext } from "./IProcessTelemetryContext";
 import { ITelemetryPluginChain } from "./ITelemetryPluginChain";
+import { ITelemetryUnloadState } from "./ITelemetryUnloadState";
+import { ITelemetryUpdateState } from "./ITelemetryUpdateState";
 
-/**
- * Configuration provided to SDK core
- */
-export interface ITelemetryPlugin extends IPlugin {
+export interface ITelemetryProcessor {
     /**
      * Call back for telemetry processing before it it is sent
      * @param env - This is the current event being reported
@@ -20,7 +19,22 @@ export interface ITelemetryPlugin extends IPlugin {
      * 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;
+}
+
+/**
+ * Configuration provided to SDK core
+ */
+export interface ITelemetryPlugin extends ITelemetryProcessor, IPlugin {
     /**
      * Set next extension for telemetry processing, this is not optional as plugins should use the
      * processNext() function of the passed IProcessTelemetryContext instead. It is being kept for
@@ -43,7 +57,7 @@ export interface IPlugin {
      * @param pluginChain - [Optional] specifies the current plugin chain which identifies the
      * set of plugins and the order they should be executed for the current request.
      */
-    initialize: (config: IConfiguration, core: IAppInsightsCore, extensions: IPlugin[], pluginChain?:ITelemetryPluginChain) => void;
+    initialize: (config: IConfiguration, core: IAppInsightsCore, extensions: IPlugin[], pluginChain?: ITelemetryPluginChain) => void;
     
     /**
      * Returns a value that indicates whether the plugin has already been previously initialized.
@@ -52,10 +66,14 @@ export interface IPlugin {
     isInitialized?: () => boolean;
 
     /**
-     * Tear down the plugin and remove any hooked value, the plugin should remove that it is no longer initialized and
-     * therefore can be re-initialized after being torn down.
+     * Tear down the plugin and remove any hooked value, the plugin should be removed so that it is no longer initialized and
+     * therefore could be re-initialized after being torn down. The plugin should ensure that once this has been called any further
+     * processTelemetry calls are ignored and it just calls the processNext() with the provided context.
+     * @param unloadCtx - This is the context that should be used during unloading.
+     * @param unloadState - The details / state of the unload process, it holds details like whether it should be unloaded synchronously or asynchronously and the reason for the unload.
+     * @returns boolean - true if the plugin has or will call processNext(), this for backward compatibility as previously teardown was synchronous and returned nothing.
      */
-    teardown?: () => void;
+    teardown?: (unloadCtx: IProcessTelemetryUnloadContext, unloadState?: ITelemetryUnloadState) => void | boolean;
 
     /**
      * Extension name

package/src/JavaScriptSDK.Interfaces/ITelemetryPluginChain.ts

@@ -1,15 +1,14 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
-"use strict";
 
-import { ITelemetryItem } from "./ITelemetryItem";
-import { IProcessTelemetryContext } from "./IProcessTelemetryContext";
-import { ITelemetryPlugin } from "./ITelemetryPlugin";
+import { IProcessTelemetryUnloadContext } from "./IProcessTelemetryContext";
+import { ITelemetryPlugin, ITelemetryProcessor } from "./ITelemetryPlugin";
+import { ITelemetryUnloadState } from "./ITelemetryUnloadState";
 
 /**
  * Configuration provided to SDK core
  */
-export interface ITelemetryPluginChain {
+export interface ITelemetryPluginChain extends ITelemetryProcessor {
 
     /**
      * Returns the underlying plugin that is being proxied for the processTelemetry call
@@ -22,11 +21,10 @@ export interface ITelemetryPluginChain {
     getNext: () => ITelemetryPluginChain;
 
     /**
-     * Call back for telemetry processing before it it is sent
-     * @param env - This is the current event being reported
-     * @param itemCtx - This is the context for the current request, ITelemetryPlugin instances
-     * can optionally use this to access the current core instance or define / pass additional information
-     * to later plugins (vs appending items to the telemetry item)
+     * This plugin is being unloaded and should remove any hooked events and cleanup any global/scoped values, after this
+     * call the plugin will be removed from the telemetry processing chain and will no longer receive any events..
+     * @param unloadCtx - The unload context to use for this call.
+     * @param unloadState - The details of the unload operation
      */
-    processTelemetry: (env: ITelemetryItem, itemCtx:IProcessTelemetryContext) => void;
+    unload?: (unloadCtx: IProcessTelemetryUnloadContext, unloadState: ITelemetryUnloadState) => void;
 }

package/src/JavaScriptSDK.Interfaces/ITelemetryUnloadState.ts

@@ -0,0 +1,10 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import { TelemetryUnloadReason } from "../JavaScriptSDK.Enums/TelemetryUnloadReason";
+
+export interface ITelemetryUnloadState {
+    reason: TelemetryUnloadReason;
+    isAsync: boolean;
+    flushComplete?: boolean;
+}

package/src/JavaScriptSDK.Interfaces/ITelemetryUpdateState.ts

@@ -0,0 +1,34 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import { TelemetryUpdateReason } from "../JavaScriptSDK.Enums/TelemetryUpdateReason";
+//import { IConfiguration } from "./IConfiguration";
+import { IPlugin } from "./ITelemetryPlugin";
+
+export 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
+     */
+    //prvCfg?: IConfiguration,
+
+    /**
+     * If this is a configuration update is the new configuration that is being used
+     */
+    //newCfg?: IConfiguration,
+
+    /**
+     * 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[]
+}

package/src/JavaScriptSDK.Interfaces/IUnloadableComponent.ts

@@ -0,0 +1,17 @@
+import { IProcessTelemetryUnloadContext } from "./IProcessTelemetryContext";
+import { ITelemetryUnloadState } from "./ITelemetryUnloadState";
+
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+export interface IUnloadableComponent {
+    /**
+    * Teardown / Unload hook to allow implementations to perform some additional unload operations before the BaseTelemetryPlugin
+    * finishes it's removal.
+    * @param unloadCtx - This is the context that should be used during unloading.
+    * @param unloadState - The details / state of the unload process, it holds details like whether it should be unloaded synchronously or asynchronously and the reason for the unload.
+    * @param asyncCallback - An optional callback that the plugin must call if it returns true to inform the caller that it has completed any async unload/teardown operations.
+    * @returns boolean - true if the plugin has or will call asyncCallback, this allows the plugin to perform any asynchronous operations.
+    */
+    _doUnload?: (unloadCtx?: IProcessTelemetryUnloadContext, unloadState?: ITelemetryUnloadState, asyncCallback?: () => void) => void | boolean;
+}

package/types/JavaScriptSDK/AppInsightsCore.d.ts

@@ -3,31 +3,10 @@ import { BaseCore } from "./BaseCore";
 import { IConfiguration } from "../JavaScriptSDK.Interfaces/IConfiguration";
 import { IPlugin } from "../JavaScriptSDK.Interfaces/ITelemetryPlugin";
 import { ITelemetryItem } from "../JavaScriptSDK.Interfaces/ITelemetryItem";
-import { INotificationListener } from "../JavaScriptSDK.Interfaces/INotificationListener";
 import { INotificationManager } from "../JavaScriptSDK.Interfaces/INotificationManager";
 import { IDiagnosticLogger } from "../JavaScriptSDK.Interfaces/IDiagnosticLogger";
 export declare class AppInsightsCore extends BaseCore implements IAppInsightsCore {
     constructor();
     initialize(config: IConfiguration, extensions: IPlugin[], logger?: IDiagnosticLogger, notificationManager?: INotificationManager): void;
     track(telemetryItem: ITelemetryItem): void;
-    /**
-     * Adds a notification listener. The SDK calls methods on the listener when an appropriate notification is raised.
-     * The added plugins must raise notifications. If the plugins do not implement the notifications, then no methods will be
-     * called.
-     * @param {INotificationListener} listener - An INotificationListener object.
-     */
-    addNotificationListener(listener: INotificationListener): void;
-    /**
-     * Removes all instances of the listener.
-     * @param {INotificationListener} listener - INotificationListener to remove.
-     */
-    removeNotificationListener(listener: INotificationListener): void;
-    /**
-     * Periodically check logger.queue for
-     */
-    pollInternalLogs(eventName?: string): number;
-    /**
-     * Periodically check logger.queue for
-     */
-    stopPollingInternalLogs(): void;
 }

package/types/JavaScriptSDK/BaseCore.d.ts

@@ -1,13 +1,19 @@
-import { IAppInsightsCore } from "../JavaScriptSDK.Interfaces/IAppInsightsCore";
+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";
+import { INotificationListener } from "../JavaScriptSDK.Interfaces/INotificationListener";
 import { IDiagnosticLogger } from "../JavaScriptSDK.Interfaces/IDiagnosticLogger";
-import { IProcessTelemetryContext } from "../JavaScriptSDK.Interfaces/IProcessTelemetryContext";
+import { IProcessTelemetryContext, IProcessTelemetryUpdateContext } from "../JavaScriptSDK.Interfaces/IProcessTelemetryContext";
 import { IPerfManager } from "../JavaScriptSDK.Interfaces/IPerfManager";
 import { ICookieMgr } from "../JavaScriptSDK.Interfaces/ICookieMgr";
+import { ITelemetryInitializerHandler, TelemetryInitializerFunction } from "../JavaScriptSDK.Interfaces/ITelemetryInitializers";
+import { UnloadHandler } from "./UnloadHandlerContainer";
+import { ITelemetryUpdateState } from "../JavaScriptSDK.Interfaces/ITelemetryUpdateState";
+import { ITelemetryUnloadState } from "../JavaScriptSDK.Interfaces/ITelemetryUnloadState";
+import { SendRequestReason } from "../JavaScriptSDK.Enums/SendRequestReason";
 export declare class BaseCore implements IAppInsightsCore {
     static defaultConfig: IConfiguration;
     config: IConfiguration;
@@ -20,6 +26,18 @@ export declare class BaseCore implements IAppInsightsCore {
     track(telemetryItem: ITelemetryItem): void;
     getProcessTelContext(): IProcessTelemetryContext;
     getNotifyMgr(): INotificationManager;
+    /**
+     * Adds a notification listener. The SDK calls methods on the listener when an appropriate notification is raised.
+     * The added plugins must raise notifications. If the plugins do not implement the notifications, then no methods will be
+     * called.
+     * @param {INotificationListener} listener - An INotificationListener object.
+     */
+    addNotificationListener(listener: INotificationListener): void;
+    /**
+     * Removes all instances of the listener.
+     * @param {INotificationListener} listener - INotificationListener to remove.
+     */
+    removeNotificationListener(listener: INotificationListener): void;
     /**
      * Get the current cookie manager for this instance
      */
@@ -32,5 +50,65 @@ export declare class BaseCore implements IAppInsightsCore {
     getPerfMgr(): IPerfManager;
     setPerfMgr(perfMgr: IPerfManager): void;
     eventCnt(): number;
+    /**
+     * Periodically check logger.queue for
+     */
+    pollInternalLogs(eventName?: string): number;
+    /**
+     * Periodically check logger.queue for
+     */
+    stopPollingInternalLogs(): void;
+    /**
+     * Add a telemetry processor to decorate or drop telemetry events.
+     * @param telemetryInitializer - The Telemetry Initializer function
+     * @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.
+     * @param isAsync - Can the unload be performed asynchronously (default)
+     * @param unloadComplete - An optional callback that will be called once the unload has completed
+     * @param cbTimeout - An optional timeout to wait for any flush operations to complete before proceeding with the unload. Defaults to 5 seconds.
+     */
+    unload(isAsync?: boolean, unloadComplete?: (unloadState: ITelemetryUnloadState) => void, cbTimeout?: number): void;
+    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, default is false
+     * @param doAsync - Should the add be performed asynchronously
+     * @param addCb - [Optional] callback to call after the plugin has been added
+     */
+    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;
+    /**
+     * Flush and send any batched / cached data immediately
+     * @param async - send data asynchronously when true (defaults to true)
+     * @param callBack - if specified, notify caller when send is complete, the channel should return true to indicate to the caller that it will be called.
+     * If the caller doesn't return true the caller should assume that it may never be called.
+     * @param sendReason - specify the reason that you are calling "flush" defaults to ManualFlush (1) if not specified
+     * @returns - true if the callback will be return after the flush is complete otherwise the caller should assume that any provided callback will never be called
+     */
+    flush(isAsync?: boolean, callBack?: (flushComplete?: boolean) => void, sendReason?: SendRequestReason): 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;
 }

package/types/JavaScriptSDK/BaseTelemetryPlugin.d.ts

@@ -3,14 +3,25 @@ import { IConfiguration } from "../JavaScriptSDK.Interfaces/IConfiguration";
 import { IDiagnosticLogger } from "../JavaScriptSDK.Interfaces/IDiagnosticLogger";
 import { IPlugin, ITelemetryPlugin } from "../JavaScriptSDK.Interfaces/ITelemetryPlugin";
 import { ITelemetryItem } from "../JavaScriptSDK.Interfaces/ITelemetryItem";
-import { IProcessTelemetryContext } from "../JavaScriptSDK.Interfaces/IProcessTelemetryContext";
+import { IProcessTelemetryContext, IProcessTelemetryUnloadContext, IProcessTelemetryUpdateContext } 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";
+import { ITelemetryUpdateState } from "../JavaScriptSDK.Interfaces/ITelemetryUpdateState";
 /**
  * BaseTelemetryPlugin provides a basic implementation of the ITelemetryPlugin interface so that plugins
  * can avoid implementation the same set of boiler plate code as well as provide a base
  * implementation so that new default implementations can be added without breaking all plugins.
  */
 export declare abstract class BaseTelemetryPlugin implements ITelemetryPlugin {
+    identifier: string;
+    version?: string;
+    /**
+     * Holds the core instance that was used during initialization
+     */
+    core: IAppInsightsCore;
+    priority: number;
     /**
      * Call back for telemetry processing before it it is sent
      * @param env - This is the current event being reported
@@ -32,13 +43,6 @@ export declare abstract class BaseTelemetryPlugin implements ITelemetryPlugin {
      * Returns whether the plugin has been initialized
      */
     isInitialized: () => boolean;
-    identifier: string;
-    version?: string;
-    /**
-     * Holds the core instance that was used during initialization
-     */
-    core: IAppInsightsCore;
-    priority: number;
     /**
      * Helper to return the current IProcessTelemetryContext, if the passed argument exists this just
      * returns that value (helps with minification for callers), otherwise it will return the configured
@@ -51,10 +55,49 @@ export declare abstract class BaseTelemetryPlugin implements ITelemetryPlugin {
      */
     protected setInitialized: (isInitialized: boolean) => void;
     /**
-     * Internal helper to initialize the instance
+     * Teardown / Unload hook to allow implementations to perform some additional unload operations before the BaseTelemetryPlugin
+     * finishes it's removal.
+     * @param unloadCtx - This is the context that should be used during unloading.
+     * @param unloadState - The details / state of the unload process, it holds details like whether it should be unloaded synchronously or asynchronously and the reason for the unload.
+     * @param asyncCallback - An optional callback that the plugin must call if it returns true to inform the caller that it has completed any async unload/teardown operations.
+     * @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.
      */
-    private _baseTelInit;
+    protected _doUpdate?: (updateCtx?: IProcessTelemetryUpdateContext, updateState?: ITelemetryUpdateState, asyncCallback?: () => void) => void | boolean;
     constructor();
     initialize(config: IConfiguration, core: IAppInsightsCore, extensions: IPlugin[], pluginChain?: ITelemetryPluginChain): void;
+    /**
+     * Tear down the plugin and remove any hooked value, the plugin should be removed so that it is no longer initialized and
+     * therefore could be re-initialized after being torn down. The plugin should ensure that once this has been called any further
+     * processTelemetry calls are ignored and it just calls the processNext() with the provided context.
+     * @param unloadCtx - This is the context that should be used during unloading.
+     * @param unloadState - The details / state of the unload process, it holds details like whether it should be unloaded synchronously or asynchronously and the reason for the unload.
+     * @returns boolean - true if the plugin has or will call processNext(), this for backward compatibility as previously teardown was synchronous and returned nothing.
+     */
+    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
+     */
+    protected _addHook(hooks: IInstrumentHook | IInstrumentHook[]): void;
 }

package/types/JavaScriptSDK/ChannelController.d.ts

@@ -1,21 +1,20 @@
+import { SendRequestReason } from "../JavaScriptSDK.Enums/SendRequestReason";
 import { IAppInsightsCore } from "../JavaScriptSDK.Interfaces/IAppInsightsCore";
-import { IConfiguration } from "../JavaScriptSDK.Interfaces/IConfiguration";
 import { IChannelControls } from "../JavaScriptSDK.Interfaces/IChannelControls";
-import { IPlugin, ITelemetryPlugin } from "../JavaScriptSDK.Interfaces/ITelemetryPlugin";
+import { IConfiguration } from "../JavaScriptSDK.Interfaces/IConfiguration";
+import { IPlugin } from "../JavaScriptSDK.Interfaces/ITelemetryPlugin";
 import { ITelemetryPluginChain } from "../JavaScriptSDK.Interfaces/ITelemetryPluginChain";
-import { ITelemetryItem } from "../JavaScriptSDK.Interfaces/ITelemetryItem";
-import { IProcessTelemetryContext } from "../JavaScriptSDK.Interfaces/IProcessTelemetryContext";
-import { BaseTelemetryPlugin } from "./BaseTelemetryPlugin";
-export declare class ChannelController extends BaseTelemetryPlugin {
-    identifier: string;
-    priority: number;
-    setNextPlugin: (next: ITelemetryPlugin | ITelemetryPluginChain) => void;
-    constructor();
-    processTelemetry(item: ITelemetryItem, itemCtx: IProcessTelemetryContext): void;
-    getChannelControls(): IChannelControls[][];
-    initialize(config: IConfiguration, core: IAppInsightsCore, extensions: IPlugin[]): void;
-    /**
-     * Static constructor, attempt to create accessors
-     */
-    private static _staticInit;
+export declare const ChannelControllerPriority = 500;
+export interface IChannelController extends IChannelControls {
+    flush(isAsync: boolean, callBack: (flushComplete?: boolean) => void, sendReason: SendRequestReason, cbTimeout?: number): void;
+    getChannel<T extends IPlugin = IPlugin>(pluginIdentifier: string): T;
+}
+export interface IInternalChannelController extends IChannelController {
+    _setQueue: (channels: _IInternalChannels[]) => void;
+}
+export interface _IInternalChannels {
+    queue: IChannelControls[];
+    chain: ITelemetryPluginChain;
 }
+export declare function createChannelControllerPlugin(channelQueue: _IInternalChannels[], core: IAppInsightsCore): IChannelController;
+export declare function createChannelQueues(channels: IChannelControls[][], extensions: IPlugin[], config: IConfiguration, core: IAppInsightsCore): _IInternalChannels[];