@fluidframework/core-utils 2.20.0 → 2.21.0

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @fluidframework/core-utils
 
+## 2.21.0
+
+Dependency updates only.
+
 ## 2.20.0
 
 Dependency updates only.

package/dist/assert.d.ts

@@ -3,16 +3,82 @@
  * Licensed under the MIT License.
  */
 /**
- * A browser friendly assert library.
- * Use this instead of the 'assert' package, which has a big impact on bundle sizes.
+ * Asserts the specified condition.
+ *
  * @param condition - The condition that should be true, if the condition is false an error will be thrown.
  * Only use this API when `false` indicates a logic error in the problem and thus a bug that should be fixed.
  * @param message - The message to include in the error when the condition does not hold.
  * A number should not be specified manually: use a string.
  * Before a release, policy-check should be run, which will convert any asserts still using strings to
  * use numbered error codes instead.
+ * @remarks
+ * Use this instead of the node 'assert' package, which requires polyfills and has a big impact on bundle sizes.
+ *
+ * Assertions using this API will be included in all configurations: there is no option to disable or optimize them out.
+ * Thus this API is suitable for detecting conditions that should terminate the application and produce a useful diagnostic message.
+ * It can be used to ensure bad states are detected early and to avoid data corruption or harder to debug errors.
+ *
+ * In cases where the assert is very unlikely to have an impact on production code but is still useful as documentation and for debugging, consider using `debugAssert` instead
+ * to optimize bundle size.
+ *
+ * This API is not intended for use outside of the Fluid Framework client codebase: it will most likely be made internal in the future.
+ * @privateRemarks
+ * This should be deprecated (as a non internal API) then moved to purely internal.
+ * When done the `debugAssert` reference above should be turned into a link.
  * @legacy
  * @alpha
  */
 export declare function assert(condition: boolean, message: string | number): asserts condition;
+/**
+ * Asserts that can be conditionally enabled in debug/development builds but will be optimized out of production builds.
+ *
+ * Disabled by default.
+ *
+ * If the assert must be enforced/checked in production or enabled by default, use {@link assert} instead.
+ *
+ * @param predicate - A pure function that should return true if the condition holds, or a string or object describing the condition that failed.
+ * This function will only be run in some configurations so it should be pure, and only used to detect bugs (when debugAssert are enabled), and must not be relied on to enforce the condition is true: for that use {@link assert}.
+ * @remarks
+ * Optimizing the asserts out of the bundle requires a bundler like webpack which leverages `__PURE__` annotations like https://webpack.js.org/guides/tree-shaking/#mark-a-function-call-as-side-effect-free.
+ *
+ * Exceptions thrown by this function must never be caught in production code, as that will result in different behavior when testing and when running optimized builds.
+ * The `predicate` function must be pure (have no side-effects) to ensure that the behavior of code is the same regardless of if the asserts are disabled, enabled or optimized out.
+ *
+ * These asserts are disabled by default, even in debug builds to ensure that by default code will be tested as production runs, with them disabled.
+ * Additionally, this ensures that apps that use a bundler which does not remove `__PURE__` will not incur the runtime cost of calling the predicate.
+ * These asserts can be can be enabled by calling `configureDebugAsserts(true)`: see {@link configureDebugAsserts}.
+ *
+ * @privateRemarks
+ * This design was chosen to accomplish two main goals:
+ *
+ * 1. Make it easy to compile debug asserts fully out of production builds.
+ * For webpack this happens by default, avoiding the need for customers to do special configuration.
+ * This is important for both performance and bundle size.
+ *
+ * 2. Make it easy to test (both manually and automated) with and without the predicates running.
+ * This ensures it is possible to benefit from the asserts when enabled, but also test with them disabled to ensure this disablement doesn't cause bugs.
+ *
+ * The default behavior of having debugAsserts disabled helps ensure that tests which don't know about debug asserts will still run in a way that is most similar to production.
+ * @internal
+ */
+export declare function debugAssert(predicate: () => true | {
+    toString(): string;
+}): void;
+/**
+ * Enables {@link debugAssert} validation.
+ * @remarks
+ * Throws if debugAsserts have been optimized out.
+ * @returns The previous state of debugAsserts.
+ * @internal
+ */
+export declare function configureDebugAsserts(enabled: boolean): boolean;
+/**
+ * Checks if non-production conditional code like {@link debugAssert} is included in this build.
+ * @remarks
+ * Such code can be optimized out by bundlers: this checks if that has occurred.
+ * @privateRemarks
+ * See {@link skipInProduction}.
+ * @internal
+ */
+export declare function nonProductionConditionalsIncluded(): boolean;
 //# sourceMappingURL=assert.d.ts.map

package/dist/assert.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"assert.d.ts","sourceRoot":"","sources":["../src/assert.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;GAWG;AACH,wBAAgB,MAAM,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,SAAS,CAMtF"}
+{"version":3,"file":"assert.d.ts","sourceRoot":"","sources":["../src/assert.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,MAAM,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,SAAS,CAMtF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,IAAI,GAAG;IAAE,QAAQ,IAAI,MAAM,CAAA;CAAE,GAAG,IAAI,CAahF;AAID;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAQ/D;AAED;;;;;;;GAOG;AACH,wBAAgB,iCAAiC,IAAI,OAAO,CAM3D"}

package/dist/assert.js

@@ -4,16 +4,30 @@
  * Licensed under the MIT License.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.assert = void 0;
+exports.nonProductionConditionalsIncluded = exports.configureDebugAsserts = exports.debugAssert = exports.assert = void 0;
 /**
- * A browser friendly assert library.
- * Use this instead of the 'assert' package, which has a big impact on bundle sizes.
+ * Asserts the specified condition.
+ *
  * @param condition - The condition that should be true, if the condition is false an error will be thrown.
  * Only use this API when `false` indicates a logic error in the problem and thus a bug that should be fixed.
  * @param message - The message to include in the error when the condition does not hold.
  * A number should not be specified manually: use a string.
  * Before a release, policy-check should be run, which will convert any asserts still using strings to
  * use numbered error codes instead.
+ * @remarks
+ * Use this instead of the node 'assert' package, which requires polyfills and has a big impact on bundle sizes.
+ *
+ * Assertions using this API will be included in all configurations: there is no option to disable or optimize them out.
+ * Thus this API is suitable for detecting conditions that should terminate the application and produce a useful diagnostic message.
+ * It can be used to ensure bad states are detected early and to avoid data corruption or harder to debug errors.
+ *
+ * In cases where the assert is very unlikely to have an impact on production code but is still useful as documentation and for debugging, consider using `debugAssert` instead
+ * to optimize bundle size.
+ *
+ * This API is not intended for use outside of the Fluid Framework client codebase: it will most likely be made internal in the future.
+ * @privateRemarks
+ * This should be deprecated (as a non internal API) then moved to purely internal.
+ * When done the `debugAssert` reference above should be turned into a link.
  * @legacy
  * @alpha
  */
@@ -23,4 +37,108 @@ function assert(condition, message) {
     }
 }
 exports.assert = assert;
