Interface AssertionUtilities

Wrap a string such that its use as a substitution value in a template literal tagged with details or Fail will be treated literally rather than being quoted or redacted.

To avoid injection attacks that exploit quoting confusion, this must NEVER be used with data that is possibly attacker-controlled.

As a further safeguard, we fall back to quoting any input that is not a string of sufficiently word-like parts separated by isolated spaces (rather than throwing an exception, which could hide the original problem for which explanatory details are being constructed---i.e., assert.details`...` should never be the source of a new exception, nor should an attempt to render its output, although we could instead decide to handle the latter by inline replacement similar to that of bestEffortStringify for producing rendered messages like (an object) was tagged "[Unsafe bare string]").

Use as a template literal tag to create an opaque DetailsToken for use with other assertion functions that might redact unquoted substitution values (i.e., those that are not output from the quote function) into lossy typeof output but still preserve them for logging to an associated console.

The normal convention is to locally rename details to X like const { details: X, quote: q, Fail } = assert;. However, note that in most cases it is preferable to instead use the Fail template literal tag (which has the same input signature but automatically creates and throws an error):

sky.isBlue() || Fail`${sky.color} should be "blue"`;
Copy

The raw property of an input template array is ignored, so a simple array of strings may be provided directly.

Use as a template literal tag to create and throw an error in whose message unquoted substitution values (i.e., those that are not output from the quote function) may have been redacted into lossy typeof output but are still available for logging to an associated console.

For example, using the normal convention to locally rename properties like const { quote: q, Fail } = assert;:

sky.isBlue() || Fail`${sky.color} should be "blue"`;
Copy

This || pattern saves the cost of creating DetailsToken and/or error instances when the asserted condition holds, but can weaken TypeScript static reasoning due to https://github.com/microsoft/TypeScript/issues/51426 . Where this is a problem, instead express the assertion as

if (!sky.isBlue()) {
  // This `throw` does not affect runtime behavior since `Fail` throws, but
  // might be needed to improve static analysis.
  throw Fail`${sky.color} should be "blue"`;
}
Copy

The raw property of an input template array is ignored, so a simple array of strings may be provided directly.

Create an error with a message in which unquoted details substitution values may have been redacted into lossy typeof output but are still available for logging to an associated console.

Associate details with error, potentially to be logged by an associated console for providing extra information about the error.

Wrap a value such that its use as a substitution value in a template literal tagged with details or Fail will result in it appearing quoted (in a way similar to but more general than JSON.stringify) rather than redacted in the message of errors based on the resulting DetailsToken.

This does not affect representation in output of an associated console, which still logs the value as it would without quote, but does reveal it to functions in the propagation path of such errors.

For example, the following will reveal the expected value in the thrown error's message, but only the type of the actual incorrect value (using the normal convention to locally rename properties like const { quote: q, Fail } = assert;):

actual === expected || Fail`${actual} should be ${q(expected)}`;
Copy

The optional space parameter matches that of JSON.stringify, and is used to request insertion of non-semantic line feeds, indentation, and separating spaces in the output for improving readability of objects and arrays.