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

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

@@ -8,6 +8,7 @@ import { arrForEach } from '@nevware21/ts-utils';
 import { arrIndexOf } from '@nevware21/ts-utils';
 import { arrMap } from '@nevware21/ts-utils';
 import { arrReduce } from '@nevware21/ts-utils';
+import { asString } from '@nevware21/ts-utils';
 import { objDeepFreeze as deepFreeze } from '@nevware21/ts-utils';
 import { dumpObj } from '@nevware21/ts-utils';
 import { EnumCls } from '@nevware21/ts-utils';
@@ -71,35 +72,13 @@ export function addPageShowEventListener(listener: any, excludeEvents?: string[]
 export function addPageUnloadEventListener(listener: any, excludeEvents?: string[], evtNamespace?: string | string[]): boolean;
 
 // @public (undocumented)
-export class AppInsightsCore extends BaseCore implements IAppInsightsCore {
-    constructor();
-    // (undocumented)
-    initialize(config: IConfiguration, extensions: IPlugin[], logger?: IDiagnosticLogger, notificationManager?: INotificationManager): void;
-    // (undocumented)
-    track(telemetryItem: ITelemetryItem): void;
-}
-
-// @public (undocumented)
-export function areCookiesSupported(logger?: IDiagnosticLogger): any;
-
-export { arrForEach }
-
-export { arrIndexOf }
-
-export { arrMap }
-
-export { arrReduce }
-
-// @public
-export function attachEvent(obj: any, eventNameWithoutOn: string, handlerRef: any, useCapture?: boolean): boolean;
-
-// @public (undocumented)
-export class BaseCore implements IAppInsightsCore {
+export class AppInsightsCore implements IAppInsightsCore {
     constructor();
     addNotificationListener(listener: INotificationListener): void;
     addPlugin<T extends IPlugin = ITelemetryPlugin>(plugin: T, replaceExisting?: boolean, doAsync?: boolean, addCb?: (added?: boolean) => void): void;
-    addTelemetryInitializer(telemetryInitializer: TelemetryInitializerFunction): ITelemetryInitializerHandler | void;
+    addTelemetryInitializer(telemetryInitializer: TelemetryInitializerFunction): ITelemetryInitializerHandler;
     addUnloadCb(handler: UnloadHandler): void;
+    addUnloadHook(hooks: IUnloadHook | IUnloadHook[] | Iterator<IUnloadHook> | ILegacyUnloadHook | ILegacyUnloadHook[] | Iterator<ILegacyUnloadHook>): void;
     // (undocumented)
     config: IConfiguration;
     // (undocumented)
@@ -128,6 +107,7 @@ export class BaseCore implements IAppInsightsCore {
     isInitialized: () => boolean;
     // (undocumented)
     logger: IDiagnosticLogger;
+    onCfgChange<T extends IConfiguration = IConfiguration>(handler: WatcherFunction<T>): IUnloadHook;
     pollInternalLogs(eventName?: string): number;
     // (undocumented)
     protected releaseQueue(): void;
@@ -140,13 +120,33 @@ export class BaseCore implements IAppInsightsCore {
     // (undocumented)
     track(telemetryItem: ITelemetryItem): void;
     unload(isAsync?: boolean, unloadComplete?: (unloadState: ITelemetryUnloadState) => void, cbTimeout?: number): void;
+    updateCfg<T extends IConfiguration = IConfiguration>(newConfig: T, mergeExisting?: boolean): void;
     protected _updateHook?(updateCtx: IProcessTelemetryUpdateContext, updateState: ITelemetryUpdateState): void | boolean;
 }
 
+// @public (undocumented)
+export function applyDefaults<C>(theConfig: C, defaultValues: IConfigDefaults<C>): C;
+
+// @public (undocumented)
+export function areCookiesSupported(logger?: IDiagnosticLogger): any;
+
+export { arrForEach }
+
+export { arrIndexOf }
+
+export { arrMap }
+
+export { arrReduce }
+
+export { asString }
+
+// @public
+export function attachEvent(obj: any, eventNameWithoutOn: string, handlerRef: any, useCapture?: boolean): boolean;
+
 // @public
 export abstract class BaseTelemetryPlugin implements ITelemetryPlugin {
     constructor();
-    protected _addHook(hooks: IInstrumentHook | IInstrumentHook[]): void;
+    protected _addHook(hooks: IUnloadHook | IUnloadHook[] | ILegacyUnloadHook | ILegacyUnloadHook[]): void;
     protected _addUnloadCb(handler: UnloadHandler): void;
     core: IAppInsightsCore;
     diagLog: (itemCtx?: IProcessTelemetryContext) => IDiagnosticLogger;
@@ -177,13 +177,16 @@ export function createClassFromInterface<T>(defaults?: T): new () => T;
 // @public (undocumented)
 export function createCookieMgr(rootConfig?: IConfiguration, logger?: IDiagnosticLogger): ICookieMgr;
 
+// @public
+export function createDynamicConfig<T extends IConfiguration>(config: T, defaultConfig?: IConfigDefaults<T>, logger?: IDiagnosticLogger, inPlace?: boolean): IDynamicConfigHandler<T>;
+
 // @public
 export const createEnumStyle: <E>(values: {
     [key in keyof E]: E[keyof E];
 }) => EnumValue<E>;
 
 // @public
-export function createProcessTelemetryContext(telemetryChain: ITelemetryPluginChain | null, config: IConfiguration, core: IAppInsightsCore, startAt?: IPlugin): IProcessTelemetryContext;
+export function createProcessTelemetryContext(telemetryChain: ITelemetryPluginChain | null, cfg: IConfiguration, core: IAppInsightsCore, startAt?: IPlugin): IProcessTelemetryContext;
 
 // @public
 export function createTraceParent(traceId?: string, spanId?: string, flags?: number, version?: string): ITraceParent;
@@ -223,7 +226,9 @@ export class DiagnosticLogger implements IDiagnosticLogger {
     queue: _InternalLogMessage[];
     resetInternalMessageCount(): void;
     telemetryLoggingLevel(): number;
-    throwInternal(severity: LoggingSeverity, msgId: _InternalMessageId, msg: string, properties?: Object, isUserAct?: boolean): void;
+    throwInternal(severity: LoggingSeverity, msgId: _eInternalMessageId, msg: string, properties?: Object, isUserAct?: boolean): void;
+    // (undocumented)
+    update(updateState: ITelemetryUpdateState): void;
     warnToConsole(message: string): void;
 }
 
@@ -275,8 +280,12 @@ export const enum _eInternalMessageId {
     // (undocumented)
     ClientPerformanceMathError = 8,
     // (undocumented)
+    ConfigWatcherException = 107,
+    // (undocumented)
     CreateEnvelopeError = 47,
     // (undocumented)
+    DynamicConfigException = 108,
+    // (undocumented)
     ErrorParsingAISessionCookie = 9,
     // (undocumented)
     ErrorPVCalc = 10,
@@ -415,6 +424,7 @@ export const enum _eInternalMessageId {
 // @public (undocumented)
 export const enum eLoggingSeverity {
     CRITICAL = 1,
+    DISABLED = 0,
     WARNING = 2
 }
 
@@ -462,19 +472,14 @@ export function getDebugListener(config: IConfiguration): INotificationListener;
 
 export { getDocument }
 
+// Warning: (ae-internal-missing-underscore) The name "getDynamicConfigHandler" should be prefixed with an underscore because the declaration is marked as @internal
+//
+// @internal
+export function getDynamicConfigHandler<T>(value: T | IDynamicConfigHandler<T>): IDynamicConfigHandler<T> | null;
+
 // @public
 export function getExceptionName(object: any): string;
 
-// @public (undocumented)
-export const enum GetExtCfgMergeType {
-    // (undocumented)
-    MergeDefaultFromRootOrDefault = 2,
-    // (undocumented)
-    MergeDefaultOnly = 1,
-    // (undocumented)
-    None = 0
-}
-
 // @public
 export function getGblPerfMgr(): IPerfManager;
 
@@ -523,8 +528,9 @@ export { hasWindow }
 export interface IAppInsightsCore extends IPerfManagerProvider {
     addNotificationListener?(listener: INotificationListener): void;
     addPlugin<T extends IPlugin = ITelemetryPlugin>(plugin: T, replaceExisting?: boolean, doAsync?: boolean, addCb?: (added?: boolean) => void): void;
-    addTelemetryInitializer(telemetryInitializer: TelemetryInitializerFunction): ITelemetryInitializerHandler | void;
+    addTelemetryInitializer(telemetryInitializer: TelemetryInitializerFunction): ITelemetryInitializerHandler;
     addUnloadCb(handler: UnloadHandler): void;
+    addUnloadHook(hooks: IUnloadHook | IUnloadHook[] | Iterator<IUnloadHook> | ILegacyUnloadHook | ILegacyUnloadHook[] | Iterator<ILegacyUnloadHook>): void;
     // (undocumented)
     config: IConfiguration;
     evtNamespace(): string;
@@ -541,6 +547,7 @@ export interface IAppInsightsCore extends IPerfManagerProvider {
     isInitialized?: () => boolean;
     // (undocumented)
     logger: IDiagnosticLogger;
+    onCfgChange<T extends IConfiguration = IConfiguration>(handler: WatcherFunction<T>): IUnloadHook;
     // (undocumented)
     pollInternalLogs?(eventName?: string): number;
     removeNotificationListener?(listener: INotificationListener): void;
@@ -551,6 +558,7 @@ export interface IAppInsightsCore extends IPerfManagerProvider {
     // (undocumented)
     track(telemetryItem: ITelemetryItem): void;
     unload(isAsync?: boolean, unloadComplete?: (unloadState: ITelemetryUnloadState) => void, cbTimeout?: number): void;
+    updateCfg<T extends IConfiguration = IConfiguration>(newConfig: T, mergeExisting?: boolean): void;
 }
 
 // @public (undocumented)
@@ -560,7 +568,7 @@ export interface IBaseProcessingContext {
     diagLog: () => IDiagnosticLogger;
     getCfg: () => IConfiguration;
     getConfig: (identifier: string, field: string, defaultValue?: number | string | boolean | string[] | RegExp[] | Function) => number | string | boolean | string[] | RegExp[] | Function;
-    getExtCfg: <T>(identifier: string, defaultValue?: T | any, mergeDefault?: GetExtCfgMergeType) => T;
+    getExtCfg: <T>(identifier: string, defaultValue?: IConfigDefaults<T>) => T;
     getNext: () => ITelemetryPluginChain;
     hasNext: () => boolean;
     iterate: <T extends ITelemetryPlugin = ITelemetryPlugin>(callback: (plugin: T) => void) => void;
@@ -576,6 +584,26 @@ export interface IChannelControls extends ITelemetryPlugin {
     teardown: (unloadCtx?: IProcessTelemetryUnloadContext, unloadState?: ITelemetryUnloadState) => void | boolean;
 }
 
+// @public
+export type IConfigCheckFn<V> = (value: V) => boolean;
+
+// @public
+export interface IConfigDefaultCheck<T, V, C extends IConfiguration = IConfiguration> {
+    dfVal?: (value: any) => boolean;
+    fb?: keyof T | keyof C | Array<keyof T | keyof C>;
+    isVal?: IConfigCheckFn<V>;
+    set?: IConfigSetFn<T, V>;
+    v?: V;
+}
+
+// @public
+export type IConfigDefaults<T, C extends IConfiguration = IConfiguration> = {
+    [key in keyof T]: T[key] | IConfigDefaultCheck<T, T[key], C>;
+};
+
+// @public
+export type IConfigSetFn<T, V> = (value: any, defValue: V, theConfig: T) => V;
+
 // @public
 export interface IConfiguration {
     channels?: IChannelControls[][];
@@ -613,6 +641,7 @@ export interface ICookieMgr {
     purge(name: string, path?: string): boolean;
     set(name: string, value: string, maxAgeSec?: number, domain?: string, path?: string): boolean;
     setEnabled(value: boolean): void;
+    update?(updateState: ITelemetryUpdateState): void;
 }
 
 // @public
@@ -661,7 +690,8 @@ export interface IDiagnosticLogger {
     queue: _InternalLogMessage[];
     resetInternalMessageCount(): void;
     telemetryLoggingLevel: () => number;
-    throwInternal(severity: LoggingSeverity, msgId: _InternalMessageId, msg: string, properties?: Object, isUserAct?: boolean): void;
+    throwInternal(severity: LoggingSeverity, msgId: _eInternalMessageId, msg: string, properties?: Object, isUserAct?: boolean): void;
+    update?(updateState: ITelemetryUpdateState): void;
     warnToConsole(message: string): void;
 }
 
@@ -677,6 +707,22 @@ export interface IDistributedTraceContext {
     setTraceId(newValue: string): void;
 }
 
+// @public
+export interface IDynamicConfigHandler<T extends IConfiguration> {
+    cfg: T;
+    logger: IDiagnosticLogger;
+    notify: () => void;
+    set: <C, V>(theConfig: C, name: string, value: V) => V;
+    readonly uid: string;
+    watch: (configHandler: WatcherFunction<T>) => IWatcherHandler<T>;
+}
+
+// @public (undocumented)
+export interface IDynamicPropertyHandler<T> {
+    h: IWatcherHandler<T>[];
+    n: string;
+}
+
 // @public (undocumented)
 export interface IInstrumentCallDetails {
     ctx: () => any;
@@ -691,7 +737,7 @@ export interface IInstrumentCallDetails {
 }
 
 // @public
-export interface IInstrumentHook {
+export interface IInstrumentHook extends IUnloadHook {
     cbks: IInstrumentHooksCallbacks;
     id: number;
     rm: () => void;
@@ -718,6 +764,11 @@ export interface IInstrumentHooksCallbacks {
     rsp?: InstrumentorHooksCallback;
 }
 
+// @public
+export interface ILegacyUnloadHook {
+    remove: () => void;
+}
+
 // @public (undocumented)
 export interface ILoadedPlugin<T extends IPlugin> {
     isEnabled: () => boolean;
@@ -771,21 +822,15 @@ export function InstrumentProtos(target: any, funcNames: string[], callbacks: II
 
 // @public (undocumented)
 export class _InternalLogMessage {
-    constructor(msgId: _InternalMessageId, msg: string, isUserAct?: boolean, properties?: Object);
+    constructor(msgId: _eInternalMessageId, msg: string, isUserAct?: boolean, properties?: Object);
     // (undocumented)
     static dataType: string;
     // (undocumented)
     message: string;
     // (undocumented)
-    messageId: _InternalMessageId;
+    messageId: _eInternalMessageId;
 }
 
-// @public
-export const _InternalMessageId: EnumValue<typeof _eInternalMessageId>;
-
-// @public (undocumented)
-export type _InternalMessageId = number | _eInternalMessageId;
-
 // @public
 export interface IPerfEvent {
     childEvts?: IPerfEvent[];
@@ -922,7 +967,7 @@ export interface ITelemetryInitializerContainer {
 }
 
 // @public (undocumented)
-export interface ITelemetryInitializerHandler {
+export interface ITelemetryInitializerHandler extends ILegacyUnloadHook {
     // (undocumented)
     remove(): void;
 }
@@ -972,6 +1017,10 @@ export interface ITelemetryUnloadState {
 // @public (undocumented)
 export interface ITelemetryUpdateState {
     added?: IPlugin[];
+    cfg?: IConfiguration;
+    merge?: boolean;
+    newConfig?: IConfiguration;
+    oldCfg?: IConfiguration;
     reason: TelemetryUpdateReason;
     removed?: IPlugin[];
 }
@@ -997,6 +1046,27 @@ export interface IUnloadHandlerContainer {
     run: (itemCtx: IProcessTelemetryUnloadContext, unloadState: ITelemetryUnloadState) => void;
 }
 
+// @public
+export interface IUnloadHook {
+    rm: () => void;
+}
+
+// @public (undocumented)
+export interface IWatchDetails<T extends IConfiguration> {
+    // (undocumented)
+    cfg: T;
+    // (undocumented)
+    hdlr: IDynamicConfigHandler<T>;
+}
+
+// @public (undocumented)
+export interface IWatcherHandler<T extends IConfiguration> extends IUnloadHook {
+    // (undocumented)
+    fn: WatcherFunction<T>;
+    // (undocumented)
+    rm: () => void;
+}
+
 // @public (undocumented)
 export const LoggingSeverity: EnumValue<typeof eLoggingSeverity>;
 
@@ -1060,6 +1130,9 @@ export { objSeal }
 
 export { objToString }
 
+// @public
+export function onConfigChange<T>(config: T, configHandler: WatcherFunction<T>, logger?: IDiagnosticLogger): IWatcherHandler<T>;
+
 // @public
 export function optimizeObject<T>(theObject: T): T;
 
@@ -1110,7 +1183,7 @@ export class ProcessTelemetryContext implements IProcessTelemetryContext {
     // (undocumented)
     getConfig: (identifier: string, field: string, defaultValue?: number | string | boolean | string[] | RegExp[] | Function) => number | string | boolean | string[] | RegExp[] | Function;
     // (undocumented)
-    getExtCfg: <T>(identifier: string, defaultValue?: T | any) => T;
+    getExtCfg: <T>(identifier: string, defaultValue?: IConfigDefaults<T>) => T;
     getNext: () => ITelemetryPluginChain;
     hasNext: () => boolean;
     iterate: <T extends ITelemetryPlugin = ITelemetryPlugin>(callback: (plugin: T) => void) => void;
@@ -1217,6 +1290,7 @@ export const enum TelemetryUnloadReason {
 
 // @public
 export const enum TelemetryUpdateReason {
+    ConfigurationChanged = 1,
     PluginAdded = 16,
     PluginRemoved = 32,
     Unknown = 0
@@ -1225,10 +1299,10 @@ export const enum TelemetryUpdateReason {
 export { throwError }
 
 // @public
-export function _throwInternal(logger: IDiagnosticLogger, severity: LoggingSeverity, msgId: _InternalMessageId, msg: string, properties?: Object, isUserAct?: boolean): void;
+export function _throwInternal(logger: IDiagnosticLogger, severity: LoggingSeverity, msgId: _eInternalMessageId, msg: string, properties?: Object, isUserAct?: boolean): void;
 
 // @public
-export function toISOString(date: Date): any;
+export function toISOString(date: Date): string;
 
 // @public (undocumented)
 export function uaDisallowsSameSiteNone(userAgent: string): boolean;
@@ -1248,6 +1322,9 @@ export function useXDomainRequest(): boolean | undefined;
 // @public
 export function _warnToConsole(logger: IDiagnosticLogger, message: string): void;
 
+// @public (undocumented)
+export type WatcherFunction<T extends IConfiguration> = (details: IWatchDetails<T>) => void;
+
 // (No @packageDocumentation comment for this package)
 
 ```