@xylabs/assert

Base functionality used throughout XY Labs TypeScript/JavaScript libraries

Reference

@xylabs/assert

Functions

| Function | Description | | ------ | ------ | | assertDefinedEx | Implementation of assertDefinedEx that handles all overloads. | | assertEx | Implementation of assertEx that handles all overloads. |

functions

assertDefinedEx

@xylabs/assert

Implementation of assertDefinedEx that handles all overloads.

Call Signature

function assertDefinedEx<T>(expr: T | undefined, messageFunc?: AssertExMessageFunc<T>): T;

Asserts that a value is defined (not undefined) and returns the value. Throws an error if the value is undefined.

Type Parameters

| Type Parameter | Description | | ------ | ------ | | T | The type of value to check |

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | expr | T | undefined | Expression to be evaluated for being defined | | messageFunc? | AssertExMessageFunc<T> | Function that returns a message for the error if expression is undefined |

Returns

T

The value of the expression (guaranteed to be defined)

Throws

Error with the message returned by messageFunc

Example

// Simple usage with a message function
const value = assertDefinedEx(possiblyUndefined, () => 'Value must be defined')

// Using with type narrowing
const config: Config | undefined = loadConfig()
const safeConfig = assertDefinedEx(config, () => 'Config failed to load')
// safeConfig is now type Config (not Config | undefined)

Call Signature

function assertDefinedEx<T, R>(expr: T | undefined, errorFunc?: AssertExErrorFunc<T, R>): T;

Asserts that a value is defined (not undefined) and returns the value. Throws a custom error if the value is undefined.

Type Parameters

| Type Parameter | Description | | ------ | ------ | | T | The type of value to check | | R extends Error | The type of error to throw |

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | expr | T | undefined | Expression to be evaluated for being defined | | errorFunc? | AssertExErrorFunc<T, R> | Function that returns a custom error instance if expression is undefined |

Returns

T

The value of the expression (guaranteed to be defined)

Throws

Custom error returned by errorFunc

Example

// Using with a custom error
const user = assertDefinedEx(getUser(), () => new UserNotFoundError('User not found'))

assertEx

@xylabs/assert

Implementation of assertEx that handles all overloads.

Call Signature

function assertEx<T>(expr: T | null | undefined, messageFunc?: AssertExMessageFunc<T>): T;

Asserts that an expression is truthy and returns the value. Throws an error if the expression is falsy.

Type Parameters

| Type Parameter | Description | | ------ | ------ | | T | The type of value to check |

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | expr | T | null | undefined | Expression to be evaluated for truthiness | | messageFunc? | AssertExMessageFunc<T> | Function that returns a message for the error if expression is falsy |

Returns

T

The value of the expression (guaranteed to be truthy)

Throws

Error with the message returned by messageFunc

Example

// Simple usage with a message function
const value = assertEx(possiblyFalsy, () => 'Value must be truthy')

// Using with type narrowing
const config: Config | null = loadConfig()
const safeConfig = assertEx(config, () => 'Config failed to load')
// safeConfig is now type Config (not Config | null)

Call Signature

function assertEx<T, R>(expr: T | null | undefined, errorFunc?: AssertExErrorFunc<T, R>): T;

Asserts that an expression is truthy and returns the value. Throws a custom error if the expression is falsy.

Type Parameters

| Type Parameter | Description | | ------ | ------ | | T | The type of value to check | | R extends Error | The type of error to throw |

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | expr | T | null | undefined | Expression to be evaluated for truthiness | | errorFunc? | AssertExErrorFunc<T, R> | Function that returns a custom error instance if expression is falsy |

Returns

T

The value of the expression (guaranteed to be truthy)

Throws

Custom error returned by errorFunc

Example

// Using with a custom error
const user = assertEx(getUser(), () => new UserNotFoundError('User not found'))

Part of sdk-js

Maintainers

• Arie Trouw (arietrouw.com)
• Matt Jones
• Joel Carter
• Jordan Trouw

License

See the LICENSE file for license details

Credits

Made with 🔥 and ❄️ by XYLabs