+/**
+ * Asserts that can be conditionally enabled in debug/development builds but will be optimized out of production builds.
+ *
+ * Disabled by default.
+ *
+ * If the assert must be enforced/checked in production or enabled by default, use {@link assert} instead.
+ *
+ * @param predicate - A pure function that should return true if the condition holds, or a string or object describing the condition that failed.
+ * This function will only be run in some configurations so it should be pure, and only used to detect bugs (when debugAssert are enabled), and must not be relied on to enforce the condition is true: for that use {@link assert}.
+ * @remarks
+ * Optimizing the asserts out of the bundle requires a bundler like webpack which leverages `__PURE__` annotations like https://webpack.js.org/guides/tree-shaking/#mark-a-function-call-as-side-effect-free.
+ *
+ * Exceptions thrown by this function must never be caught in production code, as that will result in different behavior when testing and when running optimized builds.
+ * The `predicate` function must be pure (have no side-effects) to ensure that the behavior of code is the same regardless of if the asserts are disabled, enabled or optimized out.
+ *
+ * These asserts are disabled by default, even in debug builds to ensure that by default code will be tested as production runs, with them disabled.
+ * Additionally, this ensures that apps that use a bundler which does not remove `__PURE__` will not incur the runtime cost of calling the predicate.
+ * These asserts can be can be enabled by calling `configureDebugAsserts(true)`: see {@link configureDebugAsserts}.
+ *
+ * @privateRemarks
+ * This design was chosen to accomplish two main goals:
+ *
+ * 1. Make it easy to compile debug asserts fully out of production builds.
+ * For webpack this happens by default, avoiding the need for customers to do special configuration.
+ * This is important for both performance and bundle size.
+ *
+ * 2. Make it easy to test (both manually and automated) with and without the predicates running.
+ * This ensures it is possible to benefit from the asserts when enabled, but also test with them disabled to ensure this disablement doesn't cause bugs.
+ *
+ * The default behavior of having debugAsserts disabled helps ensure that tests which don't know about debug asserts will still run in a way that is most similar to production.
+ * @internal
+ */
+function debugAssert(predicate) {
+    // This is valid since the contract for this function is that "predicate" should be side effect free and never return non true in production scenarios:
+    // it returning non-true indicates a bug is present, and that the validation it does to detect the bug is only desired in specific test/debug situations.
+    // Production scenarios, where pure code is removed, should never hit a failing predicate, and thus this code should be side effect free.
+    skipInProduction(() => {
+        if (debugAssertsEnabled) {
+            const result = predicate();
+            if (result !== true) {
+                debugger;
+                throw new Error(`Debug assert failed: ${result.toString()}`);
+            }
+        }
+    });
+}
+exports.debugAssert = debugAssert;
+let debugAssertsEnabled = false;
+/**
+ * Enables {@link debugAssert} validation.
+ * @remarks
+ * Throws if debugAsserts have been optimized out.
+ * @returns The previous state of debugAsserts.
+ * @internal
+ */
+function configureDebugAsserts(enabled) {
+    assert(nonProductionConditionalsIncluded(), 0xab1 /* Debug asserts cannot be configured since they have been optimized out. */);
+    const old = debugAssertsEnabled;
+    debugAssertsEnabled = enabled;
+    return old;
+}
+exports.configureDebugAsserts = configureDebugAsserts;
+/**
+ * Checks if non-production conditional code like {@link debugAssert} is included in this build.
+ * @remarks
+ * Such code can be optimized out by bundlers: this checks if that has occurred.
+ * @privateRemarks
+ * See {@link skipInProduction}.
+ * @internal
+ */
+function nonProductionConditionalsIncluded() {
+    let included = false;
+    skipInProduction(() => {
+        included = true;
+    });
+    return included;
+}
+exports.nonProductionConditionalsIncluded = nonProductionConditionalsIncluded;
+/**
+ * Run `conditional` only in debug/development (non optimized/minified) builds, but optimize it out of production builds.
+ *
+ * @param conditional - This function will only be run in some configurations so it should be pure (at least in production scenarios).
+ * It can be used to interact with debug only functionality that is also removed in production builds, or to do validation/testing/debugging that can be assumed to be sideeffect free in production where it might be removed.
+ * @remarks
+ * Great care must be taken when using this to ensure that bugs are not introduced which only occur when `conditional` is not run.
+ * One way to do this is to provide an alternative way to disable the effects of `conditional` in development builds so both configurations can be tested:
+ * {@link debugAssert} uses this pattern.
+ *
+ * @privateRemarks
+ * Since this function has no built in option for toggling it in development for testing, it is not exported and is only used as a building block for other testable options.
+ * There are some additional details about syntax and bundler support in https://github.com/javascript-compiler-hints/compiler-notations-spec/tree/main .
+ * This code uses both NO_SIDE_EFFECTS and PURE to maximize compatibility: for any bundler supporting both they are redundant.
+ */
+// Using the exact syntax from https://github.com/javascript-compiler-hints/compiler-notations-spec/blob/main/no-side-effects-notation-spec.md to maximize compatibility with tree-shaking tools.
+// eslint-disable-next-line spaced-comment
+/*#__NO_SIDE_EFFECTS__*/
+function skipInProduction(conditional) {
+    // Here __PURE__ annotation is used to indicate that is is safe to optimize out this call.
+    // This is valid since the contract for this function is that "conditional" should be side effect free if it were run in production scenarios
+    // See https://webpack.js.org/guides/tree-shaking/#mark-a-function-call-as-side-effect-free for documentation on this annotation.
+    // Using the exact syntax from https://webpack.js.org/guides/tree-shaking/#mark-a-function-call-as-side-effect-free to maximize compatibility with tree-shaking tools.
+    // eslint-disable-next-line spaced-comment
+    /*#__PURE__*/ conditional();
+}
 //# sourceMappingURL=assert.js.map

package/dist/assert.js.map

@@ -1 +1 @@
-{"version":3,"file":"assert.js","sourceRoot":"","sources":["../src/assert.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH;;;;;;;;;;;GAWG;AACH,SAAgB,MAAM,CAAC,SAAkB,EAAE,OAAwB;IAClE,IAAI,CAAC,SAAS,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CACd,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CACpF,CAAC;IACH,CAAC;AACF,CAAC;AAND,wBAMC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n/**\n * A browser friendly assert library.\n * Use this instead of the 'assert' package, which has a big impact on bundle sizes.\n * @param condition - The condition that should be true, if the condition is false an error will be thrown.\n * Only use this API when `false` indicates a logic error in the problem and thus a bug that should be fixed.\n * @param message - The message to include in the error when the condition does not hold.\n * A number should not be specified manually: use a string.\n * Before a release, policy-check should be run, which will convert any asserts still using strings to\n * use numbered error codes instead.\n * @legacy\n * @alpha\n */\nexport function assert(condition: boolean, message: string | number): asserts condition {\n\tif (!condition) {\n\t\tthrow new Error(\n\t\t\ttypeof message === \"number\" ? `0x${message.toString(16).padStart(3, \"0\")}` : message,\n\t\t);\n\t}\n}\n"]}
+{"version":3,"file":"assert.js","sourceRoot":"","sources":["../src/assert.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,SAAgB,MAAM,CAAC,SAAkB,EAAE,OAAwB;IAClE,IAAI,CAAC,SAAS,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CACd,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CACpF,CAAC;IACH,CAAC;AACF,CAAC;AAND,wBAMC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,SAAgB,WAAW,CAAC,SAA8C;IACzE,uJAAuJ;IACvJ,yJAAyJ;IACzJ,yIAAyI;IACzI,gBAAgB,CAAC,GAAG,EAAE;QACrB,IAAI,mBAAmB,EAAE,CAAC;YACzB,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;YAC3B,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;gBACrB,QAAQ,CAAC;gBACT,MAAM,IAAI,KAAK,CAAC,wBAAwB,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;YAC9D,CAAC;QACF,CAAC;IACF,CAAC,CAAC,CAAC;AACJ,CAAC;AAbD,kCAaC;AAED,IAAI,mBAAmB,GAAG,KAAK,CAAC;AAEhC;;;;;;GAMG;AACH,SAAgB,qBAAqB,CAAC,OAAgB;IACrD,MAAM,CACL,iCAAiC,EAAE,EACnC,KAAK,CAAC,4EAA4E,CAClF,CAAC;IACF,MAAM,GAAG,GAAG,mBAAmB,CAAC;IAChC,mBAAmB,GAAG,OAAO,CAAC;IAC9B,OAAO,GAAG,CAAC;AACZ,CAAC;AARD,sDAQC;AAED;;;;;;;GAOG;AACH,SAAgB,iCAAiC;IAChD,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,gBAAgB,CAAC,GAAG,EAAE;QACrB,QAAQ,GAAG,IAAI,CAAC;IACjB,CAAC,CAAC,CAAC;IACH,OAAO,QAAQ,CAAC;AACjB,CAAC;AAND,8EAMC;AAED;;;;;;;;;;;;;;GAcG;AACH,iMAAiM;AACjM,0CAA0C;AAC1C,wBAAwB;AACxB,SAAS,gBAAgB,CAAC,WAAuB;IAChD,0FAA0F;IAC1F,6IAA6I;IAC7I,iIAAiI;IAEjI,sKAAsK;IACtK,0CAA0C;IAC1C,aAAa,CAAC,WAAW,EAAE,CAAC;AAC7B,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n/**\n * Asserts the specified condition.\n *\n * @param condition - The condition that should be true, if the condition is false an error will be thrown.\n * Only use this API when `false` indicates a logic error in the problem and thus a bug that should be fixed.\n * @param message - The message to include in the error when the condition does not hold.\n * A number should not be specified manually: use a string.\n * Before a release, policy-check should be run, which will convert any asserts still using strings to\n * use numbered error codes instead.\n * @remarks\n * Use this instead of the node 'assert' package, which requires polyfills and has a big impact on bundle sizes.\n *\n * Assertions using this API will be included in all configurations: there is no option to disable or optimize them out.\n * Thus this API is suitable for detecting conditions that should terminate the application and produce a useful diagnostic message.\n * It can be used to ensure bad states are detected early and to avoid data corruption or harder to debug errors.\n *\n * In cases where the assert is very unlikely to have an impact on production code but is still useful as documentation and for debugging, consider using `debugAssert` instead\n * to optimize bundle size.\n *\n * This API is not intended for use outside of the Fluid Framework client codebase: it will most likely be made internal in the future.\n * @privateRemarks\n * This should be deprecated (as a non internal API) then moved to purely internal.\n * When done the `debugAssert` reference above should be turned into a link.\n * @legacy\n * @alpha\n */\nexport function assert(condition: boolean, message: string | number): asserts condition {\n\tif (!condition) {\n\t\tthrow new Error(\n\t\t\ttypeof message === \"number\" ? `0x${message.toString(16).padStart(3, \"0\")}` : message,\n\t\t);\n\t}\n}\n\n/**\n * Asserts that can be conditionally enabled in debug/development builds but will be optimized out of production builds.\n *\n * Disabled by default.\n *\n * If the assert must be enforced/checked in production or enabled by default, use {@link assert} instead.\n *\n * @param predicate - A pure function that should return true if the condition holds, or a string or object describing the condition that failed.\n * This function will only be run in some configurations so it should be pure, and only used to detect bugs (when debugAssert are enabled), and must not be relied on to enforce the condition is true: for that use {@link assert}.\n * @remarks\n * Optimizing the asserts out of the bundle requires a bundler like webpack which leverages `__PURE__` annotations like https://webpack.js.org/guides/tree-shaking/#mark-a-function-call-as-side-effect-free.\n *\n * Exceptions thrown by this function must never be caught in production code, as that will result in different behavior when testing and when running optimized builds.\n * The `predicate` function must be pure (have no side-effects) to ensure that the behavior of code is the same regardless of if the asserts are disabled, enabled or optimized out.\n *\n * These asserts are disabled by default, even in debug builds to ensure that by default code will be tested as production runs, with them disabled.\n * Additionally, this ensures that apps that use a bundler which does not remove `__PURE__` will not incur the runtime cost of calling the predicate.\n * These asserts can be can be enabled by calling `configureDebugAsserts(true)`: see {@link configureDebugAsserts}.\n *\n * @privateRemarks\n * This design was chosen to accomplish two main goals:\n *\n * 1. Make it easy to compile debug asserts fully out of production builds.\n * For webpack this happens by default, avoiding the need for customers to do special configuration.\n * This is important for both performance and bundle size.\n *\n * 2. Make it easy to test (both manually and automated) with and without the predicates running.\n * This ensures it is possible to benefit from the asserts when enabled, but also test with them disabled to ensure this disablement doesn't cause bugs.\n *\n * The default behavior of having debugAsserts disabled helps ensure that tests which don't know about debug asserts will still run in a way that is most similar to production.\n * @internal\n */\nexport function debugAssert(predicate: () => true | { toString(): string }): void {\n\t// This is valid since the contract for this function is that \"predicate\" should be side effect free and never return non true in production scenarios:\n\t// it returning non-true indicates a bug is present, and that the validation it does to detect the bug is only desired in specific test/debug situations.\n\t// Production scenarios, where pure code is removed, should never hit a failing predicate, and thus this code should be side effect free.\n\tskipInProduction(() => {\n\t\tif (debugAssertsEnabled) {\n\t\t\tconst result = predicate();\n\t\t\tif (result !== true) {\n\t\t\t\tdebugger;\n\t\t\t\tthrow new Error(`Debug assert failed: ${result.toString()}`);\n\t\t\t}\n\t\t}\n\t});\n}\n\nlet debugAssertsEnabled = false;\n\n/**\n * Enables {@link debugAssert} validation.\n * @remarks\n * Throws if debugAsserts have been optimized out.\n * @returns The previous state of debugAsserts.\n * @internal\n */\nexport function configureDebugAsserts(enabled: boolean): boolean {\n\tassert(\n\t\tnonProductionConditionalsIncluded(),\n\t\t0xab1 /* Debug asserts cannot be configured since they have been optimized out. */,\n\t);\n\tconst old = debugAssertsEnabled;\n\tdebugAssertsEnabled = enabled;\n\treturn old;\n}\n\n/**\n * Checks if non-production conditional code like {@link debugAssert} is included in this build.\n * @remarks\n * Such code can be optimized out by bundlers: this checks if that has occurred.\n * @privateRemarks\n * See {@link skipInProduction}.\n * @internal\n */\nexport function nonProductionConditionalsIncluded(): boolean {\n\tlet included = false;\n\tskipInProduction(() => {\n\t\tincluded = true;\n\t});\n\treturn included;\n}\n\n/**\n * Run `conditional` only in debug/development (non optimized/minified) builds, but optimize it out of production builds.\n *\n * @param conditional - This function will only be run in some configurations so it should be pure (at least in production scenarios).\n * It can be used to interact with debug only functionality that is also removed in production builds, or to do validation/testing/debugging that can be assumed to be sideeffect free in production where it might be removed.\n * @remarks\n * Great care must be taken when using this to ensure that bugs are not introduced which only occur when `conditional` is not run.\n * One way to do this is to provide an alternative way to disable the effects of `conditional` in development builds so both configurations can be tested:\n * {@link debugAssert} uses this pattern.\n *\n * @privateRemarks\n * Since this function has no built in option for toggling it in development for testing, it is not exported and is only used as a building block for other testable options.\n * There are some additional details about syntax and bundler support in https://github.com/javascript-compiler-hints/compiler-notations-spec/tree/main .\n * This code uses both NO_SIDE_EFFECTS and PURE to maximize compatibility: for any bundler supporting both they are redundant.\n */\n// Using the exact syntax from https://github.com/javascript-compiler-hints/compiler-notations-spec/blob/main/no-side-effects-notation-spec.md to maximize compatibility with tree-shaking tools.\n// eslint-disable-next-line spaced-comment\n/*#__NO_SIDE_EFFECTS__*/\nfunction skipInProduction(conditional: () => void): void {\n\t// Here __PURE__ annotation is used to indicate that is is safe to optimize out this call.\n\t// This is valid since the contract for this function is that \"conditional\" should be side effect free if it were run in production scenarios\n\t// See https://webpack.js.org/guides/tree-shaking/#mark-a-function-call-as-side-effect-free for documentation on this annotation.\n\n\t// Using the exact syntax from https://webpack.js.org/guides/tree-shaking/#mark-a-function-call-as-side-effect-free to maximize compatibility with tree-shaking tools.\n\t// eslint-disable-next-line spaced-comment\n\t/*#__PURE__*/ conditional();\n}\n"]}

