API documentation of Agoric SDK / Exports / @agoric/assert / types
Module: types
Table of contents
Interfaces
Type Aliases
- Assert
- AssertEqual
- AssertFail
- AssertMakeError
- AssertNote
- AssertQuote
- AssertString
- AssertTypeof
- AssertTypeofBigint
- AssertTypeofBoolean
- AssertTypeofFunction
- AssertTypeofNumber
- AssertTypeofObject
- AssertTypeofString
- AssertTypeofSymbol
- AssertTypeofUndefined
- BaseAssert
- Details
- DetailsTag
- DetailsToken
- FailTag
- MakeAssert
- Raise
Type Aliases
Assert
Ƭ Assert: BaseAssert & { Fail: FailTag ; bare: AssertQuote ; details: DetailsTag ; equal: AssertEqual ; error: AssertMakeError ; fail: AssertFail ; makeAssert: MakeAssert ; note: AssertNote ; quote: AssertQuote ; string: AssertString ; typeof: AssertTypeof }
Defined in
AssertEqual
Ƭ AssertEqual: (actual: any, expected: any, optDetails?: Details, ErrorConstructor?: ErrorConstructor) => void
The assert.equal method
Assert that two values must be Object.is.
Type declaration
▸ (actual, expected, optDetails?, ErrorConstructor?): void
Parameters
| Name | Type | Description |
|---|---|---|
actual | any | The value we received |
expected | any | What we wanted |
optDetails? | Details | The details to throw |
ErrorConstructor? | ErrorConstructor | An optional alternate error constructor to use. |
Returns
void
Defined in
AssertFail
Ƭ AssertFail: (optDetails?: Details, ErrorConstructor?: ErrorConstructor) => never
The assert.fail method.
Fail an assertion, recording full details to the console and raising an exception with a message in which details substitution values have been masked.
The optional optDetails can be a string for backwards compatibility with the nodejs assertion library.
Type declaration
▸ (optDetails?, ErrorConstructor?): never
Parameters
| Name | Type | Description |
|---|---|---|
optDetails? | Details | The details of what was asserted |
ErrorConstructor? | ErrorConstructor | An optional alternate error constructor to use. |
Returns
never
Defined in
AssertMakeError
Ƭ AssertMakeError: (optDetails?: Details, ErrorConstructor?: ErrorConstructor, options?: AssertMakeErrorOptions) => Error
The makeError function, recording details for the console.
The optional optDetails can be a string.
Type declaration
▸ (optDetails?, ErrorConstructor?, options?): Error
Parameters
| Name | Type | Description |
|---|---|---|
optDetails? | Details | The details of what was asserted |
ErrorConstructor? | ErrorConstructor | An optional alternate error constructor to use. |
options? | AssertMakeErrorOptions | - |
Returns
Error
Defined in
AssertNote
Ƭ AssertNote: (error: Error, detailsNote: Details) => void
The errorNote function.
Annotate an error with details, potentially to be used by an augmented console such as the causal console of console.js, to provide extra information associated with logged errors.
Type declaration
▸ (error, detailsNote): void
Parameters
| Name | Type |
|---|---|
error | Error |
detailsNote | Details |
Returns
void
Defined in
AssertQuote
Ƭ AssertQuote: (payload: any, spaces?: string | number) => StringablePayload
Type declaration
▸ (payload, spaces?): StringablePayload
Parameters
| Name | Type | Description |
|---|---|---|
payload | any | What to declassify |
spaces? | string | number | - |
Returns
Defined in
AssertString
Ƭ AssertString: (specimen: any, optDetails?: Details) => asserts specimen is string
The assert.string method.
assert.string(v) is equivalent to assert.typeof(v, 'string'). We special case this one because it is the most frequently used.
Assert an expected typeof result.
Type declaration
▸ (specimen, optDetails?): asserts specimen is string
Parameters
| Name | Type | Description |
|---|---|---|
specimen | any | The value to get the typeof |
optDetails? | Details | The details to throw |
Returns
asserts specimen is string
Defined in
AssertTypeof
Ƭ AssertTypeof: AssertTypeofBigint & AssertTypeofBoolean & AssertTypeofFunction & AssertTypeofNumber & AssertTypeofObject & AssertTypeofString & AssertTypeofSymbol & AssertTypeofUndefined
Defined in
AssertTypeofBigint
Ƭ AssertTypeofBigint: (specimen: any, typename: "bigint", optDetails?: Details) => asserts specimen is bigint
Type declaration
▸ (specimen, typename, optDetails?): asserts specimen is bigint
Parameters
| Name | Type |
|---|---|
specimen | any |
typename | "bigint" |
optDetails? | Details |
Returns
asserts specimen is bigint
Defined in
AssertTypeofBoolean
Ƭ AssertTypeofBoolean: (specimen: any, typename: "boolean", optDetails?: Details) => asserts specimen is boolean
Type declaration
▸ (specimen, typename, optDetails?): asserts specimen is boolean
Parameters
| Name | Type |
|---|---|
specimen | any |
typename | "boolean" |
optDetails? | Details |
Returns
asserts specimen is boolean
Defined in
AssertTypeofFunction
Ƭ AssertTypeofFunction: (specimen: any, typename: "function", optDetails?: Details) => asserts specimen is Function
Type declaration
▸ (specimen, typename, optDetails?): asserts specimen is Function
Parameters
| Name | Type |
|---|---|
specimen | any |
typename | "function" |
optDetails? | Details |
Returns
asserts specimen is Function
Defined in
AssertTypeofNumber
Ƭ AssertTypeofNumber: (specimen: any, typename: "number", optDetails?: Details) => asserts specimen is number
Type declaration
▸ (specimen, typename, optDetails?): asserts specimen is number
Parameters
| Name | Type |
|---|---|
specimen | any |
typename | "number" |
optDetails? | Details |
Returns
asserts specimen is number
Defined in
AssertTypeofObject
Ƭ AssertTypeofObject: (specimen: any, typename: "object", optDetails?: Details) => asserts specimen is Record<any, any> | null
Type declaration
▸ (specimen, typename, optDetails?): asserts specimen is Record<any, any> | null
Parameters
| Name | Type |
|---|---|
specimen | any |
typename | "object" |
optDetails? | Details |
Returns
asserts specimen is Record<any, any> | null
Defined in
AssertTypeofString
Ƭ AssertTypeofString: (specimen: any, typename: "string", optDetails?: Details) => asserts specimen is string
Type declaration
▸ (specimen, typename, optDetails?): asserts specimen is string
Parameters
| Name | Type |
|---|---|
specimen | any |
typename | "string" |
optDetails? | Details |
Returns
asserts specimen is string
Defined in
AssertTypeofSymbol
Ƭ AssertTypeofSymbol: (specimen: any, typename: "symbol", optDetails?: Details) => asserts specimen is symbol
Type declaration
▸ (specimen, typename, optDetails?): asserts specimen is symbol
Parameters
| Name | Type |
|---|---|
specimen | any |
typename | "symbol" |
optDetails? | Details |
Returns
asserts specimen is symbol
Defined in
AssertTypeofUndefined
Ƭ AssertTypeofUndefined: (specimen: any, typename: "undefined", optDetails?: Details) => asserts specimen is undefined
Type declaration
▸ (specimen, typename, optDetails?): asserts specimen is undefined
Parameters
| Name | Type |
|---|---|
specimen | any |
typename | "undefined" |
optDetails? | Details |
Returns
asserts specimen is undefined
Defined in
BaseAssert
Ƭ BaseAssert: (flag: any, optDetails?: Details, ErrorConstructor?: ErrorConstructor) => asserts flag
The assert function itself.
Type declaration
▸ (flag, optDetails?, ErrorConstructor?): asserts flag
Parameters
| Name | Type | Description |
|---|---|---|
flag | any | The truthy/falsy value |
optDetails? | Details | The details to throw |
ErrorConstructor? | ErrorConstructor | An optional alternate error constructor to use. |
Returns
asserts flag
Defined in
Details
Ƭ Details: string | DetailsToken
Either a plain string, or made by the details template literal tag.
Defined in
DetailsTag
Ƭ DetailsTag: (template: TemplateStringsArray | string[], ...args: any) => DetailsToken
Use the details function as a template literal tag to create informative error messages. The assertion functions take such messages as optional arguments:
assert(sky.isBlue(), details`${sky.color} should be "blue"`);or following the normal convention to locally rename details to X and quote to q like const { details: X, quote: q } = assert;:
assert(sky.isBlue(), X`${sky.color} should be "blue"`);However, note that in most cases it is preferable to instead use the Fail template literal tag (which has the same input signature as details but automatically creates and throws an error):
sky.isBlue() || Fail`${sky.color} should be "blue"`;The details template tag returns a DetailsToken object that can print itself with the formatted message in two ways. It will report full details to the console, but mask embedded substitution values with their typeof information in the thrown error to prevent revealing secrets up the exceptional path. In the example above, the thrown error may reveal only that sky.color is a string, whereas the same diagnostic printed to the console reveals that the sky was green. This masking can be disabled for an individual substitution value using quote.
The raw property of an input template array is ignored, so a simple array of strings may be provided directly.
Type declaration
▸ (template, ...args): DetailsToken
Parameters
| Name | Type |
|---|---|
template | TemplateStringsArray | string[] |
...args | any |
Returns
Defined in
DetailsToken
Ƭ DetailsToken: Object
A call to the details template literal makes and returns a fresh details token, which is a frozen empty object associated with the arguments of that details template literal expression.
Defined in
FailTag
Ƭ FailTag: (template: TemplateStringsArray | string[], ...args: any) => never
Use the Fail function as a template literal tag to efficiently create and throw a details-style error only when a condition is not satisfied.
condition || Fail`...complaint...`;This avoids the overhead of creating usually-unnecessary errors like
assert(condition, details`...complaint...`);while improving readability over alternatives like
condition || assert.fail(details`...complaint...`);However, due to current weakness in TypeScript, static reasoning is less powerful with the || patterns than with an assert call. Until/unless https://github.com/microsoft/TypeScript/issues/51426 is fixed, for ||-style assertions where this loss of static reasoning is a problem, instead express the assertion as
if (!condition) {
Fail`...complaint...`;
}or, if needed,
if (!condition) {
// `throw` is noop since `Fail` throws, but it improves static analysis
throw Fail`...complaint...`;
}Type declaration
▸ (template, ...args): never
Parameters
| Name | Type |
|---|---|
template | TemplateStringsArray | string[] |
...args | any |
Returns
never
Defined in
MakeAssert
Ƭ MakeAssert: (optRaise?: Raise, unredacted?: boolean) => Assert
Makes and returns an assert function object that shares the bookkeeping state defined by this module with other assert function objects made by makeAssert. This state is per-module-instance and is exposed by the loggedErrorHandler above. We refer to assert as a "function object" because it can be called directly as a function, but also has methods that can be called.
If optRaise is provided, the returned assert function object will call optRaise(reason) before throwing the error. This enables optRaise to engage in even more violent termination behavior, like terminating the vat, that prevents execution from reaching the following throw. However, if optRaise returns normally, which would be unusual, the throw following optRaise(reason) would still happen.
Type declaration
▸ (optRaise?, unredacted?): Assert
Parameters
| Name | Type |
|---|---|
optRaise? | Raise |
unredacted? | boolean |
Returns
Defined in
Raise
Ƭ Raise: (reason: Error) => any
To make an assert which terminates some larger unit of computation like a transaction, vat, or process, call makeAssert with a Raise callback, where that callback actually performs that larger termination. If possible, the callback should also report its reason parameter as the alleged reason for the termination.
Type declaration
▸ (reason): any
Parameters
| Name | Type |
|---|---|
reason | Error |
Returns
any