Skip to main content

@fluidframework/core-utils Package

Interfaces​

Interface Alerts Description
PromiseCacheOptions Legacy Options for configuring the PromiseCache

Classes​

Class Alerts Description
Deferred Legacy A deferred creates a promise and the ability to resolve or reject it
LazyPromise Legacy A lazy evaluated promise. The execute function is delayed until the promise is used, e.g. await, then, catch ... The execute function is only called once. All calls are then proxied to the promise returned by the execute method.
PromiseCache Legacy A specialized cache for async work, allowing you to safely cache the promised result of some async work without fear of running it multiple times or losing track of errors.

Types​

TypeAlias Alerts Description
PromiseCacheExpiry Legacy Three supported expiry policies: - indefinite: entries don't expire and must be explicitly removed - absolute: entries expire after the given duration in MS, even if accessed multiple times in the mean time - sliding: entries expire after the given duration in MS of inactivity (i.e. get resets the clock)

Functions​

Function Alerts Return Type Description
assert(condition, message) Legacy asserts condition Asserts the specified condition.
compareArrays(left, right, comparator) Legacy boolean Compare two arrays. Returns true if their elements are equivalent and in the same order.
onAssertionFailure(handler) Alpha () => void Add a callback which can be used to report an assertion before it is thrown.

Function Details​

assert​

Asserts the specified condition.

This API is provided for existing users, but is not recommended for new users.

To use, import via @fluidframework/core-utils/legacy.

For more information about our API support guarantees, see here.

Signature​

export declare function assert(condition: boolean, message: string | number): asserts condition;

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.

Parameters​

Parameter Type Description
condition boolean 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.
message string | number 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.

Returns​

Return type: asserts condition

compareArrays​

Compare two arrays. Returns true if their elements are equivalent and in the same order.

This API is provided for existing users, but is not recommended for new users.

To use, import via @fluidframework/core-utils/legacy.

For more information about our API support guarantees, see here.

Signature​

compareArrays: <T>(left: readonly T[], right: readonly T[], comparator?: (leftItem: T, rightItem: T, index: number) => boolean) => boolean
Type Parameters​
Parameter Description
T

Parameters​

Parameter Modifiers Type Description
left readonly T[] The first array to compare
right readonly T[] The second array to compare
comparator optional (leftItem: T, rightItem: T, index: number) => boolean The function used to check if two Ts are equivalent. Defaults to Object.is() equality (a shallow compare where NaN = NaN and -0 ≠ 0)

Returns​

Return type: boolean

onAssertionFailure​

Add a callback which can be used to report an assertion before it is thrown.

This API is provided as an alpha preview and may change without notice.

To use, import via @fluidframework/core-utils/alpha.

For more information about our API support guarantees, see here.

Signature​

export declare function onAssertionFailure(handler: (error: Error) => void): () => void;

Remarks​

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. 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 or missed due to not having the right catch block or event handler.

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.

Example​

import { onAssertionFailure } from "fluid-framework/alpha";
let firstAssertion: Error | undefined;
onAssertionFailure((error: Error) => {
	const priorErrorNote =
		firstAssertion === undefined
			? "Please report this bug."
			: `Might be caused due to prior error ${JSON.stringify(firstAssertion.message)} which should be investigated first.`;
	const message = `Encountered Bug in Fluid Framework: ${error.message}\n${priorErrorNote}\n${error.stack}`;
	console.error(message);
	debugger;
	firstAssertion ??= error;
});

Parameters​

Parameter Type Description
handler (error: Error) => void Called when an assertion occurs before the exception is thrown.

Returns​

a function to remove the handler.

Return type: () => void