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

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

@@ -11,6 +11,19 @@ import { ICookieMgr } from "./ICookieMgr";
 import { ITelemetryInitializerHandler, TelemetryInitializerFunction } from "./ITelemetryInitializers";
 export interface ILoadedPlugin<T extends IPlugin> {
     plugin: T;
+    /**
+     * Identifies whether the plugin is enabled and can process events. This is slightly different from isInitialized as the plugin may be initialized but disabled
+     * via the setEnabled() or it may be a shared plugin which has had it's teardown function called from another instance..
+     * @returns boolean = true if the plugin is in a state where it is operational.
+     */
+    isEnabled: () => boolean;
+    /**
+     * You can optionally enable / disable a plugin from processing events.
+     * Setting enabled to true will not necessarily cause the `isEnabled()` to also return true
+     * as the plugin must also have been successfully initialized and not had it's `teardown` method called
+     * (unless it's also been re-initialized)
+     */
+    setEnabled: (isEnabled: boolean) => void;
 }
 export interface IAppInsightsCore extends IPerfManagerProvider {
     config: IConfiguration;
@@ -64,4 +77,8 @@ export interface IAppInsightsCore extends IPerfManagerProvider {
      * @param pluginIdentifier
      */
     getPlugin<T extends IPlugin = IPlugin>(pluginIdentifier: string): ILoadedPlugin<T>;
+    /**
+     * Returns the unique event namespace that should be used when registering events
+     */
+    evtNamespace(): string;
 }

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

@@ -1,5 +1,7 @@
 import { SendRequestReason } from "../JavaScriptSDK.Enums/SendRequestReason";
+import { IProcessTelemetryUnloadContext } from "./IProcessTelemetryContext";
 import { ITelemetryPlugin } from "./ITelemetryPlugin";
+import { ITelemetryUnloadState } from "./ITelemetryUnloadState";
 /**
  * Provides data transmission capabilities
  */
@@ -13,9 +15,14 @@ export interface IChannelControls extends ITelemetryPlugin {
      */
     resume(): void;
     /**
-     * Tear down transmission pipeline
+     * 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;
     /**
      * Flush to send data immediately; channel should default to sending data asynchronously
      * @param async - send data asynchronously when true

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

@@ -1,19 +1,16 @@
 import { IAppInsightsCore } from "./IAppInsightsCore";
-import { IDiagnosticLogger } from "./IDiagnosticLogger";
 import { IConfiguration } from "./IConfiguration";
+import { IDiagnosticLogger } from "./IDiagnosticLogger";
 import { ITelemetryItem } from "./ITelemetryItem";
 import { IPlugin, ITelemetryPlugin } from "./ITelemetryPlugin";
 import { ITelemetryPluginChain } from "./ITelemetryPluginChain";
+import { ITelemetryUnloadState } from "./ITelemetryUnloadState";
 export declare const enum GetExtCfgMergeType {
     None = 0,
     MergeDefaultOnly = 1,
     MergeDefaultFromRootOrDefault = 2
 }
-/**
- * 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 interface IBaseProcessingContext {
     /**
      * The current core instance for the request
      */
@@ -51,11 +48,6 @@ export interface IProcessTelemetryContext {
      * Helper to set the next plugin proxy
      */
     setNext: (nextCtx: ITelemetryPluginChain) => void;
-    /**
-     * Call back for telemetry processing before it it is sent
-     * @param env - This is the current event being reported
-     */
-    processNext: (env: ITelemetryItem) => 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.
@@ -63,15 +55,58 @@ export interface IProcessTelemetryContext {
      */
     iterate: <T extends ITelemetryPlugin = ITelemetryPlugin>(callback: (plugin: T) => void) => void;
     /**
-     * Create a new context using the core and config from the current instance
+     * 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: Function, 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 processTelemetry(), used to support sharing the same plugin instance
+ * between multiple AppInsights instances
+ */
+export interface IProcessTelemetryUnloadContext extends IBaseProcessingContext {
     /**
-     * Set the function to call when the current chain has executed all processNext or unloadNext items.
+     * 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.
      */
-    onComplete: (onComplete: () => void) => void;
+    createNew: (plugins?: IPlugin[] | ITelemetryPluginChain, startAt?: IPlugin) => IProcessTelemetryUnloadContext;
 }

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

@@ -1,12 +1,10 @@
 import { ITelemetryItem } from "./ITelemetryItem";
 import { IConfiguration } from "./IConfiguration";
 import { IAppInsightsCore } from "./IAppInsightsCore";
-import { IProcessTelemetryContext } from "./IProcessTelemetryContext";
+import { IProcessTelemetryContext, IProcessTelemetryUnloadContext } from "./IProcessTelemetryContext";
 import { ITelemetryPluginChain } from "./ITelemetryPluginChain";
-/**
- * Configuration provided to SDK core
- */
-export interface ITelemetryPlugin extends IPlugin {
+import { ITelemetryUnloadState } from "./ITelemetryUnloadState";
+export interface ITelemetryProcessor {
     /**
      * Call back for telemetry processing before it it is sent
      * @param env - This is the current event being reported
@@ -15,6 +13,11 @@ export interface ITelemetryPlugin extends IPlugin {
      * to later plugins (vs appending items to the telemetry item)
      */
     processTelemetry: (env: ITelemetryItem, itemCtx?: IProcessTelemetryContext) => void;
+}
+/**
+ * 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
@@ -42,10 +45,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/types/JavaScriptSDK.Interfaces/ITelemetryPluginChain.d.ts

@@ -1,10 +1,10 @@
-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
      */
@@ -14,11 +14,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/types/JavaScriptSDK.Interfaces/ITelemetryUnloadState.d.ts

@@ -0,0 +1,6 @@
+import { TelemetryUnloadReason } from "../JavaScriptSDK.Enums/TelemetryUnloadReason";
+export interface ITelemetryUnloadState {
+    reason: TelemetryUnloadReason;
+    isAsync: boolean;
+    flushComplete?: boolean;
+}

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

@@ -14,8 +14,9 @@ export { AppInsightsCore } from "./JavaScriptSDK/AppInsightsCore";
 export { BaseCore } from "./JavaScriptSDK/BaseCore";
 export { BaseTelemetryPlugin } from "./JavaScriptSDK/BaseTelemetryPlugin";
 export { randomValue, random32, mwcRandomSeed, mwcRandom32, newId } from "./JavaScriptSDK/RandomHelper";
-export { CoreUtils, ICoreUtils, EventHelper, IEventHelper, Undefined, addEventHandler, newGuid, perfNow, generateW3CId, disableCookies, canUseCookies, getCookie, setCookie, deleteCookie, _legacyCookieMgr, addEventListeners, addPageUnloadEventListener, addPageHideEventListener, addPageShowEventListener } from "./JavaScriptSDK/CoreUtils";
-export { isTypeof, isUndefined, isNullOrUndefined, hasOwnProperty, isObject, isFunction, attachEvent, detachEvent, normalizeJsName, objForEachKey, strEndsWith, strStartsWith, isDate, isArray, isError, isString, isNumber, isBoolean, toISOString, arrForEach, arrIndexOf, arrMap, arrReduce, strTrim, objKeys, objDefineAccessors, dateNow, getExceptionName, throwError, strContains, isSymbol, setValue, getSetValue, isNotTruthy, isTruthy, proxyAssign, createClassFromInterface, optimizeObject, isNotUndefined, isNotNullOrUndefined, objFreeze, objSeal } from "./JavaScriptSDK/HelperFuncs";
+export { CoreUtils, ICoreUtils, EventHelper, IEventHelper, Undefined, newGuid, perfNow, generateW3CId, disableCookies, canUseCookies, getCookie, setCookie, deleteCookie, _legacyCookieMgr } from "./JavaScriptSDK/CoreUtils";
+export { isTypeof, isUndefined, isNullOrUndefined, hasOwnProperty, isObject, isFunction, normalizeJsName, objForEachKey, strEndsWith, strStartsWith, isDate, isArray, isError, isString, isNumber, isBoolean, toISOString, arrForEach, arrIndexOf, arrMap, arrReduce, strTrim, objKeys, objDefineAccessors, dateNow, getExceptionName, throwError, strContains, isSymbol, setValue, getSetValue, isNotTruthy, isTruthy, proxyAssign, proxyFunctions, proxyFunctionAs, createClassFromInterface, optimizeObject, isNotUndefined, isNotNullOrUndefined, objFreeze, objSeal, createEnumStyle, objExtend } from "./JavaScriptSDK/HelperFuncs";
+export { attachEvent, detachEvent, addEventHandler, addEventListeners, addPageUnloadEventListener, addPageHideEventListener, addPageShowEventListener, removeEventHandler, removeEventListeners, removePageUnloadEventListener, removePageHideEventListener, eventOn, eventOff, mergeEvtNamespace, _IRegisteredEvents, __getRegisteredEvents } from "./JavaScriptSDK/EventHelpers";
 export { getGlobalInst, hasWindow, getWindow, hasDocument, getDocument, getCrypto, getMsCrypto, hasNavigator, getNavigator, hasHistory, getHistory, getLocation, getPerformance, hasJSON, getJSON, isReactNative, getConsole, dumpObj, isIE, getIEVersion, isSafari, setEnableEnvMocks, isBeaconsSupported, isFetchSupported, useXDomainRequest, isXhrSupported } from "./JavaScriptSDK/EnvUtils";
 export { getGlobal, objCreateFn as objCreate, strShimPrototype as strPrototype, strShimFunction as strFunction, strShimUndefined as strUndefined, strShimObject as strObject } from "@microsoft/applicationinsights-shims";
 export { NotificationManager } from "./JavaScriptSDK/NotificationManager";
@@ -26,7 +27,7 @@ export { PerfEvent, PerfManager, doPerf, getGblPerfMgr, setGblPerfMgr } from "./
 export { safeGetLogger, DiagnosticLogger, _InternalLogMessage } from "./JavaScriptSDK/DiagnosticLogger";
 export { ProcessTelemetryContext, createProcessTelemetryContext } from "./JavaScriptSDK/ProcessTelemetryContext";
 export { initializePlugins, sortPlugins } from "./JavaScriptSDK/TelemetryHelpers";
-export { _InternalMessageId, LoggingSeverity } from "./JavaScriptSDK.Enums/LoggingEnums";
+export { _InternalMessageId, _eInternalMessageId, LoggingSeverity, eLoggingSeverity } from "./JavaScriptSDK.Enums/LoggingEnums";
 export { InstrumentProto, InstrumentProtos, InstrumentFunc, InstrumentFuncs } from "./JavaScriptSDK/InstrumentHooks";
 export { ICookieMgr, ICookieMgrConfig } from "./JavaScriptSDK.Interfaces/ICookieMgr";
 export { createCookieMgr, safeGetCookieMgr, uaDisallowsSameSiteNone, areCookiesSupported } from "./JavaScriptSDK/CookieMgr";
@@ -34,3 +35,5 @@ export { strIKey, strExtensionConfig } from "./JavaScriptSDK/Constants";
 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 { ITelemetryUnloadState } from "./JavaScriptSDK.Interfaces/ITelemetryUnloadState";