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

package/types/Config/DynamicSupport.d.ts

@@ -8,6 +8,73 @@ export declare function _cfgDeepCopy<T>(source: T): T;
  * @returns
  */
 export declare function getDynamicConfigHandler<T>(value: T | IDynamicConfigHandler<T>): IDynamicConfigHandler<T> | null;
+/**
+ * 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
+ */
+export declare function blockDynamicConversion<T>(value: T): T;
+/**
+ * This is the reverse case of {@link blockDynamicConversion} in that this will tag an
+ * object to indicate that it should always be converted into a dynamic trackable object
+ * even when not an object or array. So all properties of this object will become
+ * get / set accessor functions.
+ *
+ * When you have tagged a value as both {@link forceDynamicConversion} and blocked force will take precedence.
+ *
+ * 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.
+ * @param value - The object that should be tagged and converted if included into a dynamic
+ * configuration.
+ * @returns The original value
+ */
+export declare function forceDynamicConversion<T>(value: T): T;
+/**
+ * @internal
+ * @ignore
+ * Helper function to check whether an object can or should be converted into a dynamic
+ * object.
+ * @param value - The object to check whether it should be converted
+ * @returns `true` if the value should be converted otherwise `false`.
+ */
+export declare function _canMakeDynamic<T>(value: any): boolean;
 /**
  * Throws an invalid access exception
  * @param message - The message to include in the exception

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

@@ -54,5 +54,5 @@ export { IDynamicConfigHandler } from "./Config/IDynamicConfigHandler";
 export { IDynamicPropertyHandler } from "./Config/IDynamicPropertyHandler";
 export { IWatchDetails, IWatcherHandler, WatcherFunction } from "./Config/IDynamicWatcher";
 export { createDynamicConfig, onConfigChange } from "./Config/DynamicConfig";
-export { getDynamicConfigHandler } from "./Config/DynamicSupport";
+export { getDynamicConfigHandler, blockDynamicConversion } from "./Config/DynamicSupport";
 export { cfgDfValidate, cfgDfMerge, cfgDfBoolean, cfgDfFunc, cfgDfString, cfgDfSet } from "./Config/ConfigDefaultHelpers";