package/dist/index.d.ts

@@ -2,7 +2,7 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-export { assert } from "./assert.js";
+export { assert, debugAssert, configureDebugAsserts, nonProductionConditionalsIncluded, } from "./assert.js";
 export { compareArrays } from "./compare.js";
 export { delay } from "./delay.js";
 export type { IComparer, IHeapNode } from "./heap.js";
@@ -11,6 +11,7 @@ export { Lazy, LazyPromise } from "./lazy.js";
 export type { PromiseCacheExpiry, PromiseCacheOptions } from "./promiseCache.js";
 export { PromiseCache } from "./promiseCache.js";
 export { Deferred } from "./promises.js";
+export { shallowCloneObject } from "./shallowClone.js";
 export type { IPromiseTimer, IPromiseTimerResult, ITimer } from "./timer.js";
 export { PromiseTimer, setLongTimeout, Timer } from "./timer.js";
 export { unreachableCase } from "./unreachable.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtD,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC9C,YAAY,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,YAAY,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAC7E,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACjE,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACN,MAAM,EACN,WAAW,EACX,qBAAqB,EACrB,iCAAiC,GACjC,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtD,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC9C,YAAY,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,YAAY,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAC7E,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACjE,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -4,9 +4,12 @@
  * Licensed under the MIT License.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.oob = exports.isPromiseLike = exports.isObject = exports.unreachableCase = exports.Timer = exports.setLongTimeout = exports.PromiseTimer = exports.Deferred = exports.PromiseCache = exports.LazyPromise = exports.Lazy = exports.NumberComparer = exports.Heap = exports.delay = exports.compareArrays = exports.assert = void 0;
+exports.oob = exports.isPromiseLike = exports.isObject = exports.unreachableCase = exports.Timer = exports.setLongTimeout = exports.PromiseTimer = exports.shallowCloneObject = exports.Deferred = exports.PromiseCache = exports.LazyPromise = exports.Lazy = exports.NumberComparer = exports.Heap = exports.delay = exports.compareArrays = exports.nonProductionConditionalsIncluded = exports.configureDebugAsserts = exports.debugAssert = exports.assert = void 0;
 var assert_js_1 = require("./assert.js");
 Object.defineProperty(exports, "assert", { enumerable: true, get: function () { return assert_js_1.assert; } });
+Object.defineProperty(exports, "debugAssert", { enumerable: true, get: function () { return assert_js_1.debugAssert; } });
+Object.defineProperty(exports, "configureDebugAsserts", { enumerable: true, get: function () { return assert_js_1.configureDebugAsserts; } });
+Object.defineProperty(exports, "nonProductionConditionalsIncluded", { enumerable: true, get: function () { return assert_js_1.nonProductionConditionalsIncluded; } });
 var compare_js_1 = require("./compare.js");
 Object.defineProperty(exports, "compareArrays", { enumerable: true, get: function () { return compare_js_1.compareArrays; } });
 var delay_js_1 = require("./delay.js");
@@ -21,6 +24,8 @@ var promiseCache_js_1 = require("./promiseCache.js");
 Object.defineProperty(exports, "PromiseCache", { enumerable: true, get: function () { return promiseCache_js_1.PromiseCache; } });
 var promises_js_1 = require("./promises.js");
 Object.defineProperty(exports, "Deferred", { enumerable: true, get: function () { return promises_js_1.Deferred; } });
