@lightbase/utils

Various utilities, some lodash like, some to aid with strict TypeScript. Also includes
various type utilities.

Utilities

This library exports the utility functions in the following groups:

Assertion functions

Type-narrowing assertions, that throw when the provided value is falsy. This uses
TypeScript assert operator.

$3

Asserts that the provided value is null or undefined. Else throws the provided error.

$3

Asserts that the provided value is not null or undefined. Else throws the provided
error.

'Is' functions

Type-narrowing functions, returning truthy when the value is of the corresponding type.
These can be used to constrain type in if-else branches.

$3

Returns true when the provided value is null or undefined.

$3

Returns true when the provided value is an object-like.

$3

Returns true when the provided value is an object-like and has the provided keys.

Invariants

Generic assertion functions that don't type-narrow. Can be used to create
business-specific validation functions to align business logic and related error return
types.

> [!INFO]
>
> If at some point TypeScript supports creating assertion functions via a generic
> function, without manually typing the resulting assertion, this system will be applied
> to asserts as well.

$3

Create an invariant function to execute business rules. Various options are supported:

- A predicate callback which is executed to determine if an invariant fails
- Various options for error customization:
- Static error messages.
- Customizable error messages on invariant invocation.
- A custom error constructor, function or static method with typed arguments on
invariant invocation.
- Partial application of the provided custom error.

Types

This library exports the following utility types:

$3

Force TypeScript to resolve the result of computed types. Can be used to improve the
readability in Quick-documentation popups and errors.

$3

Represent a value which may be wrapped in a Promise or Array respectively.

$3

Extract the type wrapped in a MaybePromise or MaybeArray respectively.

$3

Brand types, so a general type like string is not assignable to a business constrainted
type like 'email' without going through an explicit cast. See the
Zod docs or the
Total TypeScript article
on this subject.

$3

Like Pick and Omit, but instead of specifying keys, specify the type of value that
should be picked or omitted.

$3

Map union types to an intersection type.

$3

Extract the parameter types from class constructors or functions.

Node.js

This package has a specific @encapsula/util/node export providing the following
utilities

$3

Wrapper around
AsyncLocalStorage,
for read-only AsyncLocalStorage use. The main difference is the explicit get and
getOptional functions that wrap AsyncLocalStorage#getStore. get`, throws an error
when not in the async-context of a store.