@fluidframework/core-utils 2.81.1 → 2.82.0

package/CHANGELOG.md

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

package/README.md

@@ -31,6 +31,8 @@ For more information on the related support guarantees, see [API Support Levels]
 
 To access the `public` ([SemVer](https://semver.org/)) APIs, import via `@fluidframework/core-utils` like normal.
 
+To access the `alpha` APIs, import via `@fluidframework/core-utils/alpha`.
+
 To access the `legacy` APIs, import via `@fluidframework/core-utils/legacy`.
 
 ## API Documentation

package/alpha.d.ts

@@ -0,0 +1,11 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/*
+ * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
+ * Generated by "flub generate entrypoints" in @fluid-tools/build-cli.
+ */
+
+export * from "./lib/alpha.js";

package/api-extractor/api-extractor-lint-alpha.cjs.json

@@ -0,0 +1,5 @@
+{
+	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+	"extends": "<projectFolder>/../../../common/build/build-common/api-extractor-lint.entrypoint.json",
+	"mainEntryPointFilePath": "<projectFolder>/dist/alpha.d.ts"
+}

package/api-extractor/api-extractor-lint-alpha.esm.json

@@ -0,0 +1,5 @@
+{
+	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+	"extends": "<projectFolder>/../../../common/build/build-common/api-extractor-lint.entrypoint.json",
+	"mainEntryPointFilePath": "<projectFolder>/lib/alpha.d.ts"
+}

package/api-extractor/api-extractor.current.json

@@ -1,5 +1,9 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
 	"extends": "<projectFolder>/../../../common/build/build-common/api-extractor-report.esm.current.json",
-	"mainEntryPointFilePath": "<projectFolder>/lib/public.d.ts"
+	"mainEntryPointFilePath": "<projectFolder>/lib/alpha.d.ts",
+	"apiReport": {
+		// The base config omits alpha. Explicitly opt into alpha reports (in addition to public/beta) for this package.
+		"reportVariants": ["public", "beta", "alpha"]
+	}
 }

package/api-report/core-utils.alpha.api.md

@@ -0,0 +1,18 @@
+## Alpha API Report File for "@fluidframework/core-utils"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+// @alpha
+export function emulateProductionBuild(enable?: boolean): void;
+
+// @alpha
+export function nonProductionConditionalsIncluded(): boolean;
+
+// @alpha
+export function onAssertionFailure(handler: (error: Error) => void): () => void;
+
+// (No @packageDocumentation comment for this package)
+
+```

package/dist/alpha.d.ts

@@ -0,0 +1,17 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/*
+ * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
+ * Generated by "flub generate entrypoints" in @fluid-tools/build-cli.
+ */
+
+export {
+	// #region @alpha APIs
+	emulateProductionBuild, 
+	nonProductionConditionalsIncluded, 
+	onAssertionFailure
+	// #endregion
+} from "./index.js";

package/dist/assert.d.ts

@@ -140,7 +140,7 @@ export declare function configureDebugAsserts(enabled: boolean): boolean;
  * More details on these annotations can be found at {@link  https://github.com/javascript-compiler-hints/compiler-notations-spec/tree/main}.
  * @privateRemarks
  * See {@link skipInProductionInner}.
- * @internal
+ * @alpha
  */
 export declare function nonProductionConditionalsIncluded(): boolean;
 /**
@@ -172,7 +172,7 @@ export declare function nonProductionConditionalsIncluded(): boolean;
  * The approach taken with `configureDebugAsserts` is a bit more flexible, allowing both opt in and opt out, but also more error prone.
  * This API, `emulateProductionBuild` provides a more restrictive but less error prone option targeted at being a final defense for detecting cases where production mode causes issues.
  * It catches some cases `configureDebugAsserts` can't, like dependency on side effects of failing asserts debug message callback.
- * @internal
+ * @alpha
  */
 export declare function emulateProductionBuild(enable?: boolean): void;
 //# sourceMappingURL=assert.d.ts.map

package/dist/assert.js

@@ -205,7 +205,7 @@ exports.configureDebugAsserts = configureDebugAsserts;
  * More details on these annotations can be found at {@link  https://github.com/javascript-compiler-hints/compiler-notations-spec/tree/main}.
  * @privateRemarks
  * See {@link skipInProductionInner}.
- * @internal
+ * @alpha
  */
 function nonProductionConditionalsIncluded() {
     let included = false;
@@ -244,7 +244,7 @@ exports.nonProductionConditionalsIncluded = nonProductionConditionalsIncluded;
  * The approach taken with `configureDebugAsserts` is a bit more flexible, allowing both opt in and opt out, but also more error prone.
  * This API, `emulateProductionBuild` provides a more restrictive but less error prone option targeted at being a final defense for detecting cases where production mode causes issues.
  * It catches some cases `configureDebugAsserts` can't, like dependency on side effects of failing asserts debug message callback.
- * @internal
+ * @alpha
  */
 function emulateProductionBuild(enable = true) {
     emulateProductionBuildCount += enable ? 1 : -1;

package/dist/assert.js.map

@@ -1 +1 @@
-{"version":3,"file":"assert.js","sourceRoot":"","sources":["../src/assert.ts"],"names":[],"mappings":"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","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 literal instead.\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 * @param debugMessageBuilder - An optional function that can be used to build a debug message to include in the error in development builds.\n * Only executed if `condition` is false. `debugMessageBuilder` is not executed in production builds, see `skipInProduction` for details.\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 {@link 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 `skipInProduction` reference above should be turned into a link.\n * @legacy @beta\n */\nexport function assert(\n\tcondition: boolean,\n\tmessage: string | number,\n\tdebugMessageBuilder?: () => string,\n): asserts condition {\n\tif (!condition) {\n\t\tfailPrivate(message, debugMessageBuilder);\n\t}\n}\n\n/**\n * {@link fail}'s implementation, but extracted to avoid assert tagging trying to tag the use of it in `assert`.\n */\nfunction failPrivate(message: string | number, debugMessageBuilder?: () => string): never {\n\tlet messageString =\n\t\ttypeof message === \"number\" ? `0x${message.toString(16).padStart(3, \"0\")}` : message;\n\tskipInProduction(() => {\n\t\tif (debugMessageBuilder !== undefined) {\n\t\t\tmessageString = `${messageString}\\nDebug Message: ${debugMessageBuilder()}`;\n\t\t}\n\t\t// Using console.log instead of console.error or console.warn since the latter two may break downstream users.\n\t\tconsole.log(`Bug in Fluid Framework: Failed Assertion: ${messageString}`);\n\t});\n\tconst error = new Error(messageString);\n\tonAssertionError(error);\n\tthrow error;\n}\n\n/**\n * Throw an error with a constant message.\n * @remarks\n * Works like {@link assert}, but errors unconditionally instead of taking in a condition.\n *\n * Unlike `assert`, this `fail` is not \"tagged\" by the assert tagging too by default.\n * Use a `assertTagging.config.mjs` file to enable this and any other assert tagging customizations as needed.\n *\n * Returns `never` so it can be used inline as part of an expression, or as a return value.\n * @example\n * ```ts\n *  const x: number = numbersMap.get(\"foo\") ?? fail(\"foo missing from map\");\n * ```\n * @see {@link assert}\n * @internal\n */\nexport function fail(message: string | number, debugMessageBuilder?: () => string): never {\n\tfailPrivate(message, debugMessageBuilder);\n}\n\nfunction onAssertionError(error: Error): void {\n\tfor (const handler of firstChanceAssertionHandler) {\n\t\thandler(error);\n\t}\n}\n\nconst firstChanceAssertionHandler = new Set<(error: Error) => void>();\n\n/**\n * Add a callback which can be used to report an assertion before it is thrown.\n * @param handler - Called when an assertion occurs before the exception is thrown.\n * @returns a function to remove the handler.\n * @remarks\n * The callback runs just before the exception is thrown, which makes it a better place to report telemetry for Fluid Framework bugs than a catch block or an event like `window.onerror`.\n * Using this API to report telemetry is preferred over those approaches since it eliminates the risk of the exception being swallowed or obfuscated by an intermediate stack frame's catch block\n * or missed due to not having the right catch block or event handler.\n *\n * This does not replace the need for error handling elsewhere since errors (even bugs in Fluid) can cause other kinds of exceptions which this cannot run the callback for.\n * @example\n * ```ts\n * import { onAssertionFailure } from \"fluid-framework/alpha\";\n *\n * let firstAssertion: Error | undefined;\n *\n * onAssertionFailure((error: Error) => {\n * \tconst priorErrorNote =\n * \t\tfirstAssertion === undefined\n * \t\t\t? \"Please report this bug.\"\n * \t\t\t: `Might be caused due to prior error ${JSON.stringify(firstAssertion.message)} which should be investigated first.`;\n * \tconst message = `Encountered Bug in Fluid Framework: ${error.message}\\n${priorErrorNote}\\n${error.stack}`;\n * \tconsole.error(message);\n *\n * \tdebugger;\n * \tfirstAssertion ??= error;\n * });\n * ```\n * @alpha\n */\nexport function onAssertionFailure(handler: (error: Error) => void): () => void {\n\t// To avoid issues if the same callback is registered twice (mainly it not triggering twice and the first unregister removing it),\n\t// generate a wrapper around the handler.\n\tconst wrapper = (error: Error): void => {\n\t\thandler(error);\n\t};\n\tfirstChanceAssertionHandler.add(wrapper);\n\treturn () => {\n\t\tfirstChanceAssertionHandler.delete(wrapper);\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 * Enabled when {@link nonProductionConditionalsIncluded} is true.\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 * 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 enabled by default in debug builds: this introduces risk that code may behave differently when they are disabled or optimized out.\n * To mitigate this risk, these asserts can be disabled in debug builds by calling {@link configureDebugAsserts} or {@link emulateProductionBuild}.\n * This allows testing with the asserts both enabled and disabled to help ensure that code does not depend on them being enabled.\n *\n * Apps (or other performance sensitive scenarios) packaged in a way that does not {@link nonProductionConditionalsIncluded|skip non-production code}\n * can use the same approaches to disable these asserts to reduce performance overhead.\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 enabled helps ensure debugAsserts are effective at catching bugs during development and testing.\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\tconst error = new Error(`Debug assert failed: ${result.toString()}`);\n\t\t\t\tonAssertionError(error);\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t}\n\t});\n}\n\nlet debugAssertsEnabled = true;\n\n/**\n * Enables {@link debugAssert} validation.\n * @remarks\n * Throws if debugAsserts have been optimized out.\n *\n * Disabling debugAsserts has two main use cases:\n *\n * 1. Testing that the code behaves correctly in a more production like configuration.\n * 2. Reducing performance overhead.\n *\n * Disabling debugAsserts does not make everything production like: see {@link emulateProductionBuild} for a way to disable more non-production code.\n *\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 or by {@link emulateProductionBuild}: this checks if that has occurred.\n *\n * The non-production used by this library is annotated with `__PURE__` and `#__NO_SIDE_EFFECTS__` and has no return value and thus is removed by bundlers when optimizing based on these annotations.\n * Typically this means that such code is removed in production builds.\n * More details on these annotations can be found at {@link  https://github.com/javascript-compiler-hints/compiler-notations-spec/tree/main}.\n * @privateRemarks\n * See {@link skipInProductionInner}.\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 * Overrides the behavior code which optimizes out non-production conditional code like {@link debugAssert} and {@link nonProductionConditionalsIncluded}.\n *\n * Can be called multiple times. Will emulate production builds if called with `true` more times than `false`.\n * Emulation of production builds is disabled when enabled and disabled counts match (including at 0, by default).\n * It is an error to disable this more than it was enabled.\n *\n * @remarks\n * This is intended for testing that the code behaves correctly in production configurations.\n * Since tools like {@link debugAssert} typically add additional validation to help catch more bugs, tests should generally be run with such checks enabled (and thus emulateProductionBuild in its default disabled state).\n * However it is possible that some debugAsserts could accidentally change behavior and hide a bug.\n * This function provides a way to globally disable the debugAsserts so it is possible to run test suites in a production like mode without having to do a production bundling of them.\n *\n * To avoid introducing additional risk that code does production-specific logic using this setting, the actual setting is not exposed.\n * The intended use is that a pipeline could enable this before running the test suite (for example based on a CLI flag).\n * Such a run may have to also use some filtering to skip any tests which explicity check development only tooling, possibly via {@link nonProductionConditionalsIncluded} or some other mechanism like a test tag.\n *\n * @privateRemarks\n * See {@link skipInProduction}.\n *\n * This design, with a counter, was picked so that it's always safe for some scope to opt in when trying to test production behavior,\n * and it should be basically impossible to accidentally fail to test the production mode when trying to.\n * Some tests or test suites may want to run in production mode and they can use this API to opt in (via before and after hooks for example).\n * Additionally something might want to opt into production mode at some other level (for example test running the entire test suite again with production mode enabled).\n * In such setups, it's important that tests which were explicitly opting in don't accidentally disable production mode for the rest of the run when ending if something higher level enabled it.\n *\n * The approach taken with `configureDebugAsserts` is a bit more flexible, allowing both opt in and opt out, but also more error prone.\n * This API, `emulateProductionBuild` provides a more restrictive but less error prone option targeted at being a final defense for detecting cases where production mode causes issues.\n * It catches some cases `configureDebugAsserts` can't, like dependency on side effects of failing asserts debug message callback.\n * @internal\n */\nexport function emulateProductionBuild(enable = true): void {\n\temulateProductionBuildCount += enable ? 1 : -1;\n\tassert(\n\t\temulateProductionBuildCount >= 0,\n\t\t0xc70 /* emulateProductionBuild disabled more than it was enabled */,\n\t);\n}\n\nlet emulateProductionBuildCount = 0;\n\n/**\n * {@link skipInProductionInner}, except can be disabled by {@link emulateProductionBuild}.\n */\nfunction skipInProduction(conditional: () => void): void {\n\tskipInProductionInner(() => {\n\t\tif (emulateProductionBuildCount === 0) conditional();\n\t});\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 skipInProductionInner(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"]}
+{"version":3,"file":"assert.js","sourceRoot":"","sources":["../src/assert.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,SAAgB,MAAM,CACrB,SAAkB,EAClB,OAAwB,EACxB,mBAAkC;IAElC,IAAI,CAAC,SAAS,EAAE,CAAC;QAChB,WAAW,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC;IAC3C,CAAC;AACF,CAAC;AARD,wBAQC;AAED;;GAEG;AACH,SAAS,WAAW,CAAC,OAAwB,EAAE,mBAAkC;IAChF,IAAI,aAAa,GAChB,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,CAAC;IACtF,gBAAgB,CAAC,GAAG,EAAE;QACrB,IAAI,mBAAmB,KAAK,SAAS,EAAE,CAAC;YACvC,aAAa,GAAG,GAAG,aAAa,oBAAoB,mBAAmB,EAAE,EAAE,CAAC;QAC7E,CAAC;QACD,8GAA8G;QAC9G,OAAO,CAAC,GAAG,CAAC,6CAA6C,aAAa,EAAE,CAAC,CAAC;IAC3E,CAAC,CAAC,CAAC;IACH,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,aAAa,CAAC,CAAC;IACvC,gBAAgB,CAAC,KAAK,CAAC,CAAC;IACxB,MAAM,KAAK,CAAC;AACb,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,SAAgB,IAAI,CAAC,OAAwB,EAAE,mBAAkC;IAChF,WAAW,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC;AAC3C,CAAC;AAFD,oBAEC;AAED,SAAS,gBAAgB,CAAC,KAAY;IACrC,KAAK,MAAM,OAAO,IAAI,2BAA2B,EAAE,CAAC;QACnD,OAAO,CAAC,KAAK,CAAC,CAAC;IAChB,CAAC;AACF,CAAC;AAED,MAAM,2BAA2B,GAAG,IAAI,GAAG,EAA0B,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,SAAgB,kBAAkB,CAAC,OAA+B;IACjE,kIAAkI;IAClI,yCAAyC;IACzC,MAAM,OAAO,GAAG,CAAC,KAAY,EAAQ,EAAE;QACtC,OAAO,CAAC,KAAK,CAAC,CAAC;IAChB,CAAC,CAAC;IACF,2BAA2B,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACzC,OAAO,GAAG,EAAE;QACX,2BAA2B,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC7C,CAAC,CAAC;AACH,CAAC;AAVD,gDAUC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;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,KAAK,GAAG,IAAI,KAAK,CAAC,wBAAwB,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;gBACrE,gBAAgB,CAAC,KAAK,CAAC,CAAC;gBACxB,MAAM,KAAK,CAAC;YACb,CAAC;QACF,CAAC;IACF,CAAC,CAAC,CAAC;AACJ,CAAC;AAfD,kCAeC;AAED,IAAI,mBAAmB,GAAG,IAAI,CAAC;AAE/B;;;;;;;;;;;;;;GAcG;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;;;;;;;;;;;GAWG;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,SAAgB,sBAAsB,CAAC,MAAM,GAAG,IAAI;IACnD,2BAA2B,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/C,MAAM,CACL,2BAA2B,IAAI,CAAC,EAChC,KAAK,CAAC,8DAA8D,CACpE,CAAC;AACH,CAAC;AAND,wDAMC;AAED,IAAI,2BAA2B,GAAG,CAAC,CAAC;AAEpC;;GAEG;AACH,SAAS,gBAAgB,CAAC,WAAuB;IAChD,qBAAqB,CAAC,GAAG,EAAE;QAC1B,IAAI,2BAA2B,KAAK,CAAC;YAAE,WAAW,EAAE,CAAC;IACtD,CAAC,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,iMAAiM;AACjM,0CAA0C;AAC1C,wBAAwB;AACxB,SAAS,qBAAqB,CAAC,WAAuB;IACrD,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 literal instead.\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 * @param debugMessageBuilder - An optional function that can be used to build a debug message to include in the error in development builds.\n * Only executed if `condition` is false. `debugMessageBuilder` is not executed in production builds, see `skipInProduction` for details.\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 {@link 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 `skipInProduction` reference above should be turned into a link.\n * @legacy @beta\n */\nexport function assert(\n\tcondition: boolean,\n\tmessage: string | number,\n\tdebugMessageBuilder?: () => string,\n): asserts condition {\n\tif (!condition) {\n\t\tfailPrivate(message, debugMessageBuilder);\n\t}\n}\n\n/**\n * {@link fail}'s implementation, but extracted to avoid assert tagging trying to tag the use of it in `assert`.\n */\nfunction failPrivate(message: string | number, debugMessageBuilder?: () => string): never {\n\tlet messageString =\n\t\ttypeof message === \"number\" ? `0x${message.toString(16).padStart(3, \"0\")}` : message;\n\tskipInProduction(() => {\n\t\tif (debugMessageBuilder !== undefined) {\n\t\t\tmessageString = `${messageString}\\nDebug Message: ${debugMessageBuilder()}`;\n\t\t}\n\t\t// Using console.log instead of console.error or console.warn since the latter two may break downstream users.\n\t\tconsole.log(`Bug in Fluid Framework: Failed Assertion: ${messageString}`);\n\t});\n\tconst error = new Error(messageString);\n\tonAssertionError(error);\n\tthrow error;\n}\n\n/**\n * Throw an error with a constant message.\n * @remarks\n * Works like {@link assert}, but errors unconditionally instead of taking in a condition.\n *\n * Unlike `assert`, this `fail` is not \"tagged\" by the assert tagging too by default.\n * Use a `assertTagging.config.mjs` file to enable this and any other assert tagging customizations as needed.\n *\n * Returns `never` so it can be used inline as part of an expression, or as a return value.\n * @example\n * ```ts\n *  const x: number = numbersMap.get(\"foo\") ?? fail(\"foo missing from map\");\n * ```\n * @see {@link assert}\n * @internal\n */\nexport function fail(message: string | number, debugMessageBuilder?: () => string): never {\n\tfailPrivate(message, debugMessageBuilder);\n}\n\nfunction onAssertionError(error: Error): void {\n\tfor (const handler of firstChanceAssertionHandler) {\n\t\thandler(error);\n\t}\n}\n\nconst firstChanceAssertionHandler = new Set<(error: Error) => void>();\n\n/**\n * Add a callback which can be used to report an assertion before it is thrown.\n * @param handler - Called when an assertion occurs before the exception is thrown.\n * @returns a function to remove the handler.\n * @remarks\n * The callback runs just before the exception is thrown, which makes it a better place to report telemetry for Fluid Framework bugs than a catch block or an event like `window.onerror`.\n * Using this API to report telemetry is preferred over those approaches since it eliminates the risk of the exception being swallowed or obfuscated by an intermediate stack frame's catch block\n * or missed due to not having the right catch block or event handler.\n *\n * This does not replace the need for error handling elsewhere since errors (even bugs in Fluid) can cause other kinds of exceptions which this cannot run the callback for.\n * @example\n * ```ts\n * import { onAssertionFailure } from \"fluid-framework/alpha\";\n *\n * let firstAssertion: Error | undefined;\n *\n * onAssertionFailure((error: Error) => {\n * \tconst priorErrorNote =\n * \t\tfirstAssertion === undefined\n * \t\t\t? \"Please report this bug.\"\n * \t\t\t: `Might be caused due to prior error ${JSON.stringify(firstAssertion.message)} which should be investigated first.`;\n * \tconst message = `Encountered Bug in Fluid Framework: ${error.message}\\n${priorErrorNote}\\n${error.stack}`;\n * \tconsole.error(message);\n *\n * \tdebugger;\n * \tfirstAssertion ??= error;\n * });\n * ```\n * @alpha\n */\nexport function onAssertionFailure(handler: (error: Error) => void): () => void {\n\t// To avoid issues if the same callback is registered twice (mainly it not triggering twice and the first unregister removing it),\n\t// generate a wrapper around the handler.\n\tconst wrapper = (error: Error): void => {\n\t\thandler(error);\n\t};\n\tfirstChanceAssertionHandler.add(wrapper);\n\treturn () => {\n\t\tfirstChanceAssertionHandler.delete(wrapper);\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 * Enabled when {@link nonProductionConditionalsIncluded} is true.\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 * 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 enabled by default in debug builds: this introduces risk that code may behave differently when they are disabled or optimized out.\n * To mitigate this risk, these asserts can be disabled in debug builds by calling {@link configureDebugAsserts} or {@link emulateProductionBuild}.\n * This allows testing with the asserts both enabled and disabled to help ensure that code does not depend on them being enabled.\n *\n * Apps (or other performance sensitive scenarios) packaged in a way that does not {@link nonProductionConditionalsIncluded|skip non-production code}\n * can use the same approaches to disable these asserts to reduce performance overhead.\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 enabled helps ensure debugAsserts are effective at catching bugs during development and testing.\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\tconst error = new Error(`Debug assert failed: ${result.toString()}`);\n\t\t\t\tonAssertionError(error);\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t}\n\t});\n}\n\nlet debugAssertsEnabled = true;\n\n/**\n * Enables {@link debugAssert} validation.\n * @remarks\n * Throws if debugAsserts have been optimized out.\n *\n * Disabling debugAsserts has two main use cases:\n *\n * 1. Testing that the code behaves correctly in a more production like configuration.\n * 2. Reducing performance overhead.\n *\n * Disabling debugAsserts does not make everything production like: see {@link emulateProductionBuild} for a way to disable more non-production code.\n *\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 or by {@link emulateProductionBuild}: this checks if that has occurred.\n *\n * The non-production used by this library is annotated with `__PURE__` and `#__NO_SIDE_EFFECTS__` and has no return value and thus is removed by bundlers when optimizing based on these annotations.\n * Typically this means that such code is removed in production builds.\n * More details on these annotations can be found at {@link  https://github.com/javascript-compiler-hints/compiler-notations-spec/tree/main}.\n * @privateRemarks\n * See {@link skipInProductionInner}.\n * @alpha\n */\nexport function nonProductionConditionalsIncluded(): boolean {\n\tlet included = false;\n\tskipInProduction(() => {\n\t\tincluded = true;\n\t});\n\treturn included;\n}\n\n/**\n * Overrides the behavior code which optimizes out non-production conditional code like {@link debugAssert} and {@link nonProductionConditionalsIncluded}.\n *\n * Can be called multiple times. Will emulate production builds if called with `true` more times than `false`.\n * Emulation of production builds is disabled when enabled and disabled counts match (including at 0, by default).\n * It is an error to disable this more than it was enabled.\n *\n * @remarks\n * This is intended for testing that the code behaves correctly in production configurations.\n * Since tools like {@link debugAssert} typically add additional validation to help catch more bugs, tests should generally be run with such checks enabled (and thus emulateProductionBuild in its default disabled state).\n * However it is possible that some debugAsserts could accidentally change behavior and hide a bug.\n * This function provides a way to globally disable the debugAsserts so it is possible to run test suites in a production like mode without having to do a production bundling of them.\n *\n * To avoid introducing additional risk that code does production-specific logic using this setting, the actual setting is not exposed.\n * The intended use is that a pipeline could enable this before running the test suite (for example based on a CLI flag).\n * Such a run may have to also use some filtering to skip any tests which explicity check development only tooling, possibly via {@link nonProductionConditionalsIncluded} or some other mechanism like a test tag.\n *\n * @privateRemarks\n * See {@link skipInProduction}.\n *\n * This design, with a counter, was picked so that it's always safe for some scope to opt in when trying to test production behavior,\n * and it should be basically impossible to accidentally fail to test the production mode when trying to.\n * Some tests or test suites may want to run in production mode and they can use this API to opt in (via before and after hooks for example).\n * Additionally something might want to opt into production mode at some other level (for example test running the entire test suite again with production mode enabled).\n * In such setups, it's important that tests which were explicitly opting in don't accidentally disable production mode for the rest of the run when ending if something higher level enabled it.\n *\n * The approach taken with `configureDebugAsserts` is a bit more flexible, allowing both opt in and opt out, but also more error prone.\n * This API, `emulateProductionBuild` provides a more restrictive but less error prone option targeted at being a final defense for detecting cases where production mode causes issues.\n * It catches some cases `configureDebugAsserts` can't, like dependency on side effects of failing asserts debug message callback.\n * @alpha\n */\nexport function emulateProductionBuild(enable = true): void {\n\temulateProductionBuildCount += enable ? 1 : -1;\n\tassert(\n\t\temulateProductionBuildCount >= 0,\n\t\t0xc70 /* emulateProductionBuild disabled more than it was enabled */,\n\t);\n}\n\nlet emulateProductionBuildCount = 0;\n\n/**\n * {@link skipInProductionInner}, except can be disabled by {@link emulateProductionBuild}.\n */\nfunction skipInProduction(conditional: () => void): void {\n\tskipInProductionInner(() => {\n\t\tif (emulateProductionBuildCount === 0) conditional();\n\t});\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 skipInProductionInner(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/alpha.d.ts

@@ -0,0 +1,17 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/*
+ * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
+ * Generated by "flub generate entrypoints" in @fluid-tools/build-cli.
+ */
+
+export {
+	// #region @alpha APIs
+	emulateProductionBuild, 
+	nonProductionConditionalsIncluded, 
+	onAssertionFailure
+	// #endregion
+} from "./index.js";

package/lib/assert.d.ts

@@ -140,7 +140,7 @@ export declare function configureDebugAsserts(enabled: boolean): boolean;
  * More details on these annotations can be found at {@link  https://github.com/javascript-compiler-hints/compiler-notations-spec/tree/main}.
  * @privateRemarks
  * See {@link skipInProductionInner}.
- * @internal
+ * @alpha
  */
 export declare function nonProductionConditionalsIncluded(): boolean;
 /**
@@ -172,7 +172,7 @@ export declare function nonProductionConditionalsIncluded(): boolean;
  * The approach taken with `configureDebugAsserts` is a bit more flexible, allowing both opt in and opt out, but also more error prone.
  * This API, `emulateProductionBuild` provides a more restrictive but less error prone option targeted at being a final defense for detecting cases where production mode causes issues.
  * It catches some cases `configureDebugAsserts` can't, like dependency on side effects of failing asserts debug message callback.
- * @internal
+ * @alpha
  */
 export declare function emulateProductionBuild(enable?: boolean): void;
 //# sourceMappingURL=assert.d.ts.map

package/lib/assert.js

@@ -197,7 +197,7 @@ export function configureDebugAsserts(enabled) {
  * More details on these annotations can be found at {@link  https://github.com/javascript-compiler-hints/compiler-notations-spec/tree/main}.
  * @privateRemarks
  * See {@link skipInProductionInner}.
- * @internal
+ * @alpha
  */
 export function nonProductionConditionalsIncluded() {
     let included = false;
@@ -235,7 +235,7 @@ export function nonProductionConditionalsIncluded() {
  * The approach taken with `configureDebugAsserts` is a bit more flexible, allowing both opt in and opt out, but also more error prone.
  * This API, `emulateProductionBuild` provides a more restrictive but less error prone option targeted at being a final defense for detecting cases where production mode causes issues.
  * It catches some cases `configureDebugAsserts` can't, like dependency on side effects of failing asserts debug message callback.
- * @internal
+ * @alpha
  */
 export function emulateProductionBuild(enable = true) {
     emulateProductionBuildCount += enable ? 1 : -1;

package/lib/assert.js.map

@@ -1 +1 @@
-{"version":3,"file":"assert.js","sourceRoot":"","sources":["../src/assert.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,MAAM,CACrB,SAAkB,EAClB,OAAwB,EACxB,mBAAkC;IAElC,IAAI,CAAC,SAAS,EAAE,CAAC;QAChB,WAAW,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC;IAC3C,CAAC;AACF,CAAC;AAED;;GAEG;AACH,SAAS,WAAW,CAAC,OAAwB,EAAE,mBAAkC;IAChF,IAAI,aAAa,GAChB,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,CAAC;IACtF,gBAAgB,CAAC,GAAG,EAAE;QACrB,IAAI,mBAAmB,KAAK,SAAS,EAAE,CAAC;YACvC,aAAa,GAAG,GAAG,aAAa,oBAAoB,mBAAmB,EAAE,EAAE,CAAC;QAC7E,CAAC;QACD,8GAA8G;QAC9G,OAAO,CAAC,GAAG,CAAC,6CAA6C,aAAa,EAAE,CAAC,CAAC;IAC3E,CAAC,CAAC,CAAC;IACH,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,aAAa,CAAC,CAAC;IACvC,gBAAgB,CAAC,KAAK,CAAC,CAAC;IACxB,MAAM,KAAK,CAAC;AACb,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,IAAI,CAAC,OAAwB,EAAE,mBAAkC;IAChF,WAAW,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC;AAC3C,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAY;IACrC,KAAK,MAAM,OAAO,IAAI,2BAA2B,EAAE,CAAC;QACnD,OAAO,CAAC,KAAK,CAAC,CAAC;IAChB,CAAC;AACF,CAAC;AAED,MAAM,2BAA2B,GAAG,IAAI,GAAG,EAA0B,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAA+B;IACjE,kIAAkI;IAClI,yCAAyC;IACzC,MAAM,OAAO,GAAG,CAAC,KAAY,EAAQ,EAAE;QACtC,OAAO,CAAC,KAAK,CAAC,CAAC;IAChB,CAAC,CAAC;IACF,2BAA2B,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACzC,OAAO,GAAG,EAAE;QACX,2BAA2B,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC7C,CAAC,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;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,KAAK,GAAG,IAAI,KAAK,CAAC,wBAAwB,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;gBACrE,gBAAgB,CAAC,KAAK,CAAC,CAAC;gBACxB,MAAM,KAAK,CAAC;YACb,CAAC;QACF,CAAC;IACF,CAAC,CAAC,CAAC;AACJ,CAAC;AAED,IAAI,mBAAmB,GAAG,IAAI,CAAC;AAE/B;;;;;;;;;;;;;;GAcG;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;;;;;;;;;;;GAWG;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAAM,GAAG,IAAI;IACnD,2BAA2B,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/C,MAAM,CACL,2BAA2B,IAAI,CAAC,EAChC,KAAK,CAAC,8DAA8D,CACpE,CAAC;AACH,CAAC;AAED,IAAI,2BAA2B,GAAG,CAAC,CAAC;AAEpC;;GAEG;AACH,SAAS,gBAAgB,CAAC,WAAuB;IAChD,qBAAqB,CAAC,GAAG,EAAE;QAC1B,IAAI,2BAA2B,KAAK,CAAC;YAAE,WAAW,EAAE,CAAC;IACtD,CAAC,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,iMAAiM;AACjM,0CAA0C;AAC1C,wBAAwB;AACxB,SAAS,qBAAqB,CAAC,WAAuB;IACrD,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 literal instead.\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 * @param debugMessageBuilder - An optional function that can be used to build a debug message to include in the error in development builds.\n * Only executed if `condition` is false. `debugMessageBuilder` is not executed in production builds, see `skipInProduction` for details.\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 {@link 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 `skipInProduction` reference above should be turned into a link.\n * @legacy @beta\n */\nexport function assert(\n\tcondition: boolean,\n\tmessage: string | number,\n\tdebugMessageBuilder?: () => string,\n): asserts condition {\n\tif (!condition) {\n\t\tfailPrivate(message, debugMessageBuilder);\n\t}\n}\n\n/**\n * {@link fail}'s implementation, but extracted to avoid assert tagging trying to tag the use of it in `assert`.\n */\nfunction failPrivate(message: string | number, debugMessageBuilder?: () => string): never {\n\tlet messageString =\n\t\ttypeof message === \"number\" ? `0x${message.toString(16).padStart(3, \"0\")}` : message;\n\tskipInProduction(() => {\n\t\tif (debugMessageBuilder !== undefined) {\n\t\t\tmessageString = `${messageString}\\nDebug Message: ${debugMessageBuilder()}`;\n\t\t}\n\t\t// Using console.log instead of console.error or console.warn since the latter two may break downstream users.\n\t\tconsole.log(`Bug in Fluid Framework: Failed Assertion: ${messageString}`);\n\t});\n\tconst error = new Error(messageString);\n\tonAssertionError(error);\n\tthrow error;\n}\n\n/**\n * Throw an error with a constant message.\n * @remarks\n * Works like {@link assert}, but errors unconditionally instead of taking in a condition.\n *\n * Unlike `assert`, this `fail` is not \"tagged\" by the assert tagging too by default.\n * Use a `assertTagging.config.mjs` file to enable this and any other assert tagging customizations as needed.\n *\n * Returns `never` so it can be used inline as part of an expression, or as a return value.\n * @example\n * ```ts\n *  const x: number = numbersMap.get(\"foo\") ?? fail(\"foo missing from map\");\n * ```\n * @see {@link assert}\n * @internal\n */\nexport function fail(message: string | number, debugMessageBuilder?: () => string): never {\n\tfailPrivate(message, debugMessageBuilder);\n}\n\nfunction onAssertionError(error: Error): void {\n\tfor (const handler of firstChanceAssertionHandler) {\n\t\thandler(error);\n\t}\n}\n\nconst firstChanceAssertionHandler = new Set<(error: Error) => void>();\n\n/**\n * Add a callback which can be used to report an assertion before it is thrown.\n * @param handler - Called when an assertion occurs before the exception is thrown.\n * @returns a function to remove the handler.\n * @remarks\n * The callback runs just before the exception is thrown, which makes it a better place to report telemetry for Fluid Framework bugs than a catch block or an event like `window.onerror`.\n * Using this API to report telemetry is preferred over those approaches since it eliminates the risk of the exception being swallowed or obfuscated by an intermediate stack frame's catch block\n * or missed due to not having the right catch block or event handler.\n *\n * This does not replace the need for error handling elsewhere since errors (even bugs in Fluid) can cause other kinds of exceptions which this cannot run the callback for.\n * @example\n * ```ts\n * import { onAssertionFailure } from \"fluid-framework/alpha\";\n *\n * let firstAssertion: Error | undefined;\n *\n * onAssertionFailure((error: Error) => {\n * \tconst priorErrorNote =\n * \t\tfirstAssertion === undefined\n * \t\t\t? \"Please report this bug.\"\n * \t\t\t: `Might be caused due to prior error ${JSON.stringify(firstAssertion.message)} which should be investigated first.`;\n * \tconst message = `Encountered Bug in Fluid Framework: ${error.message}\\n${priorErrorNote}\\n${error.stack}`;\n * \tconsole.error(message);\n *\n * \tdebugger;\n * \tfirstAssertion ??= error;\n * });\n * ```\n * @alpha\n */\nexport function onAssertionFailure(handler: (error: Error) => void): () => void {\n\t// To avoid issues if the same callback is registered twice (mainly it not triggering twice and the first unregister removing it),\n\t// generate a wrapper around the handler.\n\tconst wrapper = (error: Error): void => {\n\t\thandler(error);\n\t};\n\tfirstChanceAssertionHandler.add(wrapper);\n\treturn () => {\n\t\tfirstChanceAssertionHandler.delete(wrapper);\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 * Enabled when {@link nonProductionConditionalsIncluded} is true.\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 * 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 enabled by default in debug builds: this introduces risk that code may behave differently when they are disabled or optimized out.\n * To mitigate this risk, these asserts can be disabled in debug builds by calling {@link configureDebugAsserts} or {@link emulateProductionBuild}.\n * This allows testing with the asserts both enabled and disabled to help ensure that code does not depend on them being enabled.\n *\n * Apps (or other performance sensitive scenarios) packaged in a way that does not {@link nonProductionConditionalsIncluded|skip non-production code}\n * can use the same approaches to disable these asserts to reduce performance overhead.\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 enabled helps ensure debugAsserts are effective at catching bugs during development and testing.\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\tconst error = new Error(`Debug assert failed: ${result.toString()}`);\n\t\t\t\tonAssertionError(error);\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t}\n\t});\n}\n\nlet debugAssertsEnabled = true;\n\n/**\n * Enables {@link debugAssert} validation.\n * @remarks\n * Throws if debugAsserts have been optimized out.\n *\n * Disabling debugAsserts has two main use cases:\n *\n * 1. Testing that the code behaves correctly in a more production like configuration.\n * 2. Reducing performance overhead.\n *\n * Disabling debugAsserts does not make everything production like: see {@link emulateProductionBuild} for a way to disable more non-production code.\n *\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 or by {@link emulateProductionBuild}: this checks if that has occurred.\n *\n * The non-production used by this library is annotated with `__PURE__` and `#__NO_SIDE_EFFECTS__` and has no return value and thus is removed by bundlers when optimizing based on these annotations.\n * Typically this means that such code is removed in production builds.\n * More details on these annotations can be found at {@link  https://github.com/javascript-compiler-hints/compiler-notations-spec/tree/main}.\n * @privateRemarks\n * See {@link skipInProductionInner}.\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 * Overrides the behavior code which optimizes out non-production conditional code like {@link debugAssert} and {@link nonProductionConditionalsIncluded}.\n *\n * Can be called multiple times. Will emulate production builds if called with `true` more times than `false`.\n * Emulation of production builds is disabled when enabled and disabled counts match (including at 0, by default).\n * It is an error to disable this more than it was enabled.\n *\n * @remarks\n * This is intended for testing that the code behaves correctly in production configurations.\n * Since tools like {@link debugAssert} typically add additional validation to help catch more bugs, tests should generally be run with such checks enabled (and thus emulateProductionBuild in its default disabled state).\n * However it is possible that some debugAsserts could accidentally change behavior and hide a bug.\n * This function provides a way to globally disable the debugAsserts so it is possible to run test suites in a production like mode without having to do a production bundling of them.\n *\n * To avoid introducing additional risk that code does production-specific logic using this setting, the actual setting is not exposed.\n * The intended use is that a pipeline could enable this before running the test suite (for example based on a CLI flag).\n * Such a run may have to also use some filtering to skip any tests which explicity check development only tooling, possibly via {@link nonProductionConditionalsIncluded} or some other mechanism like a test tag.\n *\n * @privateRemarks\n * See {@link skipInProduction}.\n *\n * This design, with a counter, was picked so that it's always safe for some scope to opt in when trying to test production behavior,\n * and it should be basically impossible to accidentally fail to test the production mode when trying to.\n * Some tests or test suites may want to run in production mode and they can use this API to opt in (via before and after hooks for example).\n * Additionally something might want to opt into production mode at some other level (for example test running the entire test suite again with production mode enabled).\n * In such setups, it's important that tests which were explicitly opting in don't accidentally disable production mode for the rest of the run when ending if something higher level enabled it.\n *\n * The approach taken with `configureDebugAsserts` is a bit more flexible, allowing both opt in and opt out, but also more error prone.\n * This API, `emulateProductionBuild` provides a more restrictive but less error prone option targeted at being a final defense for detecting cases where production mode causes issues.\n * It catches some cases `configureDebugAsserts` can't, like dependency on side effects of failing asserts debug message callback.\n * @internal\n */\nexport function emulateProductionBuild(enable = true): void {\n\temulateProductionBuildCount += enable ? 1 : -1;\n\tassert(\n\t\temulateProductionBuildCount >= 0,\n\t\t0xc70 /* emulateProductionBuild disabled more than it was enabled */,\n\t);\n}\n\nlet emulateProductionBuildCount = 0;\n\n/**\n * {@link skipInProductionInner}, except can be disabled by {@link emulateProductionBuild}.\n */\nfunction skipInProduction(conditional: () => void): void {\n\tskipInProductionInner(() => {\n\t\tif (emulateProductionBuildCount === 0) conditional();\n\t});\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 skipInProductionInner(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"]}
+{"version":3,"file":"assert.js","sourceRoot":"","sources":["../src/assert.ts"],"names":[],"mappings":"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","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 literal instead.\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 * @param debugMessageBuilder - An optional function that can be used to build a debug message to include in the error in development builds.\n * Only executed if `condition` is false. `debugMessageBuilder` is not executed in production builds, see `skipInProduction` for details.\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 {@link 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 `skipInProduction` reference above should be turned into a link.\n * @legacy @beta\n */\nexport function assert(\n\tcondition: boolean,\n\tmessage: string | number,\n\tdebugMessageBuilder?: () => string,\n): asserts condition {\n\tif (!condition) {\n\t\tfailPrivate(message, debugMessageBuilder);\n\t}\n}\n\n/**\n * {@link fail}'s implementation, but extracted to avoid assert tagging trying to tag the use of it in `assert`.\n */\nfunction failPrivate(message: string | number, debugMessageBuilder?: () => string): never {\n\tlet messageString =\n\t\ttypeof message === \"number\" ? `0x${message.toString(16).padStart(3, \"0\")}` : message;\n\tskipInProduction(() => {\n\t\tif (debugMessageBuilder !== undefined) {\n\t\t\tmessageString = `${messageString}\\nDebug Message: ${debugMessageBuilder()}`;\n\t\t}\n\t\t// Using console.log instead of console.error or console.warn since the latter two may break downstream users.\n\t\tconsole.log(`Bug in Fluid Framework: Failed Assertion: ${messageString}`);\n\t});\n\tconst error = new Error(messageString);\n\tonAssertionError(error);\n\tthrow error;\n}\n\n/**\n * Throw an error with a constant message.\n * @remarks\n * Works like {@link assert}, but errors unconditionally instead of taking in a condition.\n *\n * Unlike `assert`, this `fail` is not \"tagged\" by the assert tagging too by default.\n * Use a `assertTagging.config.mjs` file to enable this and any other assert tagging customizations as needed.\n *\n * Returns `never` so it can be used inline as part of an expression, or as a return value.\n * @example\n * ```ts\n *  const x: number = numbersMap.get(\"foo\") ?? fail(\"foo missing from map\");\n * ```\n * @see {@link assert}\n * @internal\n */\nexport function fail(message: string | number, debugMessageBuilder?: () => string): never {\n\tfailPrivate(message, debugMessageBuilder);\n}\n\nfunction onAssertionError(error: Error): void {\n\tfor (const handler of firstChanceAssertionHandler) {\n\t\thandler(error);\n\t}\n}\n\nconst firstChanceAssertionHandler = new Set<(error: Error) => void>();\n\n/**\n * Add a callback which can be used to report an assertion before it is thrown.\n * @param handler - Called when an assertion occurs before the exception is thrown.\n * @returns a function to remove the handler.\n * @remarks\n * The callback runs just before the exception is thrown, which makes it a better place to report telemetry for Fluid Framework bugs than a catch block or an event like `window.onerror`.\n * Using this API to report telemetry is preferred over those approaches since it eliminates the risk of the exception being swallowed or obfuscated by an intermediate stack frame's catch block\n * or missed due to not having the right catch block or event handler.\n *\n * This does not replace the need for error handling elsewhere since errors (even bugs in Fluid) can cause other kinds of exceptions which this cannot run the callback for.\n * @example\n * ```ts\n * import { onAssertionFailure } from \"fluid-framework/alpha\";\n *\n * let firstAssertion: Error | undefined;\n *\n * onAssertionFailure((error: Error) => {\n * \tconst priorErrorNote =\n * \t\tfirstAssertion === undefined\n * \t\t\t? \"Please report this bug.\"\n * \t\t\t: `Might be caused due to prior error ${JSON.stringify(firstAssertion.message)} which should be investigated first.`;\n * \tconst message = `Encountered Bug in Fluid Framework: ${error.message}\\n${priorErrorNote}\\n${error.stack}`;\n * \tconsole.error(message);\n *\n * \tdebugger;\n * \tfirstAssertion ??= error;\n * });\n * ```\n * @alpha\n */\nexport function onAssertionFailure(handler: (error: Error) => void): () => void {\n\t// To avoid issues if the same callback is registered twice (mainly it not triggering twice and the first unregister removing it),\n\t// generate a wrapper around the handler.\n\tconst wrapper = (error: Error): void => {\n\t\thandler(error);\n\t};\n\tfirstChanceAssertionHandler.add(wrapper);\n\treturn () => {\n\t\tfirstChanceAssertionHandler.delete(wrapper);\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 * Enabled when {@link nonProductionConditionalsIncluded} is true.\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 * 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 enabled by default in debug builds: this introduces risk that code may behave differently when they are disabled or optimized out.\n * To mitigate this risk, these asserts can be disabled in debug builds by calling {@link configureDebugAsserts} or {@link emulateProductionBuild}.\n * This allows testing with the asserts both enabled and disabled to help ensure that code does not depend on them being enabled.\n *\n * Apps (or other performance sensitive scenarios) packaged in a way that does not {@link nonProductionConditionalsIncluded|skip non-production code}\n * can use the same approaches to disable these asserts to reduce performance overhead.\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 enabled helps ensure debugAsserts are effective at catching bugs during development and testing.\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\tconst error = new Error(`Debug assert failed: ${result.toString()}`);\n\t\t\t\tonAssertionError(error);\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t}\n\t});\n}\n\nlet debugAssertsEnabled = true;\n\n/**\n * Enables {@link debugAssert} validation.\n * @remarks\n * Throws if debugAsserts have been optimized out.\n *\n * Disabling debugAsserts has two main use cases:\n *\n * 1. Testing that the code behaves correctly in a more production like configuration.\n * 2. Reducing performance overhead.\n *\n * Disabling debugAsserts does not make everything production like: see {@link emulateProductionBuild} for a way to disable more non-production code.\n *\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 or by {@link emulateProductionBuild}: this checks if that has occurred.\n *\n * The non-production used by this library is annotated with `__PURE__` and `#__NO_SIDE_EFFECTS__` and has no return value and thus is removed by bundlers when optimizing based on these annotations.\n * Typically this means that such code is removed in production builds.\n * More details on these annotations can be found at {@link  https://github.com/javascript-compiler-hints/compiler-notations-spec/tree/main}.\n * @privateRemarks\n * See {@link skipInProductionInner}.\n * @alpha\n */\nexport function nonProductionConditionalsIncluded(): boolean {\n\tlet included = false;\n\tskipInProduction(() => {\n\t\tincluded = true;\n\t});\n\treturn included;\n}\n\n/**\n * Overrides the behavior code which optimizes out non-production conditional code like {@link debugAssert} and {@link nonProductionConditionalsIncluded}.\n *\n * Can be called multiple times. Will emulate production builds if called with `true` more times than `false`.\n * Emulation of production builds is disabled when enabled and disabled counts match (including at 0, by default).\n * It is an error to disable this more than it was enabled.\n *\n * @remarks\n * This is intended for testing that the code behaves correctly in production configurations.\n * Since tools like {@link debugAssert} typically add additional validation to help catch more bugs, tests should generally be run with such checks enabled (and thus emulateProductionBuild in its default disabled state).\n * However it is possible that some debugAsserts could accidentally change behavior and hide a bug.\n * This function provides a way to globally disable the debugAsserts so it is possible to run test suites in a production like mode without having to do a production bundling of them.\n *\n * To avoid introducing additional risk that code does production-specific logic using this setting, the actual setting is not exposed.\n * The intended use is that a pipeline could enable this before running the test suite (for example based on a CLI flag).\n * Such a run may have to also use some filtering to skip any tests which explicity check development only tooling, possibly via {@link nonProductionConditionalsIncluded} or some other mechanism like a test tag.\n *\n * @privateRemarks\n * See {@link skipInProduction}.\n *\n * This design, with a counter, was picked so that it's always safe for some scope to opt in when trying to test production behavior,\n * and it should be basically impossible to accidentally fail to test the production mode when trying to.\n * Some tests or test suites may want to run in production mode and they can use this API to opt in (via before and after hooks for example).\n * Additionally something might want to opt into production mode at some other level (for example test running the entire test suite again with production mode enabled).\n * In such setups, it's important that tests which were explicitly opting in don't accidentally disable production mode for the rest of the run when ending if something higher level enabled it.\n *\n * The approach taken with `configureDebugAsserts` is a bit more flexible, allowing both opt in and opt out, but also more error prone.\n * This API, `emulateProductionBuild` provides a more restrictive but less error prone option targeted at being a final defense for detecting cases where production mode causes issues.\n * It catches some cases `configureDebugAsserts` can't, like dependency on side effects of failing asserts debug message callback.\n * @alpha\n */\nexport function emulateProductionBuild(enable = true): void {\n\temulateProductionBuildCount += enable ? 1 : -1;\n\tassert(\n\t\temulateProductionBuildCount >= 0,\n\t\t0xc70 /* emulateProductionBuild disabled more than it was enabled */,\n\t);\n}\n\nlet emulateProductionBuildCount = 0;\n\n/**\n * {@link skipInProductionInner}, except can be disabled by {@link emulateProductionBuild}.\n */\nfunction skipInProduction(conditional: () => void): void {\n\tskipInProductionInner(() => {\n\t\tif (emulateProductionBuildCount === 0) conditional();\n\t});\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 skipInProductionInner(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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/core-utils",
-  "version": "2.81.1",
+  "version": "2.82.0",
   "description": "Not intended for use outside the Fluid client repo.",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -23,6 +23,16 @@
         "default": "./dist/index.js"
       }
     },
+    "./alpha": {
+      "import": {
+        "types": "./lib/alpha.d.ts",
+        "default": "./lib/index.js"
+      },
+      "require": {
+        "types": "./dist/alpha.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
     "./legacy": {
       "import": {
         "types": "./lib/legacy.d.ts",
@@ -69,16 +79,16 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.2",
     "@biomejs/biome": "~1.9.3",
-    "@fluid-internal/mocha-test-setup": "~2.81.1",
+    "@fluid-internal/mocha-test-setup": "~2.82.0",
     "@fluid-tools/benchmark": "^0.52.0",
     "@fluid-tools/build-cli": "^0.63.0",
     "@fluidframework/build-common": "^2.0.3",
     "@fluidframework/build-tools": "^0.63.0",
     "@fluidframework/core-utils-previous": "npm:@fluidframework/core-utils@2.81.0",
-    "@fluidframework/eslint-config-fluid": "~2.81.1",
+    "@fluidframework/eslint-config-fluid": "~2.82.0",
     "@microsoft/api-extractor": "7.52.11",
     "@types/mocha": "^10.0.10",
-    "@types/node": "^18.19.0",
+    "@types/node": "~20.19.30",
     "@types/sinon": "^17.0.3",
     "c8": "^10.1.3",
     "concurrently": "^9.2.1",
@@ -118,8 +128,10 @@
     "check:biome": "biome check .",
     "check:exports": "concurrently \"npm:check:exports:*\"",
     "check:exports:bundle-release-tags": "api-extractor run --config api-extractor/api-extractor-lint-bundle.json",
+    "check:exports:cjs:alpha": "api-extractor run --config api-extractor/api-extractor-lint-alpha.cjs.json",
     "check:exports:cjs:legacy": "api-extractor run --config api-extractor/api-extractor-lint-legacy.cjs.json",
     "check:exports:cjs:public": "api-extractor run --config api-extractor/api-extractor-lint-public.cjs.json",
+    "check:exports:esm:alpha": "api-extractor run --config api-extractor/api-extractor-lint-alpha.esm.json",
     "check:exports:esm:legacy": "api-extractor run --config api-extractor/api-extractor-lint-legacy.esm.json",
     "check:exports:esm:public": "api-extractor run --config api-extractor/api-extractor-lint-public.esm.json",
     "check:format": "npm run check:biome",

package/src/assert.ts

@@ -215,7 +215,7 @@ export function configureDebugAsserts(enabled: boolean): boolean {
  * More details on these annotations can be found at {@link  https://github.com/javascript-compiler-hints/compiler-notations-spec/tree/main}.
  * @privateRemarks
  * See {@link skipInProductionInner}.
- * @internal
+ * @alpha
  */
 export function nonProductionConditionalsIncluded(): boolean {
 	let included = false;
@@ -254,7 +254,7 @@ export function nonProductionConditionalsIncluded(): boolean {
  * The approach taken with `configureDebugAsserts` is a bit more flexible, allowing both opt in and opt out, but also more error prone.
  * This API, `emulateProductionBuild` provides a more restrictive but less error prone option targeted at being a final defense for detecting cases where production mode causes issues.
  * It catches some cases `configureDebugAsserts` can't, like dependency on side effects of failing asserts debug message callback.
- * @internal
+ * @alpha
  */
 export function emulateProductionBuild(enable = true): void {
 	emulateProductionBuildCount += enable ? 1 : -1;

package/biome.jsonc

@@ -1,4 +0,0 @@
-{
-	"$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
-	"extends": ["../../../biome.jsonc"]
-}