+var shallowClone_js_1 = require("./shallowClone.js");
+Object.defineProperty(exports, "shallowCloneObject", { enumerable: true, get: function () { return shallowClone_js_1.shallowCloneObject; } });
 var timer_js_1 = require("./timer.js");
 Object.defineProperty(exports, "PromiseTimer", { enumerable: true, get: function () { return timer_js_1.PromiseTimer; } });
 Object.defineProperty(exports, "setLongTimeout", { enumerable: true, get: function () { return timer_js_1.setLongTimeout; } });

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,yCAAqC;AAA5B,mGAAA,MAAM,OAAA;AACf,2CAA6C;AAApC,2GAAA,aAAa,OAAA;AACtB,uCAAmC;AAA1B,iGAAA,KAAK,OAAA;AAEd,qCAAiD;AAAxC,+FAAA,IAAI,OAAA;AAAE,yGAAA,cAAc,OAAA;AAC7B,qCAA8C;AAArC,+FAAA,IAAI,OAAA;AAAE,sGAAA,WAAW,OAAA;AAE1B,qDAAiD;AAAxC,+GAAA,YAAY,OAAA;AACrB,6CAAyC;AAAhC,uGAAA,QAAQ,OAAA;AAEjB,uCAAiE;AAAxD,wGAAA,YAAY,OAAA;AAAE,0GAAA,cAAc,OAAA;AAAE,iGAAA,KAAK,OAAA;AAC5C,mDAAmD;AAA1C,iHAAA,eAAe,OAAA;AACxB,mDAA2D;AAAlD,0GAAA,QAAQ,OAAA;AAAE,+GAAA,aAAa,OAAA;AAChC,mCAA+B;AAAtB,6FAAA,GAAG,OAAA","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nexport { assert } from \"./assert.js\";\nexport { compareArrays } from \"./compare.js\";\nexport { delay } from \"./delay.js\";\nexport type { IComparer, IHeapNode } from \"./heap.js\";\nexport { Heap, NumberComparer } from \"./heap.js\";\nexport { Lazy, LazyPromise } from \"./lazy.js\";\nexport type { PromiseCacheExpiry, PromiseCacheOptions } from \"./promiseCache.js\";\nexport { PromiseCache } from \"./promiseCache.js\";\nexport { Deferred } from \"./promises.js\";\nexport type { IPromiseTimer, IPromiseTimerResult, ITimer } from \"./timer.js\";\nexport { PromiseTimer, setLongTimeout, Timer } from \"./timer.js\";\nexport { unreachableCase } from \"./unreachable.js\";\nexport { isObject, isPromiseLike } from \"./typesGuards.js\";\nexport { oob } from \"./oob.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,yCAKqB;AAJpB,mGAAA,MAAM,OAAA;AACN,wGAAA,WAAW,OAAA;AACX,kHAAA,qBAAqB,OAAA;AACrB,8HAAA,iCAAiC,OAAA;AAElC,2CAA6C;AAApC,2GAAA,aAAa,OAAA;AACtB,uCAAmC;AAA1B,iGAAA,KAAK,OAAA;AAEd,qCAAiD;AAAxC,+FAAA,IAAI,OAAA;AAAE,yGAAA,cAAc,OAAA;AAC7B,qCAA8C;AAArC,+FAAA,IAAI,OAAA;AAAE,sGAAA,WAAW,OAAA;AAE1B,qDAAiD;AAAxC,+GAAA,YAAY,OAAA;AACrB,6CAAyC;AAAhC,uGAAA,QAAQ,OAAA;AACjB,qDAAuD;AAA9C,qHAAA,kBAAkB,OAAA;AAE3B,uCAAiE;AAAxD,wGAAA,YAAY,OAAA;AAAE,0GAAA,cAAc,OAAA;AAAE,iGAAA,KAAK,OAAA;AAC5C,mDAAmD;AAA1C,iHAAA,eAAe,OAAA;AACxB,mDAA2D;AAAlD,0GAAA,QAAQ,OAAA;AAAE,+GAAA,aAAa,OAAA;AAChC,mCAA+B;AAAtB,6FAAA,GAAG,OAAA","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nexport {\n\tassert,\n\tdebugAssert,\n\tconfigureDebugAsserts,\n\tnonProductionConditionalsIncluded,\n} from \"./assert.js\";\nexport { compareArrays } from \"./compare.js\";\nexport { delay } from \"./delay.js\";\nexport type { IComparer, IHeapNode } from \"./heap.js\";\nexport { Heap, NumberComparer } from \"./heap.js\";\nexport { Lazy, LazyPromise } from \"./lazy.js\";\nexport type { PromiseCacheExpiry, PromiseCacheOptions } from \"./promiseCache.js\";\nexport { PromiseCache } from \"./promiseCache.js\";\nexport { Deferred } from \"./promises.js\";\nexport { shallowCloneObject } from \"./shallowClone.js\";\nexport type { IPromiseTimer, IPromiseTimerResult, ITimer } from \"./timer.js\";\nexport { PromiseTimer, setLongTimeout, Timer } from \"./timer.js\";\nexport { unreachableCase } from \"./unreachable.js\";\nexport { isObject, isPromiseLike } from \"./typesGuards.js\";\nexport { oob } from \"./oob.js\";\n"]}

package/dist/shallowClone.d.ts

@@ -0,0 +1,13 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+/**
+ * Shallow clone an object.
+ *
+ * @param value - The object to clone
+ * @returns A shallow clone of the input value
+ * @internal
+ */
+export declare function shallowCloneObject<T extends object>(value: T): T;
+//# sourceMappingURL=shallowClone.d.ts.map

package/dist/shallowClone.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shallowClone.d.ts","sourceRoot":"","sources":["../src/shallowClone.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAKhE"}

package/dist/shallowClone.js

@@ -0,0 +1,22 @@
+"use strict";
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shallowCloneObject = void 0;
+/**
+ * Shallow clone an object.
+ *
+ * @param value - The object to clone
+ * @returns A shallow clone of the input value
+ * @internal
+ */
+function shallowCloneObject(value) {
+    if (Array.isArray(value)) {
+        return [...value];
+    }
+    return { ...value };
+}
+exports.shallowCloneObject = shallowCloneObject;
+//# sourceMappingURL=shallowClone.js.map

package/dist/shallowClone.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shallowClone.js","sourceRoot":"","sources":["../src/shallowClone.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH;;;;;;GAMG;AACH,SAAgB,kBAAkB,CAAmB,KAAQ;IAC5D,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,CAAC,GAAG,KAAK,CAAM,CAAC;IACxB,CAAC;IACD,OAAO,EAAE,GAAG,KAAK,EAAE,CAAC;AACrB,CAAC;AALD,gDAKC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n/**\n * Shallow clone an object.\n *\n * @param value - The object to clone\n * @returns A shallow clone of the input value\n * @internal\n */\nexport function shallowCloneObject<T extends object>(value: T): T {\n\tif (Array.isArray(value)) {\n\t\treturn [...value] as T;\n\t}\n\treturn { ...value };\n}\n"]}

package/lib/assert.d.ts

@@ -3,16 +3,82 @@
  * Licensed under the MIT License.
  */
 /**
- * A browser friendly assert library.
- * Use this instead of the 'assert' package, which has a big impact on bundle sizes.
+ * Asserts the specified condition.
+ *
  * @param condition - The condition that should be true, if the condition is false an error will be thrown.
  * Only use this API when `false` indicates a logic error in the problem and thus a bug that should be fixed.
  * @param message - The message to include in the error when the condition does not hold.
  * A number should not be specified manually: use a string.
  * Before a release, policy-check should be run, which will convert any asserts still using strings to
  * use numbered error codes instead.
+ * @remarks
+ * Use this instead of the node 'assert' package, which requires polyfills and has a big impact on bundle sizes.
+ *
+ * Assertions using this API will be included in all configurations: there is no option to disable or optimize them out.
+ * Thus this API is suitable for detecting conditions that should terminate the application and produce a useful diagnostic message.
+ * It can be used to ensure bad states are detected early and to avoid data corruption or harder to debug errors.
+ *
+ * In cases where the assert is very unlikely to have an impact on production code but is still useful as documentation and for debugging, consider using `debugAssert` instead
+ * to optimize bundle size.
+ *
+ * This API is not intended for use outside of the Fluid Framework client codebase: it will most likely be made internal in the future.
+ * @privateRemarks
+ * This should be deprecated (as a non internal API) then moved to purely internal.
+ * When done the `debugAssert` reference above should be turned into a link.
  * @legacy
  * @alpha
  */
 export declare function assert(condition: boolean, message: string | number): asserts condition;
