@microsoft/applicationinsights-core-js 3.0.0-beta.2209-03 → 3.0.0-beta.2210-02

package/src/JavaScriptSDK.Interfaces/IDiagnosticLogger.ts

@@ -1,7 +1,8 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
-import { _InternalMessageId, LoggingSeverity } from "../JavaScriptSDK.Enums/LoggingEnums";
+import { _eInternalMessageId, LoggingSeverity } from "../JavaScriptSDK.Enums/LoggingEnums";
 import { _InternalLogMessage } from "../JavaScriptSDK/DiagnosticLogger";
+import { ITelemetryUpdateState } from "./ITelemetryUpdateState";
 
 "use strict"
 
@@ -37,14 +38,14 @@ export interface IDiagnosticLogger {
 
     /**
      * This method will throw exceptions in debug mode or attempt to log the error as a console warning.
-     * @param severity {LoggingSeverity} - The severity of the log message
-     * @param message {_InternalLogMessage} - The log message.
+     * @param severity - {LoggingSeverity} - The severity of the log message
+     * @param message - {_InternalLogMessage} - The log message.
      */
-    throwInternal(severity: LoggingSeverity, msgId: _InternalMessageId, msg: string, properties?: Object, isUserAct?: boolean): void;
+    throwInternal(severity: LoggingSeverity, msgId: _eInternalMessageId, msg: string, properties?: Object, isUserAct?: boolean): void;
 
     /**
      * This will write a warning to the console if possible
-     * @param message {string} - The warning message
+     * @param message - {string} - The warning message
      */
     warnToConsole(message: string): void;
 
@@ -52,7 +53,7 @@ export interface IDiagnosticLogger {
      * This will write an error to the console if possible.
      * Provided by the default DiagnosticLogger instance, and internally the SDK will fall back to warnToConsole, however,
      * direct callers MUST check for its existence on the logger as you can provide your own IDiagnosticLogger instance.
-     * @param message {string} - The error message
+     * @param message - {string} - The error message
      */
     errorToConsole?(message: string): void;
 
@@ -63,8 +64,14 @@ export interface IDiagnosticLogger {
 
     /**
      * Logs a message to the internal queue.
-     * @param severity {LoggingSeverity} - The severity of the log message
-     * @param message {_InternalLogMessage} - The message to log.
+     * @param severity - {LoggingSeverity} - The severity of the log message
+     * @param message - {_InternalLogMessage} - The message to log.
      */
     logInternalMessage?(severity: LoggingSeverity, message: _InternalLogMessage): void;
+
+    /**
+     * Optional Callback hook to allow the diagnostic logger to update it's configuration
+     * @param updateState
+     */
+    update?(updateState: ITelemetryUpdateState): void;
 }

package/src/JavaScriptSDK.Interfaces/IInstrumentHooks.ts

@@ -1,6 +1,8 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
+import { IUnloadHook } from "./IUnloadHook";
+
 /**
  * A callback function that will be called for the wrapped instrumentation function
  * before the original function is executed.
@@ -43,7 +45,7 @@ export interface IInstrumentHooksCallbacks {
 /**
  * The holder of the specific instance callback
  */
-export interface IInstrumentHook {
+export interface IInstrumentHook extends IUnloadHook {
     /** Unique Id for this callback on the hooked method */
     id: number;
 

package/src/JavaScriptSDK.Interfaces/INotificationListener.ts

@@ -12,21 +12,21 @@ import { IPerfEvent } from "./IPerfEvent";
 export interface INotificationListener {
     /**
      * [Optional] A function called when events are sent.
-     * @param {ITelemetryItem[]} events - The array of events that have been sent.
+     * @param events - The array of events that have been sent.
      */
     eventsSent?: (events: ITelemetryItem[]) => void;
     /**
      * [Optional] A function called when events are discarded.
-     * @param {ITelemetryItem[]} events - The array of events that have been discarded.
-     * @param {number} reason           - The reason for discarding the events. The EventsDiscardedReason
+     * @param events - The array of events that have been discarded.
+     * @param reason - The reason for discarding the events. The EventsDiscardedReason
      * constant should be used to check the different values.
      */
     eventsDiscarded?: (events: ITelemetryItem[], reason: number) => void;
 
     /**
      * [Optional] A function called when the events have been requested to be sent to the sever.
-     * @param {number} sendReason - The reason why the event batch is being sent.
-     * @param {boolean} isAsync   - A flag which identifies whether the requests are being sent in an async or sync manner.
+     * @param sendReason - The reason why the event batch is being sent.
+     * @param isAsync - A flag which identifies whether the requests are being sent in an async or sync manner.
      */
     eventsSendRequest?: (sendReason: number, isAsync?: boolean) => void;
 

package/src/JavaScriptSDK.Interfaces/INotificationManager.ts

@@ -12,41 +12,41 @@ export interface INotificationManager {
 
     /**
      * Adds a notification listener.
-     * @param {INotificationListener} listener - The notification listener to be added.
+     * @param listener - The notification listener to be added.
      */
     addNotificationListener(listener: INotificationListener): void;
 
     /**
      * Removes all instances of the listener.
-     * @param {INotificationListener} listener - AWTNotificationListener to remove.
+     * @param listener - AWTNotificationListener to remove.
      */
     removeNotificationListener(listener: INotificationListener): void;
 
     /**
      * Notification for events sent.
-     * @param {ITelemetryItem[]} events - The array of events that have been sent.
+     * @param events - The array of events that have been sent.
      */
     eventsSent(events: ITelemetryItem[]): void;
 
     /**
      * Notification for events being discarded.
-     * @param {ITelemetryItem[]} events - The array of events that have been discarded by the SDK.
-     * @param {number} reason           - The reason for which the SDK discarded the events. The EventsDiscardedReason
+     * @param events - The array of events that have been discarded by the SDK.
+     * @param reason - The reason for which the SDK discarded the events. The EventsDiscardedReason
      * constant should be used to check the different values.
      */
     eventsDiscarded(events: ITelemetryItem[], reason: number): void;
 
     /**
      * [Optional] A function called when the events have been requested to be sent to the sever.
-     * @param {number} sendReason - The reason why the event batch is being sent.
-     * @param {boolean} isAsync   - A flag which identifies whether the requests are being sent in an async or sync manner.
+     * @param sendReason - The reason why the event batch is being sent.
+     * @param isAsync - A flag which identifies whether the requests are being sent in an async or sync manner.
      */
     eventsSendRequest?(sendReason: number, isAsync: boolean): void;
 
     /**
      * [Optional] This event is sent if you have enabled perf events, they are primarily used to track internal performance testing and debugging
      * the event can be displayed via the debug plugin extension.
-     * @param perfEvent
+     * @param perfEvent - The perf event details
      */
     perfEvent?(perfEvent: IPerfEvent): void;
 }

package/src/JavaScriptSDK.Interfaces/IPerfManager.ts

@@ -13,7 +13,7 @@ export interface IPerfManagerProvider {
 
     /**
      * Set the current performance manager
-     * @param perfMgr The performance manager
+     * @param perfMgr - The performance manager
      */
     setPerfMgr(perfMgr: IPerfManager): void;
 }
@@ -26,7 +26,7 @@ export interface IPerfManager {
     /**
      * Create a new event and start timing, the manager may return null/undefined to indicate that it does not
      * want to monitor this source event.
-     * @param src The source name of the event
+     * @param src - The source name of the event
      * @param payloadDetails - An optional callback function to fetch the payload details for the event.
      * @param isAsync - Is the event occurring from a async event
      */
@@ -34,7 +34,7 @@ export interface IPerfManager {
 
     /**
      * Complete the perfEvent and fire any notifications.
-     * @param perfEvent Fire the event which will also complete the passed event
+     * @param perfEvent - Fire the event which will also complete the passed event
      */
     fire(perfEvent: IPerfEvent): void;
 

package/src/JavaScriptSDK.Interfaces/IProcessTelemetryContext.ts

@@ -2,6 +2,7 @@
 // Licensed under the MIT License.
 "use strict";
 
+import { IConfigDefaults } from "../Config/IConfigDefaults";
 import { IAppInsightsCore } from "./IAppInsightsCore";
 import { IConfiguration } from "./IConfiguration";
 import { IDiagnosticLogger } from "./IDiagnosticLogger";
@@ -11,11 +12,11 @@ import { ITelemetryPluginChain } from "./ITelemetryPluginChain";
 import { ITelemetryUnloadState } from "./ITelemetryUnloadState";
 import { ITelemetryUpdateState } from "./ITelemetryUpdateState";
 
-export const enum GetExtCfgMergeType {
-    None = 0,
-    MergeDefaultOnly = 1,
-    MergeDefaultFromRootOrDefault = 2,
-}
+// export const enum GetExtCfgMergeType {
+//     None = 0,
+//     MergeDefaultOnly = 1,
+//     MergeDefaultFromRootOrDefault = 2,
+// }
 
 export interface IBaseProcessingContext {
     /**
@@ -36,14 +37,14 @@ export interface IBaseProcessingContext {
     /**
      * Gets the named extension config
      */
-    getExtCfg: <T>(identifier: string, defaultValue?: T | any, mergeDefault?: GetExtCfgMergeType) => T;
+    getExtCfg: <T>(identifier: string, defaultValue?: IConfigDefaults<T>) => T;
 
     /**
      * Gets the named config from either the named identifier extension or core config if neither exist then the
      * default value is returned
-     * @param identifier The named extension identifier
-     * @param field The config field name
-     * @param defaultValue The default value to return if no defined config exists
+     * @param identifier - The named extension identifier
+     * @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 | string[] | RegExp[] | Function) => number | string | boolean | string[] | RegExp[] | Function;
 

package/src/JavaScriptSDK.Interfaces/ITelemetryInitializers.ts

@@ -1,8 +1,9 @@
 import { ITelemetryItem } from "./ITelemetryItem";
+import { ILegacyUnloadHook } from "./IUnloadHook";
 
 export declare type TelemetryInitializerFunction = <T extends ITelemetryItem>(item: T) => boolean | void;
 
-export interface ITelemetryInitializerHandler {
+export interface ITelemetryInitializerHandler extends ILegacyUnloadHook {
     remove(): void;
 }
 

package/src/JavaScriptSDK.Interfaces/ITelemetryUpdateState.ts

@@ -2,7 +2,7 @@
 // Licensed under the MIT License.
 
 import { TelemetryUpdateReason } from "../JavaScriptSDK.Enums/TelemetryUpdateReason";
-//import { IConfiguration } from "./IConfiguration";
+import { IConfiguration } from "./IConfiguration";
 import { IPlugin } from "./ITelemetryPlugin";
 
 export interface ITelemetryUpdateState {
@@ -13,14 +13,24 @@ export interface ITelemetryUpdateState {
     reason: TelemetryUpdateReason;
 
     /**
+     * This is a new active configuration that should be used
+     */
+    cfg?: IConfiguration,
+
+    /**
+     * The detected changes
+     */
+    oldCfg?: IConfiguration,
+
+     /**
      * If this is a configuration update this was the previous configuration that was used
      */
-    //prvCfg?: IConfiguration,
+    newConfig?: IConfiguration,
 
     /**
-     * If this is a configuration update is the new configuration that is being used
+     * Was the new config requested to be merged with the existing config
      */
-    //newCfg?: IConfiguration,
+    merge?: boolean,
 
     /**
      * This holds a collection of plugins that have been added (if the reason identifies that one or more plugins have been added)
@@ -30,5 +40,5 @@ export interface ITelemetryUpdateState {
     /**
      * This holds a collection of plugins that have been removed (if the reason identifies that one or more plugins have been removed)
      */
-     removed?: IPlugin[]
+    removed?: IPlugin[]
 }

package/src/JavaScriptSDK.Interfaces/IUnloadHook.ts

@@ -0,0 +1,22 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+/**
+ * An interface which provides automatic removal during unloading of the component
+ */
+export interface IUnloadHook {
+    /**
+     * Self remove the referenced component
+     */
+    rm: () => void;
+}
+
+/**
+ * An alternate interface which provides automatic removal during unloading of the component
+ */
+export interface ILegacyUnloadHook {
+    /**
+     * Legacy Self remove the referenced component
+     */
+    remove: () => void;
+}

package/src/JavaScriptSDK.Interfaces/IUnloadableComponent.ts

@@ -1,9 +1,9 @@
-import { IProcessTelemetryUnloadContext } from "./IProcessTelemetryContext";
-import { ITelemetryUnloadState } from "./ITelemetryUnloadState";
-
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
+import { IProcessTelemetryUnloadContext } from "./IProcessTelemetryContext";
+import { ITelemetryUnloadState } from "./ITelemetryUnloadState";
+
 export interface IUnloadableComponent {
     /**
     * Teardown / Unload hook to allow implementations to perform some additional unload operations before the BaseTelemetryPlugin

package/tsconfig.json

@@ -13,14 +13,15 @@
     "alwaysStrict": true,
     "skipDefaultLibCheck": true,
     "declaration": true,
-    "declarationDir": "shared/AppInsightsCore/types",
+    "declarationDir": "./types",
     "outDir": "./dist-esm",
-    "rootDir": "shared/AppInsightsCore/src",
+    "rootDir": "./src",
     "suppressImplicitAnyIndexErrors": true,
     "allowSyntheticDefaultImports": true
   },
   "include": [
     "./src/applicationinsights-core-js.ts",
+    "./src/Config/**/*.ts",
     "./src/JavaScriptSDK/**/*.ts",
     "./src/JavaScriptSDK.Enums/**/*.ts",
     "./src/JavaScriptSDK.Interfaces/**/*.ts"

package/types/Config/ConfigDefaults.d.ts

@@ -0,0 +1,10 @@
+import { IConfiguration } from "../JavaScriptSDK.Interfaces/IConfiguration";
+import { IConfigDefaultCheck, IConfigDefaults } from "./IConfigDefaults";
+/**
+ * Applies the default value on the config property and makes sure that it's dynamic
+ * @param theConfig
+ * @param name
+ * @param defaultValue
+ */
+export declare function _applyDefaultValue<T extends IConfiguration, C>(theConfig: C, name: string, defaultValue: C[keyof C] | IConfigDefaultCheck<C, C[keyof C], T>): void;
+export declare function applyDefaults<C>(theConfig: C, defaultValues: IConfigDefaults<C>): C;

package/types/Config/DynamicConfig.d.ts

@@ -0,0 +1,23 @@
+import { IConfiguration } from "../JavaScriptSDK.Interfaces/IConfiguration";
+import { IDiagnosticLogger } from "../JavaScriptSDK.Interfaces/IDiagnosticLogger";
+import { IConfigDefaults } from "./IConfigDefaults";
+import { IDynamicConfigHandler } from "./IDynamicConfigHandler";
+import { IWatcherHandler, WatcherFunction } from "./IDynamicWatcher";
+/**
+ * Create or return a dynamic version of the passed config, if it is not already dynamic
+ * @param config - The config to be converted into a dynamic config
+ * @param defaultConfig - The default values to apply on the config if the properties don't already exist
+ * @param inPlace - Should the config be converted in-place into a dynamic config or a new instance returned, defaults to true
+ * @returns The dynamic config handler for the config (whether new or existing)
+ */
+export declare function createDynamicConfig<T extends IConfiguration>(config: T, defaultConfig?: IConfigDefaults<T>, logger?: IDiagnosticLogger, inPlace?: boolean): IDynamicConfigHandler<T>;
+/**
+ * Watch and track changes for accesses to the current config, the provided config MUST already be
+ * a dynamic config or a child accessed via the dynamic config
+ * @param config
+ * @param configHandler
+ * @param logger - The logger instance to use if there is no existing handler
+ * @returns A watcher handler instance that can be used to remove itself when being unloaded
+ * @throws TypeError if the provided config is not a dynamic config instance
+ */
+export declare function onConfigChange<T>(config: T, configHandler: WatcherFunction<T>, logger?: IDiagnosticLogger): IWatcherHandler<T>;

package/types/Config/DynamicProperty.d.ts

@@ -0,0 +1,3 @@
+import { _IDynamicConfigHandlerState } from "./_IDynamicConfigHandlerState";
+export declare function _setDynamicProperty<T, C, V = any>(state: _IDynamicConfigHandlerState<T>, target: C, name: string, value: V): V;
+export declare function _makeDynamicObject<T>(state: _IDynamicConfigHandlerState<T>, target: any): any;

package/types/Config/DynamicState.d.ts

@@ -0,0 +1,3 @@
+import { _IInternalDynamicConfigHandler } from "./IDynamicConfigHandler";
+import { _IDynamicConfigHandlerState } from "./_IDynamicConfigHandlerState";
+export declare function _createState<T>(cfgHandler: _IInternalDynamicConfigHandler<T>): _IDynamicConfigHandlerState<T>;

package/types/Config/DynamicSupport.d.ts

@@ -0,0 +1,15 @@
+import { IDynamicConfigHandler } from "./IDynamicConfigHandler";
+export declare const CFG_HANDLER_LINK: symbol;
+export declare function _cfgDeepCopy<T>(source: T): T;
+/**
+ * @internal
+ * Get the dynamic config handler if the value is already dynamic
+ * @param value
+ * @returns
+ */
+export declare function getDynamicConfigHandler<T>(value: T | IDynamicConfigHandler<T>): IDynamicConfigHandler<T> | null;
+/**
+ * Throws an invalid access exception
+ * @param message - The message to include in the exception
+ */
+export declare function throwInvalidAccess(message: string): never;

package/types/Config/IConfigDefaults.d.ts

@@ -0,0 +1,42 @@
+import { IConfiguration } from "../JavaScriptSDK.Interfaces/IConfiguration";
+/**
+ * The type to identify whether the default value should be applied in preference to the provided value.
+ */
+export declare type IConfigCheckFn<V> = (value: V) => boolean;
+/**
+ * The type which identifies the function use to validate the user supplied value
+ */
+export declare type IConfigSetFn<T, V> = (value: any, defValue: V, theConfig: T) => V;
+/**
+ * The default values with a check function
+ */
+export interface IConfigDefaultCheck<T, V, C extends IConfiguration = IConfiguration> {
+    /**
+     * Callback function to check if the user-supplied value is valid, if not the default will be applied
+     */
+    isVal?: IConfigCheckFn<V>;
+    /**
+     * Optional function to allow converting and setting of the default value
+     */
+    set?: IConfigSetFn<T, V>;
+    /**
+     * The default value to apply if the user-supplied value is not valid
+     */
+    v?: V;
+    /**
+     *  The default fallback key if the main key is not present, this is the key value from the config
+     */
+    fb?: keyof T | keyof C | Array<keyof T | keyof C>;
+    /**
+     * Use this check to determine the default fallback, default only checked whether the property isDefined,
+     * therefore `null`; `""` are considered to be valid values.
+     */
+    dfVal?: (value: any) => boolean;
+}
+/**
+ * The Type definition to define default values to be applied to the config
+ * The value may be either the direct value or a ConfigDefaultCheck definition
+ */
+export declare type IConfigDefaults<T, C extends IConfiguration = IConfiguration> = {
+    [key in keyof T]: T[key] | IConfigDefaultCheck<T, T[key], C>;
+};

package/types/Config/IDynamicConfigHandler.d.ts

@@ -0,0 +1,46 @@
+import { IConfiguration } from "../JavaScriptSDK.Interfaces/IConfiguration";
+import { IDiagnosticLogger } from "../JavaScriptSDK.Interfaces/IDiagnosticLogger";
+import { IWatcherHandler, WatcherFunction } from "./IDynamicWatcher";
+/**
+ * This interface identifies the config which can track changes
+ */
+export interface IDynamicConfigHandler<T extends IConfiguration> {
+    /**
+     * Unique Id for this config handler
+     */
+    readonly uid: string;
+    /**
+     * Link back to the configuration object that should be used to get/set values
+     */
+    cfg: T;
+    /**
+     * The logger instance to use to loger any issues
+     */
+    logger: IDiagnosticLogger;
+    /**
+     * Helper to call any listeners that are waiting to be notified
+     */
+    notify: () => void;
+    /**
+     * Watch and track changes for accesses to the current config anb
+     */
+    watch: (configHandler: WatcherFunction<T>) => IWatcherHandler<T>;
+    /**
+     * Set the value against the provided config/name with the value, the property
+     * will be converted to be dynamic (if not already) as long as the provided config
+     * is already a tracked dynamic object.
+     * @throws TypeError if the provided config is not a monitored dynamic config
+     */
+    set: <C, V>(theConfig: C, name: string, value: V) => V;
+}
+/**
+ * @internal
+ * @ignore
+ */
+export interface _IInternalDynamicConfigHandler<T extends IConfiguration> extends IDynamicConfigHandler<T> {
+    /**
+     * @ignore
+     * Internal function to explicitly block watching for any config updates
+     */
+    _block: (configHandler: WatcherFunction<T>) => void;
+}

package/types/Config/IDynamicPropertyHandler.d.ts

@@ -0,0 +1,11 @@
+import { IWatcherHandler } from "./IDynamicWatcher";
+export interface IDynamicPropertyHandler<T> {
+    /**
+     * Identifies the name of the field that is handled by this handler
+     */
+    n: string;
+    /**
+     * The current collection is watcher handlers which should be called if the value changes
+     */
+    h: IWatcherHandler<T>[];
+}

package/types/Config/IDynamicWatcher.d.ts

@@ -0,0 +1,28 @@
+import { IConfiguration } from "../JavaScriptSDK.Interfaces/IConfiguration";
+import { IUnloadHook } from "../JavaScriptSDK.Interfaces/IUnloadHook";
+import { IDynamicConfigHandler } from "./IDynamicConfigHandler";
+import { IDynamicPropertyHandler } from "./IDynamicPropertyHandler";
+export interface IWatchDetails<T extends IConfiguration> {
+    cfg: T;
+    hdlr: IDynamicConfigHandler<T>;
+}
+export declare type WatcherFunction<T extends IConfiguration> = (details: IWatchDetails<T>) => void;
+/**
+ * @internal
+ */
+export interface _WatcherChangeDetails<T extends IConfiguration> {
+    d: _IDynamicDetail<T>;
+}
+/**
+ * @internal
+ */
+export interface _IDynamicDetail<T extends IConfiguration> extends IDynamicPropertyHandler<T> {
+    /**
+     * Add the watcher for monitoring changes
+     */
+    add: (handler: IWatcherHandler<T>) => void;
+}
+export interface IWatcherHandler<T extends IConfiguration> extends IUnloadHook {
+    fn: WatcherFunction<T>;
+    rm: () => void;
+}

package/types/Config/_IDynamicConfigHandlerState.d.ts

@@ -0,0 +1,35 @@
+import { IDynamicConfigHandler } from "./IDynamicConfigHandler";
+import { IDynamicPropertyHandler } from "./IDynamicPropertyHandler";
+import { IWatcherHandler, WatcherFunction } from "./IDynamicWatcher";
+/**
+ * @internal
+ * Interface for the global dynamic config handler
+ */
+export interface _IDynamicConfigHandlerState<T> {
+    prop: symbol;
+    ro: symbol;
+    /**
+     * Link to the handler
+     */
+    hdlr: IDynamicConfigHandler<T>;
+    /**
+     * Identifies the current active handler
+     */
+    act?: IWatcherHandler<T>;
+    /**
+     * Enable / Disable updates to dynamic readonly properties
+     */
+    upd?: boolean;
+    /**
+     * Helper to call any listeners that are waiting to be notified
+     */
+    notify: () => void;
+    /**
+     * Add this property handler to the collection to be notified
+     */
+    add: (handler: IDynamicPropertyHandler<T>) => void;
+    /**
+     * Use the provided handler to listen for changes
+     */
+    use: (activeHandler: IWatcherHandler<T>, callback: WatcherFunction<T>) => void;
+}