Package Exports

@tsxo/assure
@tsxo/assure/dist/cjs/index.js
@tsxo/assure/dist/esm/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@tsxo/assure) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@tsxo/assure

A very simple, lightweight, type-safe assertion library for JavaScript and TypeScript.

npm

Features

Type Safety - Full TypeScript support.
Type Narrows - Ability to narrow types via assert.
Small and Fast - Minimal overhead for your projects.
ESM and CJS - Seamlessly supports both ECMAScript Modules (ESM) and CommonJS (CJS) for flexibility across modern and legacy projects.
Tree-Shaking Ready - Designed with tree-shaking in mind to optimize application size.

Installation

npm install @tsxo/assure

Quick Start

The library provides a simple API for asserting conditions and throwing meaningful errors when conditions fail.

import { assert } from "@tsxo/assure";

type MyType = "a" | "b";

function act(v: MyType | undefined) {
    assert(v); // v is now narrowed to MyType
}

API Reference

Base Assertion

`assert(value: unknown, msg?: string): asserts value`

The core assertion function that checks if a value is truthy. Will type narrow.

assert(someValue, "Value must be truthy");

Equality Assertions

`assert_eq<T>(l: T, r: T, msg?: string): void`

Asserts that two values are strictly equal.

assert_eq(5, 5); // passes
assert_eq("hello", "hello"); // passes
assert_eq(5, 6); // throws error

`assert_ne<T>(l: T, r: T, msg?: string): void`

Asserts that two values are not strictly equal.

assert_ne(5, 6); // passes
assert_ne("hello", "world"); // passes
assert_ne(5, 5); // throws error

Ordering Assertions

`assert_gt<T extends Ordered>(l: T, r: T, msg?: string): void`

Asserts that the left value is greater than the right value.

assert_gt(5, 3); // passes
assert_gt(3, 5); // throws error

`assert_lt<T extends Ordered>(l: T, r: T, msg?: string): void`

Asserts that the left value is less than the right value.

assert_lt(3, 5); // passes
assert_lt(5, 3); // throws error

`assert_gte<T extends Ordered>(l: T, r: T, msg?: string): void`

Asserts that the left value is greater than or equal to the right value.

assert_gte(5, 3); // passes
assert_gte(5, 5); // passes
assert_gte(3, 5); // throws error

`assert_lte<T extends Ordered>(l: T, r: T, msg?: string): void`

Asserts that the left value is less than or equal to the right value.

assert_lte(3, 5); // passes
assert_lte(5, 5); // passes
assert_lte(5, 3); // throws error

Error Messages

All assertion functions accept an optional message parameter that will be included in the error when the assertion fails:

assert_eq(5, 6, "Numbers must be equal"); // throws "Assertion Error: Numbers must be equal"

Acknowledgments

This project draws inspiration from several excellent assertion libraries:

Node.js Assert - The built-in Node.js assertion module
tiny-invariant - A tiny invariant function.
claims - Additional assertion macros for testing in Rust applications.

License

MIT License - fork, modify and use however you want.