+/**
+ * Asserts that can be conditionally enabled in debug/development builds but will be optimized out of production builds.
+ *
+ * Disabled by default.
+ *
+ * If the assert must be enforced/checked in production or enabled by default, use {@link assert} instead.
+ *
+ * @param predicate - A pure function that should return true if the condition holds, or a string or object describing the condition that failed.
+ * This function will only be run in some configurations so it should be pure, and only used to detect bugs (when debugAssert are enabled), and must not be relied on to enforce the condition is true: for that use {@link assert}.
+ * @remarks
+ * Optimizing the asserts out of the bundle requires a bundler like webpack which leverages `__PURE__` annotations like https://webpack.js.org/guides/tree-shaking/#mark-a-function-call-as-side-effect-free.
+ *
+ * Exceptions thrown by this function must never be caught in production code, as that will result in different behavior when testing and when running optimized builds.
+ * The `predicate` function must be pure (have no side-effects) to ensure that the behavior of code is the same regardless of if the asserts are disabled, enabled or optimized out.
+ *
+ * These asserts are disabled by default, even in debug builds to ensure that by default code will be tested as production runs, with them disabled.
+ * Additionally, this ensures that apps that use a bundler which does not remove `__PURE__` will not incur the runtime cost of calling the predicate.
+ * These asserts can be can be enabled by calling `configureDebugAsserts(true)`: see {@link configureDebugAsserts}.
+ *
+ * @privateRemarks
+ * This design was chosen to accomplish two main goals:
+ *
+ * 1. Make it easy to compile debug asserts fully out of production builds.
+ * For webpack this happens by default, avoiding the need for customers to do special configuration.
+ * This is important for both performance and bundle size.
+ *
+ * 2. Make it easy to test (both manually and automated) with and without the predicates running.
+ * This ensures it is possible to benefit from the asserts when enabled, but also test with them disabled to ensure this disablement doesn't cause bugs.
+ *
+ * The default behavior of having debugAsserts disabled helps ensure that tests which don't know about debug asserts will still run in a way that is most similar to production.
+ * @internal
+ */
+export declare function debugAssert(predicate: () => true | {
+    toString(): string;
+}): void;
+/**
+ * Enables {@link debugAssert} validation.
+ * @remarks
+ * Throws if debugAsserts have been optimized out.
+ * @returns The previous state of debugAsserts.
+ * @internal
+ */
+export declare function configureDebugAsserts(enabled: boolean): boolean;
+/**
+ * Checks if non-production conditional code like {@link debugAssert} is included in this build.
+ * @remarks
+ * Such code can be optimized out by bundlers: this checks if that has occurred.
+ * @privateRemarks
+ * See {@link skipInProduction}.
+ * @internal
+ */
+export declare function nonProductionConditionalsIncluded(): boolean;
 //# sourceMappingURL=assert.d.ts.map

package/lib/assert.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"assert.d.ts","sourceRoot":"","sources":["../src/assert.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;GAWG;AACH,wBAAgB,MAAM,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,SAAS,CAMtF"}
+{"version":3,"file":"assert.d.ts","sourceRoot":"","sources":["../src/assert.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,MAAM,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,SAAS,CAMtF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,IAAI,GAAG;IAAE,QAAQ,IAAI,MAAM,CAAA;CAAE,GAAG,IAAI,CAahF;AAID;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAQ/D;AAED;;;;;;;GAOG;AACH,wBAAgB,iCAAiC,IAAI,OAAO,CAM3D"}

package/lib/assert.js

@@ -3,14 +3,28 @@
  * Licensed under the MIT License.
  */
 /**
- * A browser friendly assert library.
- * Use this instead of the 'assert' package, which has a big impact on bundle sizes.
+ * Asserts the specified condition.
+ *
  * @param condition - The condition that should be true, if the condition is false an error will be thrown.
  * Only use this API when `false` indicates a logic error in the problem and thus a bug that should be fixed.
  * @param message - The message to include in the error when the condition does not hold.
  * A number should not be specified manually: use a string.
  * Before a release, policy-check should be run, which will convert any asserts still using strings to
  * use numbered error codes instead.
+ * @remarks
+ * Use this instead of the node 'assert' package, which requires polyfills and has a big impact on bundle sizes.
+ *
+ * Assertions using this API will be included in all configurations: there is no option to disable or optimize them out.
+ * Thus this API is suitable for detecting conditions that should terminate the application and produce a useful diagnostic message.
+ * It can be used to ensure bad states are detected early and to avoid data corruption or harder to debug errors.
+ *
+ * In cases where the assert is very unlikely to have an impact on production code but is still useful as documentation and for debugging, consider using `debugAssert` instead
+ * to optimize bundle size.
+ *
+ * This API is not intended for use outside of the Fluid Framework client codebase: it will most likely be made internal in the future.
+ * @privateRemarks
+ * This should be deprecated (as a non internal API) then moved to purely internal.
+ * When done the `debugAssert` reference above should be turned into a link.
  * @legacy
  * @alpha
  */
@@ -19,4 +33,105 @@ export function assert(condition, message) {
         throw new Error(typeof message === "number" ? `0x${message.toString(16).padStart(3, "0")}` : message);
     }
 }
+/**
+ * Asserts that can be conditionally enabled in debug/development builds but will be optimized out of production builds.
+ *
+ * Disabled by default.
+ *
+ * If the assert must be enforced/checked in production or enabled by default, use {@link assert} instead.
+ *
+ * @param predicate - A pure function that should return true if the condition holds, or a string or object describing the condition that failed.
+ * This function will only be run in some configurations so it should be pure, and only used to detect bugs (when debugAssert are enabled), and must not be relied on to enforce the condition is true: for that use {@link assert}.
+ * @remarks
+ * Optimizing the asserts out of the bundle requires a bundler like webpack which leverages `__PURE__` annotations like https://webpack.js.org/guides/tree-shaking/#mark-a-function-call-as-side-effect-free.
+ *
+ * Exceptions thrown by this function must never be caught in production code, as that will result in different behavior when testing and when running optimized builds.
+ * The `predicate` function must be pure (have no side-effects) to ensure that the behavior of code is the same regardless of if the asserts are disabled, enabled or optimized out.
+ *
+ * These asserts are disabled by default, even in debug builds to ensure that by default code will be tested as production runs, with them disabled.
+ * Additionally, this ensures that apps that use a bundler which does not remove `__PURE__` will not incur the runtime cost of calling the predicate.
+ * These asserts can be can be enabled by calling `configureDebugAsserts(true)`: see {@link configureDebugAsserts}.
+ *
+ * @privateRemarks
+ * This design was chosen to accomplish two main goals:
+ *
+ * 1. Make it easy to compile debug asserts fully out of production builds.
+ * For webpack this happens by default, avoiding the need for customers to do special configuration.
+ * This is important for both performance and bundle size.
+ *
+ * 2. Make it easy to test (both manually and automated) with and without the predicates running.
+ * This ensures it is possible to benefit from the asserts when enabled, but also test with them disabled to ensure this disablement doesn't cause bugs.
+ *
+ * The default behavior of having debugAsserts disabled helps ensure that tests which don't know about debug asserts will still run in a way that is most similar to production.
+ * @internal
+ */
+export function debugAssert(predicate) {
+    // This is valid since the contract for this function is that "predicate" should be side effect free and never return non true in production scenarios:
+    // it returning non-true indicates a bug is present, and that the validation it does to detect the bug is only desired in specific test/debug situations.
+    // Production scenarios, where pure code is removed, should never hit a failing predicate, and thus this code should be side effect free.
+    skipInProduction(() => {
+        if (debugAssertsEnabled) {
+            const result = predicate();
+            if (result !== true) {
+                debugger;
+                throw new Error(`Debug assert failed: ${result.toString()}`);
+            }
+        }
+    });
+}
+let debugAssertsEnabled = false;
+/**
+ * Enables {@link debugAssert} validation.
+ * @remarks
+ * Throws if debugAsserts have been optimized out.
+ * @returns The previous state of debugAsserts.
+ * @internal
+ */
+export function configureDebugAsserts(enabled) {
+    assert(nonProductionConditionalsIncluded(), 0xab1 /* Debug asserts cannot be configured since they have been optimized out. */);
+    const old = debugAssertsEnabled;
+    debugAssertsEnabled = enabled;
+    return old;
+}
+/**
+ * Checks if non-production conditional code like {@link debugAssert} is included in this build.
+ * @remarks
+ * Such code can be optimized out by bundlers: this checks if that has occurred.
+ * @privateRemarks
+ * See {@link skipInProduction}.
+ * @internal
+ */
+export function nonProductionConditionalsIncluded() {
+    let included = false;
+    skipInProduction(() => {
+        included = true;
+    });
+    return included;
+}
+/**
+ * Run `conditional` only in debug/development (non optimized/minified) builds, but optimize it out of production builds.
+ *
+ * @param conditional - This function will only be run in some configurations so it should be pure (at least in production scenarios).
+ * It can be used to interact with debug only functionality that is also removed in production builds, or to do validation/testing/debugging that can be assumed to be sideeffect free in production where it might be removed.
+ * @remarks
+ * Great care must be taken when using this to ensure that bugs are not introduced which only occur when `conditional` is not run.
+ * One way to do this is to provide an alternative way to disable the effects of `conditional` in development builds so both configurations can be tested:
+ * {@link debugAssert} uses this pattern.
+ *
+ * @privateRemarks
+ * Since this function has no built in option for toggling it in development for testing, it is not exported and is only used as a building block for other testable options.
+ * There are some additional details about syntax and bundler support in https://github.com/javascript-compiler-hints/compiler-notations-spec/tree/main .
+ * This code uses both NO_SIDE_EFFECTS and PURE to maximize compatibility: for any bundler supporting both they are redundant.
+ */
+// Using the exact syntax from https://github.com/javascript-compiler-hints/compiler-notations-spec/blob/main/no-side-effects-notation-spec.md to maximize compatibility with tree-shaking tools.
+// eslint-disable-next-line spaced-comment
+/*#__NO_SIDE_EFFECTS__*/
+function skipInProduction(conditional) {
+    // Here __PURE__ annotation is used to indicate that is is safe to optimize out this call.
+    // This is valid since the contract for this function is that "conditional" should be side effect free if it were run in production scenarios
+    // See https://webpack.js.org/guides/tree-shaking/#mark-a-function-call-as-side-effect-free for documentation on this annotation.
+    // Using the exact syntax from https://webpack.js.org/guides/tree-shaking/#mark-a-function-call-as-side-effect-free to maximize compatibility with tree-shaking tools.
+    // eslint-disable-next-line spaced-comment
+    /*#__PURE__*/ conditional();
+}
 //# sourceMappingURL=assert.js.map

