[![logo][]](https://xylabs.com)

# @xylabs/assert

[![npm][npm-badge]][npm-link]
[![license][license-badge]][license-link]

> Base functionality used throughout XY Labs TypeScript/JavaScript libraries

## Install

Using npm:

```sh
npm install {{name}}
```

Using yarn:

```sh
yarn add {{name}}
```

Using pnpm:

```sh
pnpm add {{name}}
```

Using bun:

```sh
bun add {{name}}
```


## License

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

## Reference

### packages

  ### assert

    ### .temp-typedoc

      ### functions

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

[**@xylabs/assert**](#../README)

***

Implementation of assertDefinedEx that handles all overloads.

## Call Signature

```ts
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

```typescript
// 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

```ts
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

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

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

[**@xylabs/assert**](#../README)

***

Implementation of assertEx that handles all overloads.

## Call Signature

```ts
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

```typescript
// 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

```ts
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

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

## Credits

[Made with 🔥 and ❄️ by XY Labs](https://xylabs.com)

[npm-badge]: https://img.shields.io/npm/v/@xylabs/assert.svg
[npm-link]: https://www.npmjs.com/package/@xylabs/assert
[license-badge]: https://img.shields.io/npm/l/@xylabs/assert.svg
[license-link]: https://github.com/xylabs/sdk-js/blob/main/LICENSE
[logo]: https://cdn.xy.company/img/brand/XYPersistentCompany_Logo_Icon_Colored.svg