@microsoft/applicationinsights-core-js 3.0.0-beta.2303-06 → 3.0.0-beta.2303-10

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

@@ -6000,6 +6000,64 @@
             }
           ]
         },
+        {
+          "kind": "Function",
+          "canonicalReference": "@microsoft/applicationinsights-core-js!blockDynamicConversion:function(1)",
+          "docComment": "/**\n * Mark the provided value so that if it's included into the configuration it will NOT have its properties converted into a dynamic (reactive) object. If the object is not a plain object or an array (ie. a class) this function has not affect as only Objects and Arrays are converted into dynamic objects in the dynamic configuration.\n *\n * When you have tagged a value as both {@link forceDynamicConversion} and blocked force will take precedence.\n *\n * You should only need to use this function, if you are creating dynamic \"classes\" from objects which confirm to the require interface. A common case for this is during unit testing where it's easier to create mock extensions.\n *\n * If `value` is falsy (null / undefined / 0 / empty string etc) it will not be tagged and if there is an exception adding the property to the value (because its frozen etc) the exception will be swallowed\n *\n * @param value - The object that you want to block from being converted into a trackable dynamic object\n *\n * @returns The original value\n *\n * @example\n * ```ts\n * // This is a valid \"extension\", but it is technically an object\n * // So when included in the config.extensions it WILL be cloned and then\n * // converted into a dynamic object, where all of its properties will become\n * // get/set object properties and will be tracked. While this WILL still\n * // function, when attempt to use a mocking framework on top of this the\n * // functions are now technically get accessors which return a function\n * // and this can cause some mocking frameworks to fail.\n * let mockChannel = {\n *      pause: () => { },\n *      resume: () => { },\n *      teardown: () => { },\n *      flush: (async: any, callBack: any) => { },\n *      processTelemetry: (env: any) => { },\n *      setNextPlugin: (next: any) => { },\n *      initialize: (config: any, core: any, extensions: any) => { },\n *      identifier: \"testChannel\",\n *      priority: 1003\n * };\n * ```\n *\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export declare function blockDynamicConversion<T>(value: "
+            },
+            {
+              "kind": "Content",
+              "text": "T"
+            },
+            {
+              "kind": "Content",
+              "text": "): "
+            },
+            {
+              "kind": "Content",
+              "text": "T"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "types/Config/DynamicSupport.d.ts",
+          "returnTypeTokenRange": {
+            "startIndex": 3,
+            "endIndex": 4
+          },
+          "releaseTag": "Public",
+          "overloadIndex": 1,
+          "parameters": [
+            {
+              "parameterName": "value",
+              "parameterTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isOptional": false
+            }
+          ],
+          "typeParameters": [
+            {
+              "typeParameterName": "T",
+              "constraintTokenRange": {
+                "startIndex": 0,
+                "endIndex": 0
+              },
+              "defaultTypeTokenRange": {
+                "startIndex": 0,
+                "endIndex": 0
+              }
+            }
+          ],
+          "name": "blockDynamicConversion"
+        },
         {
           "kind": "Function",
           "canonicalReference": "@microsoft/applicationinsights-core-js!cfgDfBoolean:function(1)",
@@ -11613,6 +11671,114 @@
             }
           ]
         },