package/lib/assert.js.map

@@ -1 +1 @@
-{"version":3,"file":"assert.js","sourceRoot":"","sources":["../src/assert.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,MAAM,CAAC,SAAkB,EAAE,OAAwB;IAClE,IAAI,CAAC,SAAS,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CACd,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CACpF,CAAC;IACH,CAAC;AACF,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n/**\n * A browser friendly assert library.\n * Use this instead of the 'assert' package, which has a big impact on bundle sizes.\n * @param condition - The condition that should be true, if the condition is false an error will be thrown.\n * Only use this API when `false` indicates a logic error in the problem and thus a bug that should be fixed.\n * @param message - The message to include in the error when the condition does not hold.\n * A number should not be specified manually: use a string.\n * Before a release, policy-check should be run, which will convert any asserts still using strings to\n * use numbered error codes instead.\n * @legacy\n * @alpha\n */\nexport function assert(condition: boolean, message: string | number): asserts condition {\n\tif (!condition) {\n\t\tthrow new Error(\n\t\t\ttypeof message === \"number\" ? `0x${message.toString(16).padStart(3, \"0\")}` : message,\n\t\t);\n\t}\n}\n"]}
+{"version":3,"file":"assert.js","sourceRoot":"","sources":["../src/assert.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,MAAM,CAAC,SAAkB,EAAE,OAAwB;IAClE,IAAI,CAAC,SAAS,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CACd,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CACpF,CAAC;IACH,CAAC;AACF,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,WAAW,CAAC,SAA8C;IACzE,uJAAuJ;IACvJ,yJAAyJ;IACzJ,yIAAyI;IACzI,gBAAgB,CAAC,GAAG,EAAE;QACrB,IAAI,mBAAmB,EAAE,CAAC;YACzB,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;YAC3B,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;gBACrB,QAAQ,CAAC;gBACT,MAAM,IAAI,KAAK,CAAC,wBAAwB,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;YAC9D,CAAC;QACF,CAAC;IACF,CAAC,CAAC,CAAC;AACJ,CAAC;AAED,IAAI,mBAAmB,GAAG,KAAK,CAAC;AAEhC;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAgB;IACrD,MAAM,CACL,iCAAiC,EAAE,EACnC,KAAK,CAAC,4EAA4E,CAClF,CAAC;IACF,MAAM,GAAG,GAAG,mBAAmB,CAAC;IAChC,mBAAmB,GAAG,OAAO,CAAC;IAC9B,OAAO,GAAG,CAAC;AACZ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iCAAiC;IAChD,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,gBAAgB,CAAC,GAAG,EAAE;QACrB,QAAQ,GAAG,IAAI,CAAC;IACjB,CAAC,CAAC,CAAC;IACH,OAAO,QAAQ,CAAC;AACjB,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,iMAAiM;AACjM,0CAA0C;AAC1C,wBAAwB;AACxB,SAAS,gBAAgB,CAAC,WAAuB;IAChD,0FAA0F;IAC1F,6IAA6I;IAC7I,iIAAiI;IAEjI,sKAAsK;IACtK,0CAA0C;IAC1C,aAAa,CAAC,WAAW,EAAE,CAAC;AAC7B,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n/**\n * Asserts the specified condition.\n *\n * @param condition - The condition that should be true, if the condition is false an error will be thrown.\n * Only use this API when `false` indicates a logic error in the problem and thus a bug that should be fixed.\n * @param message - The message to include in the error when the condition does not hold.\n * A number should not be specified manually: use a string.\n * Before a release, policy-check should be run, which will convert any asserts still using strings to\n * use numbered error codes instead.\n * @remarks\n * Use this instead of the node 'assert' package, which requires polyfills and has a big impact on bundle sizes.\n *\n * Assertions using this API will be included in all configurations: there is no option to disable or optimize them out.\n * Thus this API is suitable for detecting conditions that should terminate the application and produce a useful diagnostic message.\n * It can be used to ensure bad states are detected early and to avoid data corruption or harder to debug errors.\n *\n * In cases where the assert is very unlikely to have an impact on production code but is still useful as documentation and for debugging, consider using `debugAssert` instead\n * to optimize bundle size.\n *\n * This API is not intended for use outside of the Fluid Framework client codebase: it will most likely be made internal in the future.\n * @privateRemarks\n * This should be deprecated (as a non internal API) then moved to purely internal.\n * When done the `debugAssert` reference above should be turned into a link.\n * @legacy\n * @alpha\n */\nexport function assert(condition: boolean, message: string | number): asserts condition {\n\tif (!condition) {\n\t\tthrow new Error(\n\t\t\ttypeof message === \"number\" ? `0x${message.toString(16).padStart(3, \"0\")}` : message,\n\t\t);\n\t}\n}\n\n/**\n * Asserts that can be conditionally enabled in debug/development builds but will be optimized out of production builds.\n *\n * Disabled by default.\n *\n * If the assert must be enforced/checked in production or enabled by default, use {@link assert} instead.\n *\n * @param predicate - A pure function that should return true if the condition holds, or a string or object describing the condition that failed.\n * This function will only be run in some configurations so it should be pure, and only used to detect bugs (when debugAssert are enabled), and must not be relied on to enforce the condition is true: for that use {@link assert}.\n * @remarks\n * Optimizing the asserts out of the bundle requires a bundler like webpack which leverages `__PURE__` annotations like https://webpack.js.org/guides/tree-shaking/#mark-a-function-call-as-side-effect-free.\n *\n * Exceptions thrown by this function must never be caught in production code, as that will result in different behavior when testing and when running optimized builds.\n * The `predicate` function must be pure (have no side-effects) to ensure that the behavior of code is the same regardless of if the asserts are disabled, enabled or optimized out.\n *\n * These asserts are disabled by default, even in debug builds to ensure that by default code will be tested as production runs, with them disabled.\n * Additionally, this ensures that apps that use a bundler which does not remove `__PURE__` will not incur the runtime cost of calling the predicate.\n * These asserts can be can be enabled by calling `configureDebugAsserts(true)`: see {@link configureDebugAsserts}.\n *\n * @privateRemarks\n * This design was chosen to accomplish two main goals:\n *\n * 1. Make it easy to compile debug asserts fully out of production builds.\n * For webpack this happens by default, avoiding the need for customers to do special configuration.\n * This is important for both performance and bundle size.\n *\n * 2. Make it easy to test (both manually and automated) with and without the predicates running.\n * This ensures it is possible to benefit from the asserts when enabled, but also test with them disabled to ensure this disablement doesn't cause bugs.\n *\n * The default behavior of having debugAsserts disabled helps ensure that tests which don't know about debug asserts will still run in a way that is most similar to production.\n * @internal\n */\nexport function debugAssert(predicate: () => true | { toString(): string }): void {\n\t// This is valid since the contract for this function is that \"predicate\" should be side effect free and never return non true in production scenarios:\n\t// it returning non-true indicates a bug is present, and that the validation it does to detect the bug is only desired in specific test/debug situations.\n\t// Production scenarios, where pure code is removed, should never hit a failing predicate, and thus this code should be side effect free.\n\tskipInProduction(() => {\n\t\tif (debugAssertsEnabled) {\n\t\t\tconst result = predicate();\n\t\t\tif (result !== true) {\n\t\t\t\tdebugger;\n\t\t\t\tthrow new Error(`Debug assert failed: ${result.toString()}`);\n\t\t\t}\n\t\t}\n\t});\n}\n\nlet debugAssertsEnabled = false;\n\n/**\n * Enables {@link debugAssert} validation.\n * @remarks\n * Throws if debugAsserts have been optimized out.\n * @returns The previous state of debugAsserts.\n * @internal\n */\nexport function configureDebugAsserts(enabled: boolean): boolean {\n\tassert(\n\t\tnonProductionConditionalsIncluded(),\n\t\t0xab1 /* Debug asserts cannot be configured since they have been optimized out. */,\n\t);\n\tconst old = debugAssertsEnabled;\n\tdebugAssertsEnabled = enabled;\n\treturn old;\n}\n\n/**\n * Checks if non-production conditional code like {@link debugAssert} is included in this build.\n * @remarks\n * Such code can be optimized out by bundlers: this checks if that has occurred.\n * @privateRemarks\n * See {@link skipInProduction}.\n * @internal\n */\nexport function nonProductionConditionalsIncluded(): boolean {\n\tlet included = false;\n\tskipInProduction(() => {\n\t\tincluded = true;\n\t});\n\treturn included;\n}\n\n/**\n * Run `conditional` only in debug/development (non optimized/minified) builds, but optimize it out of production builds.\n *\n * @param conditional - This function will only be run in some configurations so it should be pure (at least in production scenarios).\n * It can be used to interact with debug only functionality that is also removed in production builds, or to do validation/testing/debugging that can be assumed to be sideeffect free in production where it might be removed.\n * @remarks\n * Great care must be taken when using this to ensure that bugs are not introduced which only occur when `conditional` is not run.\n * One way to do this is to provide an alternative way to disable the effects of `conditional` in development builds so both configurations can be tested:\n * {@link debugAssert} uses this pattern.\n *\n * @privateRemarks\n * Since this function has no built in option for toggling it in development for testing, it is not exported and is only used as a building block for other testable options.\n * There are some additional details about syntax and bundler support in https://github.com/javascript-compiler-hints/compiler-notations-spec/tree/main .\n * This code uses both NO_SIDE_EFFECTS and PURE to maximize compatibility: for any bundler supporting both they are redundant.\n */\n// Using the exact syntax from https://github.com/javascript-compiler-hints/compiler-notations-spec/blob/main/no-side-effects-notation-spec.md to maximize compatibility with tree-shaking tools.\n// eslint-disable-next-line spaced-comment\n/*#__NO_SIDE_EFFECTS__*/\nfunction skipInProduction(conditional: () => void): void {\n\t// Here __PURE__ annotation is used to indicate that is is safe to optimize out this call.\n\t// This is valid since the contract for this function is that \"conditional\" should be side effect free if it were run in production scenarios\n\t// See https://webpack.js.org/guides/tree-shaking/#mark-a-function-call-as-side-effect-free for documentation on this annotation.\n\n\t// Using the exact syntax from https://webpack.js.org/guides/tree-shaking/#mark-a-function-call-as-side-effect-free to maximize compatibility with tree-shaking tools.\n\t// eslint-disable-next-line spaced-comment\n\t/*#__PURE__*/ conditional();\n}\n"]}

