@xylabs/assert

@xylabs/assert

Base functionality used throughout XY Labs TypeScript/JavaScript libraries

Install

Using npm:

npm install {{name}}

Using yarn:

yarn add {{name}}

Using pnpm:

pnpm add {{name}}

Using bun:

bun add {{name}}

License

See the LICENSE file for license rights and limitations (LGPL-3.0-only).

Reference

packages

assert

### .temp-typedoc

  ### functions

    ### <a id="assertDefinedEx"></a>assertDefinedEx

@xylabs/assert

Implementation of assertDefinedEx that handles all overloads.

Call Signature

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

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

Type Parameters

T

T

The type of value to check

Parameters

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, errorFunc?): T;

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

Type Parameters

T

T

The type of value to check

R

R extends Error

The type of error to throw

Parameters

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'))

    ### <a id="assertEx"></a>assertEx

@xylabs/assert

Implementation of assertEx that handles all overloads.

Call Signature

function assertEx<T>(expr, messageFunc?): T;

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

Type Parameters

T

T

The type of value to check

Parameters

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, errorFunc?): T;

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

Type Parameters

T

T

The type of value to check

R

R extends Error

The type of error to throw

Parameters

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'))