+        {
+          "kind": "Interface",
+          "canonicalReference": "@microsoft/applicationinsights-core-js!IChannelControlsHost:interface",
+          "docComment": "",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export interface IChannelControlsHost extends "
+            },
+            {
+              "kind": "Reference",
+              "text": "IChannelControls",
+              "canonicalReference": "@microsoft/applicationinsights-core-js!IChannelControls:interface"
+            },
+            {
+              "kind": "Content",
+              "text": " "
+            }
+          ],
+          "fileUrlPath": "types/JavaScriptSDK.Interfaces/IChannelControlsHost.d.ts",
+          "releaseTag": "Public",
+          "name": "IChannelControlsHost",
+          "preserveMemberOrder": false,
+          "members": [
+            {
+              "kind": "MethodSignature",
+              "canonicalReference": "@microsoft/applicationinsights-core-js!IChannelControlsHost#getChannel:member(1)",
+              "docComment": "/**\n * Get and return the named channel instance (if present) from the queues\n *\n * @param pluginIdentifier - The identifier name of the plugin\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "getChannel<T extends "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "IPlugin",
+                  "canonicalReference": "@microsoft/applicationinsights-core-js!IPlugin:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": " = "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "IPlugin",
+                  "canonicalReference": "@microsoft/applicationinsights-core-js!IPlugin:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": ">(pluginIdentifier: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": "): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "T"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isOptional": false,
+              "returnTypeTokenRange": {
+                "startIndex": 7,
+                "endIndex": 8
+              },
+              "releaseTag": "Public",
+              "overloadIndex": 1,
+              "parameters": [
+                {
+                  "parameterName": "pluginIdentifier",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 5,
+                    "endIndex": 6
+                  },
+                  "isOptional": false
+                }
+              ],
+              "typeParameters": [
+                {
+                  "typeParameterName": "T",
+                  "constraintTokenRange": {
+                    "startIndex": 1,
+                    "endIndex": 2
+                  },
+                  "defaultTypeTokenRange": {
+                    "startIndex": 3,
+                    "endIndex": 4
+                  }
+                }
+              ],
+              "name": "getChannel"
+            }
+          ],
+          "extendsTokenRanges": [
+            {
+              "startIndex": 1,
+              "endIndex": 2
+            }
+          ]
+        },
         {
           "kind": "TypeAlias",
           "canonicalReference": "@microsoft/applicationinsights-core-js!IConfigCheckFn:type",
@@ -12098,7 +12264,7 @@
               "excerptTokens": [
                 {
                   "kind": "Content",
-                  "text": "channels?: "
+                  "text": "readonly channels?: "
                 },
                 {
                   "kind": "Reference",
@@ -12114,7 +12280,7 @@
                   "text": ";"
                 }
               ],
-              "isReadonly": false,
+              "isReadonly": true,
               "isOptional": true,
               "releaseTag": "Public",
               "name": "channels",
@@ -12586,7 +12752,7 @@
               "excerptTokens": [
                 {
                   "kind": "Content",
-                  "text": "extensions?: "
+                  "text": "readonly extensions?: "
                 },
                 {
                   "kind": "Reference",
@@ -12602,7 +12768,7 @@
                   "text": ";"
                 }
               ],
-              "isReadonly": false,
+              "isReadonly": true,
               "isOptional": true,
               "releaseTag": "Public",
               "name": "extensions",

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

@@ -171,6 +171,9 @@ export abstract class BaseTelemetryPlugin implements ITelemetryPlugin {
     version?: string;
 }
 
+// @public
+export function blockDynamicConversion<T>(value: T): T;
+
 // @public
 export function cfgDfBoolean<T, C = IConfiguration>(defaultValue?: boolean, fallBackName?: keyof T | keyof C | Array<keyof T | keyof C>): IConfigDefaultCheck<T, boolean, C>;
 
@@ -602,6 +605,11 @@ export interface IChannelControls extends ITelemetryPlugin {
     teardown?: (unloadCtx?: IProcessTelemetryUnloadContext, unloadState?: ITelemetryUnloadState) => void | boolean;
 }
 
+// @public (undocumented)
+export interface IChannelControlsHost extends IChannelControls {
+    getChannel<T extends IPlugin = IPlugin>(pluginIdentifier: string): T;
+}
+
 // @public
 export type IConfigCheckFn<V> = (value: V) => boolean;
 
@@ -627,7 +635,7 @@ export type IConfigSetFn<T, V> = (value: any, defValue: V, theConfig: T) => V;
 
 // @public
 export interface IConfiguration {
-    channels?: IChannelControls[][];
+    readonly channels?: IChannelControls[][];
     connectionString?: string;
     cookieCfg?: ICookieMgrConfig;
     cookieDomain?: string;
@@ -646,7 +654,7 @@ export interface IConfiguration {
     extensionConfig?: {
         [key: string]: any;
     };
-    extensions?: ITelemetryPlugin[];
+    readonly extensions?: ITelemetryPlugin[];
     idLength?: number;
     instrumentationKey?: string;
     loggingLevelConsole?: number;

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

@@ -1,5 +1,5 @@
 /*
- * Microsoft Application Insights Core Javascript SDK, 3.0.0-beta.2303-06
+ * Microsoft Application Insights Core Javascript SDK, 3.0.0-beta.2303-10
  * Copyright (c) Microsoft and contributors. All rights reserved.
  *
  * Microsoft Application Insights Team
@@ -389,6 +389,49 @@ declare namespace ApplicationInsights {
         protected _addHook(hooks: IUnloadHook | IUnloadHook[] | Iterator<IUnloadHook> | ILegacyUnloadHook | ILegacyUnloadHook[] | Iterator<ILegacyUnloadHook>): void;
     }
 
+    /**
+     * Mark the provided value so that if it's included into the configuration it will NOT have
+     * its properties converted into a dynamic (reactive) object. If the object is not a plain object
+     * or an array (ie. a class) this function has not affect as only Objects and Arrays are converted
+     * into dynamic objects in the dynamic configuration.
+     *
+     * When you have tagged a value as both {@link forceDynamicConversion} and blocked force will take precedence.
+     *
+     * You should only need to use this function, if you are creating dynamic "classes" from objects
+     * which confirm to the require interface. A common case for this is during unit testing where it's
+     * easier to create mock extensions.
+     *
+     * If `value` is falsy (null / undefined / 0 / empty string etc) it will not be tagged and
+     * if there is an exception adding the property to the value (because its frozen etc) the
+     * exception will be swallowed
+     *
+     * @example
+     * ```ts
+     * // This is a valid "extension", but it is technically an object
+     * // So when included in the config.extensions it WILL be cloned and then
+     * // converted into a dynamic object, where all of its properties will become
+     * // get/set object properties and will be tracked. While this WILL still
+     * // function, when attempt to use a mocking framework on top of this the
+     * // functions are now technically get accessors which return a function
+     * // and this can cause some mocking frameworks to fail.
+     * let mockChannel = {
+     *      pause: () => { },
+     *      resume: () => { },
+     *      teardown: () => { },
+     *      flush: (async: any, callBack: any) => { },
+     *      processTelemetry: (env: any) => { },
+     *      setNextPlugin: (next: any) => { },
+     *      initialize: (config: any, core: any, extensions: any) => { },
+     *      identifier: "testChannel",
+     *      priority: 1003
+     * };
+     * ```
+     * @param value - The object that you want to block from being converted into a
+     * trackable dynamic object
+     * @returns The original value
+     */
+    function blockDynamicConversion<T>(value: T): T;
+
     /**
      * Helper which returns an IConfigDefaultCheck instance that will validate and convert the user
      * provided value to a boolean from a string or boolean value
@@ -1128,6 +1171,14 @@ declare namespace ApplicationInsights {
         flush?(async: boolean, callBack?: (flushComplete?: boolean) => void, sendReason?: SendRequestReason): boolean | void;
     }
 
+    interface IChannelControlsHost extends IChannelControls {
+        /**
+         * Get and return the named channel instance (if present) from the queues
+         * @param pluginIdentifier - The identifier name of the plugin
+         */
+        getChannel<T extends IPlugin = IPlugin>(pluginIdentifier: string): T;
+    }
+
     /**
      * The type to identify whether the default value should be applied in preference to the provided value.
      */
@@ -1255,12 +1306,12 @@ declare namespace ApplicationInsights {
         /**
          * Additional plugins that should be loaded by core at runtime
          */
-        extensions?: ITelemetryPlugin[];
+        readonly extensions?: ITelemetryPlugin[];
         /**
          * Channel queues that is setup by caller in desired order.
          * If channels are provided here, core will ignore any channels that are already setup, example if there is a SKU with an initialized channel
          */
-        channels?: IChannelControls[][];
+        readonly channels?: IChannelControls[][];
         /**
          * @type {boolean}
          * Flag that disables the Instrumentation Key validation.