package/lib/index.d.ts

@@ -2,7 +2,7 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-export { assert } from "./assert.js";
+export { assert, debugAssert, configureDebugAsserts, nonProductionConditionalsIncluded, } from "./assert.js";
 export { compareArrays } from "./compare.js";
 export { delay } from "./delay.js";
 export type { IComparer, IHeapNode } from "./heap.js";
@@ -11,6 +11,7 @@ export { Lazy, LazyPromise } from "./lazy.js";
 export type { PromiseCacheExpiry, PromiseCacheOptions } from "./promiseCache.js";
 export { PromiseCache } from "./promiseCache.js";
 export { Deferred } from "./promises.js";
+export { shallowCloneObject } from "./shallowClone.js";
 export type { IPromiseTimer, IPromiseTimerResult, ITimer } from "./timer.js";
 export { PromiseTimer, setLongTimeout, Timer } from "./timer.js";
 export { unreachableCase } from "./unreachable.js";

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtD,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC9C,YAAY,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,YAAY,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAC7E,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACjE,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACN,MAAM,EACN,WAAW,EACX,qBAAqB,EACrB,iCAAiC,GACjC,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtD,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC9C,YAAY,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,YAAY,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAC7E,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACjE,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC"}

package/lib/index.js

@@ -2,13 +2,14 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-export { assert } from "./assert.js";
+export { assert, debugAssert, configureDebugAsserts, nonProductionConditionalsIncluded, } from "./assert.js";
 export { compareArrays } from "./compare.js";
 export { delay } from "./delay.js";
 export { Heap, NumberComparer } from "./heap.js";
 export { Lazy, LazyPromise } from "./lazy.js";
 export { PromiseCache } from "./promiseCache.js";
 export { Deferred } from "./promises.js";
+export { shallowCloneObject } from "./shallowClone.js";
 export { PromiseTimer, setLongTimeout, Timer } from "./timer.js";
 export { unreachableCase } from "./unreachable.js";
 export { isObject, isPromiseLike } from "./typesGuards.js";

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE9C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACjE,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nexport { assert } from \"./assert.js\";\nexport { compareArrays } from \"./compare.js\";\nexport { delay } from \"./delay.js\";\nexport type { IComparer, IHeapNode } from \"./heap.js\";\nexport { Heap, NumberComparer } from \"./heap.js\";\nexport { Lazy, LazyPromise } from \"./lazy.js\";\nexport type { PromiseCacheExpiry, PromiseCacheOptions } from \"./promiseCache.js\";\nexport { PromiseCache } from \"./promiseCache.js\";\nexport { Deferred } from \"./promises.js\";\nexport type { IPromiseTimer, IPromiseTimerResult, ITimer } from \"./timer.js\";\nexport { PromiseTimer, setLongTimeout, Timer } from \"./timer.js\";\nexport { unreachableCase } from \"./unreachable.js\";\nexport { isObject, isPromiseLike } from \"./typesGuards.js\";\nexport { oob } from \"./oob.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACN,MAAM,EACN,WAAW,EACX,qBAAqB,EACrB,iCAAiC,GACjC,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE9C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEvD,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACjE,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nexport {\n\tassert,\n\tdebugAssert,\n\tconfigureDebugAsserts,\n\tnonProductionConditionalsIncluded,\n} from \"./assert.js\";\nexport { compareArrays } from \"./compare.js\";\nexport { delay } from \"./delay.js\";\nexport type { IComparer, IHeapNode } from \"./heap.js\";\nexport { Heap, NumberComparer } from \"./heap.js\";\nexport { Lazy, LazyPromise } from \"./lazy.js\";\nexport type { PromiseCacheExpiry, PromiseCacheOptions } from \"./promiseCache.js\";\nexport { PromiseCache } from \"./promiseCache.js\";\nexport { Deferred } from \"./promises.js\";\nexport { shallowCloneObject } from \"./shallowClone.js\";\nexport type { IPromiseTimer, IPromiseTimerResult, ITimer } from \"./timer.js\";\nexport { PromiseTimer, setLongTimeout, Timer } from \"./timer.js\";\nexport { unreachableCase } from \"./unreachable.js\";\nexport { isObject, isPromiseLike } from \"./typesGuards.js\";\nexport { oob } from \"./oob.js\";\n"]}

package/lib/shallowClone.d.ts

@@ -0,0 +1,13 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+/**
+ * Shallow clone an object.
+ *
+ * @param value - The object to clone
+ * @returns A shallow clone of the input value
+ * @internal
+ */
+export declare function shallowCloneObject<T extends object>(value: T): T;
+//# sourceMappingURL=shallowClone.d.ts.map

package/lib/shallowClone.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shallowClone.d.ts","sourceRoot":"","sources":["../src/shallowClone.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAKhE"}

package/lib/shallowClone.js

@@ -0,0 +1,18 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+/**
+ * Shallow clone an object.
+ *
+ * @param value - The object to clone
+ * @returns A shallow clone of the input value
+ * @internal
+ */
+export function shallowCloneObject(value) {
+    if (Array.isArray(value)) {
+        return [...value];
+    }
+    return { ...value };
+}
+//# sourceMappingURL=shallowClone.js.map

package/lib/shallowClone.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shallowClone.js","sourceRoot":"","sources":["../src/shallowClone.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAmB,KAAQ;IAC5D,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,CAAC,GAAG,KAAK,CAAM,CAAC;IACxB,CAAC;IACD,OAAO,EAAE,GAAG,KAAK,EAAE,CAAC;AACrB,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n/**\n * Shallow clone an object.\n *\n * @param value - The object to clone\n * @returns A shallow clone of the input value\n * @internal\n */\nexport function shallowCloneObject<T extends object>(value: T): T {\n\tif (Array.isArray(value)) {\n\t\treturn [...value] as T;\n\t}\n\treturn { ...value };\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/core-utils",
-  "version": "2.20.0",
+  "version": "2.21.0",
   "description": "Not intended for use outside the Fluid client repo.",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -69,13 +69,13 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.17.1",
     "@biomejs/biome": "~1.9.3",
-    "@fluid-internal/mocha-test-setup": "~2.20.0",
+    "@fluid-internal/mocha-test-setup": "~2.21.0",
     "@fluid-tools/benchmark": "^0.50.0",
     "@fluid-tools/build-cli": "^0.51.0",
     "@fluidframework/build-common": "^2.0.3",
     "@fluidframework/build-tools": "^0.51.0",
-    "@fluidframework/core-utils-previous": "npm:@fluidframework/core-utils@2.13.0",
-    "@fluidframework/eslint-config-fluid": "^5.6.0",
+    "@fluidframework/core-utils-previous": "npm:@fluidframework/core-utils@2.20.0",
+    "@fluidframework/eslint-config-fluid": "^5.7.3",
     "@microsoft/api-extractor": "7.47.8",
     "@types/mocha": "^10.0.10",
     "@types/node": "^18.19.0",
@@ -129,7 +129,7 @@
     "ci:build:api-reports:current": "api-extractor run --config api-extractor/api-extractor.current.json",
     "ci:build:api-reports:legacy": "api-extractor run --config api-extractor/api-extractor.legacy.json",
     "ci:build:docs": "api-extractor run",
-    "clean": "rimraf --glob dist lib \"*.d.ts\" \"**/*.tsbuildinfo\" \"**/*.build.log\" _api-extractor-temp nyc",
+    "clean": "rimraf --glob dist lib {alpha,beta,internal,legacy}.d.ts \"**/*.tsbuildinfo\" \"**/*.build.log\" _api-extractor-temp nyc",
     "eslint": "eslint --format stylish src",
     "eslint:fix": "eslint --format stylish src --fix --fix-type problem,suggestion,layout",
     "format": "npm run format:biome",

package/src/assert.ts

@@ -4,14 +4,28 @@
  */
 
 /**
- * A browser friendly assert library.
- * Use this instead of the 'assert' package, which has a big impact on bundle sizes.
+ * Asserts the specified condition.
+ *
  * @param condition - The condition that should be true, if the condition is false an error will be thrown.
  * Only use this API when `false` indicates a logic error in the problem and thus a bug that should be fixed.
  * @param message - The message to include in the error when the condition does not hold.
  * A number should not be specified manually: use a string.
  * Before a release, policy-check should be run, which will convert any asserts still using strings to
  * use numbered error codes instead.
+ * @remarks
+ * Use this instead of the node 'assert' package, which requires polyfills and has a big impact on bundle sizes.
+ *
+ * Assertions using this API will be included in all configurations: there is no option to disable or optimize them out.
+ * Thus this API is suitable for detecting conditions that should terminate the application and produce a useful diagnostic message.
+ * It can be used to ensure bad states are detected early and to avoid data corruption or harder to debug errors.
+ *
+ * In cases where the assert is very unlikely to have an impact on production code but is still useful as documentation and for debugging, consider using `debugAssert` instead
+ * to optimize bundle size.
+ *
+ * This API is not intended for use outside of the Fluid Framework client codebase: it will most likely be made internal in the future.
+ * @privateRemarks
+ * This should be deprecated (as a non internal API) then moved to purely internal.
+ * When done the `debugAssert` reference above should be turned into a link.
  * @legacy
  * @alpha
  */
@@ -22,3 +36,113 @@ export function assert(condition: boolean, message: string | number): asserts co
 		);
 	}
 }
+
+/**
+ * Asserts that can be conditionally enabled in debug/development builds but will be optimized out of production builds.
+ *
+ * Disabled by default.
+ *
+ * If the assert must be enforced/checked in production or enabled by default, use {@link assert} instead.
+ *
+ * @param predicate - A pure function that should return true if the condition holds, or a string or object describing the condition that failed.
+ * This function will only be run in some configurations so it should be pure, and only used to detect bugs (when debugAssert are enabled), and must not be relied on to enforce the condition is true: for that use {@link assert}.
+ * @remarks
+ * Optimizing the asserts out of the bundle requires a bundler like webpack which leverages `__PURE__` annotations like https://webpack.js.org/guides/tree-shaking/#mark-a-function-call-as-side-effect-free.
+ *
+ * Exceptions thrown by this function must never be caught in production code, as that will result in different behavior when testing and when running optimized builds.
+ * The `predicate` function must be pure (have no side-effects) to ensure that the behavior of code is the same regardless of if the asserts are disabled, enabled or optimized out.
+ *
+ * These asserts are disabled by default, even in debug builds to ensure that by default code will be tested as production runs, with them disabled.
+ * Additionally, this ensures that apps that use a bundler which does not remove `__PURE__` will not incur the runtime cost of calling the predicate.
+ * These asserts can be can be enabled by calling `configureDebugAsserts(true)`: see {@link configureDebugAsserts}.
+ *
+ * @privateRemarks
+ * This design was chosen to accomplish two main goals:
+ *
+ * 1. Make it easy to compile debug asserts fully out of production builds.
+ * For webpack this happens by default, avoiding the need for customers to do special configuration.
+ * This is important for both performance and bundle size.
+ *
+ * 2. Make it easy to test (both manually and automated) with and without the predicates running.
+ * This ensures it is possible to benefit from the asserts when enabled, but also test with them disabled to ensure this disablement doesn't cause bugs.
+ *
+ * The default behavior of having debugAsserts disabled helps ensure that tests which don't know about debug asserts will still run in a way that is most similar to production.
+ * @internal
+ */
+export function debugAssert(predicate: () => true | { toString(): string }): void {
+	// This is valid since the contract for this function is that "predicate" should be side effect free and never return non true in production scenarios:
+	// it returning non-true indicates a bug is present, and that the validation it does to detect the bug is only desired in specific test/debug situations.
+	// Production scenarios, where pure code is removed, should never hit a failing predicate, and thus this code should be side effect free.
+	skipInProduction(() => {
+		if (debugAssertsEnabled) {
+			const result = predicate();
+			if (result !== true) {
+				debugger;
+				throw new Error(`Debug assert failed: ${result.toString()}`);
+			}
+		}
+	});
+}
+
+let debugAssertsEnabled = false;
+
+/**
+ * Enables {@link debugAssert} validation.
+ * @remarks
+ * Throws if debugAsserts have been optimized out.
+ * @returns The previous state of debugAsserts.
+ * @internal
+ */
+export function configureDebugAsserts(enabled: boolean): boolean {
+	assert(
+		nonProductionConditionalsIncluded(),
+		0xab1 /* Debug asserts cannot be configured since they have been optimized out. */,
+	);
+	const old = debugAssertsEnabled;
+	debugAssertsEnabled = enabled;
+	return old;
+}
+
+/**
+ * Checks if non-production conditional code like {@link debugAssert} is included in this build.
+ * @remarks
+ * Such code can be optimized out by bundlers: this checks if that has occurred.
+ * @privateRemarks
+ * See {@link skipInProduction}.
+ * @internal
+ */
+export function nonProductionConditionalsIncluded(): boolean {
+	let included = false;
+	skipInProduction(() => {
+		included = true;
+	});
+	return included;
+}
+
+/**
+ * Run `conditional` only in debug/development (non optimized/minified) builds, but optimize it out of production builds.
+ *
+ * @param conditional - This function will only be run in some configurations so it should be pure (at least in production scenarios).
+ * It can be used to interact with debug only functionality that is also removed in production builds, or to do validation/testing/debugging that can be assumed to be sideeffect free in production where it might be removed.
+ * @remarks
+ * Great care must be taken when using this to ensure that bugs are not introduced which only occur when `conditional` is not run.
+ * One way to do this is to provide an alternative way to disable the effects of `conditional` in development builds so both configurations can be tested:
+ * {@link debugAssert} uses this pattern.
+ *
+ * @privateRemarks
+ * Since this function has no built in option for toggling it in development for testing, it is not exported and is only used as a building block for other testable options.
+ * There are some additional details about syntax and bundler support in https://github.com/javascript-compiler-hints/compiler-notations-spec/tree/main .
+ * This code uses both NO_SIDE_EFFECTS and PURE to maximize compatibility: for any bundler supporting both they are redundant.
+ */
+// Using the exact syntax from https://github.com/javascript-compiler-hints/compiler-notations-spec/blob/main/no-side-effects-notation-spec.md to maximize compatibility with tree-shaking tools.
+// eslint-disable-next-line spaced-comment
+/*#__NO_SIDE_EFFECTS__*/
+function skipInProduction(conditional: () => void): void {
+	// Here __PURE__ annotation is used to indicate that is is safe to optimize out this call.
+	// This is valid since the contract for this function is that "conditional" should be side effect free if it were run in production scenarios
+	// See https://webpack.js.org/guides/tree-shaking/#mark-a-function-call-as-side-effect-free for documentation on this annotation.
+
+	// Using the exact syntax from https://webpack.js.org/guides/tree-shaking/#mark-a-function-call-as-side-effect-free to maximize compatibility with tree-shaking tools.
+	// eslint-disable-next-line spaced-comment
+	/*#__PURE__*/ conditional();
+}

package/src/index.ts

@@ -3,7 +3,12 @@
  * Licensed under the MIT License.
  */
 
-export { assert } from "./assert.js";
+export {
+	assert,
+	debugAssert,
+	configureDebugAsserts,
+	nonProductionConditionalsIncluded,
+} from "./assert.js";
 export { compareArrays } from "./compare.js";
 export { delay } from "./delay.js";
 export type { IComparer, IHeapNode } from "./heap.js";
@@ -12,6 +17,7 @@ export { Lazy, LazyPromise } from "./lazy.js";
 export type { PromiseCacheExpiry, PromiseCacheOptions } from "./promiseCache.js";
 export { PromiseCache } from "./promiseCache.js";
 export { Deferred } from "./promises.js";
+export { shallowCloneObject } from "./shallowClone.js";
 export type { IPromiseTimer, IPromiseTimerResult, ITimer } from "./timer.js";
 export { PromiseTimer, setLongTimeout, Timer } from "./timer.js";
 export { unreachableCase } from "./unreachable.js";

package/src/shallowClone.ts

@@ -0,0 +1,18 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Shallow clone an object.
+ *
+ * @param value - The object to clone
+ * @returns A shallow clone of the input value
+ * @internal
+ */
+export function shallowCloneObject<T extends object>(value: T): T {
+	if (Array.isArray(value)) {
+		return [...value] as T;
+	}
+	return { ...value };
+}