# assert-ts
> Invariant and non-null/undefined assertion check with type guards
Latest version **0.3.4** (published 2021-09-30) · ISC license · 0 weekly downloads
## Install
```sh
npm install assert-ts
pnpm add assert-ts
yarn add assert-ts
bun add assert-ts
```
## Health
**Score 25/100 (F)** — status: abandoned.
Positive: has types; no vulnerabilities; high quality score.
Warnings: low downloads; no esm support; pre 1.0.
Negative: abandoned; low maintenance score.
## Facts
| | |
|---|---|
| Version | 0.3.4 |
| Published | 2021-09-30 |
| First published | 2019-09-14 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 14.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 10 |
| Author | Bjørn Egil Hansen |
| Maintainers | bjorn_egil |
| Keywords | assert, invariant, precondition, guard, assume, null-check, type guard, flow typing |
## Links
- npm: https://www.npmjs.com/package/assert-ts
- Repository: https://github.com/fram-x/assert-ts
- Homepage: https://github.com/fram-x/assert-ts#readme
- Issues: https://github.com/fram-x/assert-ts/issues
- npm.io page: https://npm.io/package/assert-ts
## Recent versions
- 0.3.4 (latest) — 2021-09-30
- 0.3.3 — 2021-04-24
- 0.3.2 — 2021-02-23
- 0.3.1 — 2021-02-07
- 0.3.0 — 2020-12-06
- 0.2.2 — 2020-11-02
- 0.1.0 — 2019-09-14
- 0.0.1 — 2019-09-14
## README
# assert-ts
Invariant and non-null/undefined assertions, both
- _strict_, i.e. logs error and throws exception, and
- _soft_, i.e. just logs a warning.
Both strict and soft will narrow type, i.e. eliminate `null` or `undefined`.
## Introduction
The purpose of this library is to make assumptions explicit, rather than just a comment or even worse just a thought while writing your code. This applies both to assumptions about conditions to be met or values not being null/undefined.
## Installation
To install the library into your project, run yarn or npm:
`yarn add assert-ts`
or
`npm i assert-ts`
## Examples
### Assert condition, strict
```javascript
import assert from 'assert-ts';
function transfer(fromId: string, toId: string, amount: number) {
// Throws error if not true
assert(amount > 0);
...
}
```
### Assert condition, soft
```javascript
import assert from 'assert-ts';
function transfer(fromId: string, toId: string, amount: number) {
// Logs warning if false
if (assert.soft(amount > 0)) {
...
}
}
```
### Assert condition with more context info
To make it easier to find the cause of an assertion failure, you can provide more information, i.e. a custom message and any relevant properties.
```javascript
import assert from 'assert-ts';
function transfer(fromId: string, toId: string, amount: number) {
// Custom message and properties will be formatted into error message
assert(amount > 0, "Cannot transfer 0 or negative amounts", { fromId, toId, ammount });
...
}
```
### Assert non-null/undefined
```javascript
import assert from 'assert-ts';
function findAccount(id): Account | undefined { ... }
function transfer(fromnId: string, toId: string, amount: number) {
...
// Throws error if findAccount returns undefined
const fromAccount = assert(findAccount(fromId), "From account does not exist", { fromId});
// Type restriction: when a non-null/undefined assertion succeeds,
// type is restricted, e.g. to Account. Hence, no need for further testing of undefined/null
fromAccount.amount -= amount;
...
}
```
### Assert non-null/undefined, soft
```javascript
import assert from 'assert-ts';
function notify(person?: Person) {
...
// Logs warning if person is undefined
if (assert.soft(person, 'Person should be provided')) {
// person narrowed to Person
sendSms(person.mobile);
}
}
```
## API
`assert` has two signatures
### Assert condition
Checks that a condition is true. If not, an error is thrown. By default, any message or properties provided will be formatted as part of the error's message. See below for custom configuration.
```javascript
function assert(
condition: boolean,
message?: string,
props?: object | (() => object),
): asserts condition;
```
### Assert non-null/undefined
Checks that a value is not null or undefined. If null or undefined, an error is thrown. When successful, the returned value's type is restricted to the expected type.
```javascript
function assert(
value: T | undefined | null,
message?: string,
props?: object | (() => object),
): T;
```
`assert.soft` has two signatures
### Check condition
Checks that a condition is true. If not, logs a warning. By default, any message or properties provided will be formatted as part of the warning message. See below for custom configuration.
```javascript
function soft(
condition: boolean,
message?: string,
props?: object | (() => object),
): condition is true;
```
### Check non-null/undefined
Checks that a value is not null or undefined. If null or undefined, a warning is logged. When successful, the value's type is narrowed to the expected type.
```javascript
function soft(
value: T | undefined | null,
message?: string,
props?: object | (() => object),
): value is T;
```
### Configuration
The default configuration throws an Error with a message saying whether it was a condition or null/undefined check that failed and any custom message or properties formatted as part of the message.
Use `configureAssert` to customize this, providing an `AssertConfiguration` object with any of the following properties:
| Property | Description |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| formatter | To do custom formatting of error message `(failureType: FailureType, message?: string, props?: object) => string` |
| errorCreator | To create custom error objects `(failureType: FailureType, message?: string, props?: object) => Error` |
| errorReporter | To do custom reporting of assertion failures, e.g. report to backend `(failureType: FailureType, error: Error, message?: string, props?: object) => void` |
| warningReporter | To do custom reporting of soft assertion failures, e.g. report to backend `(failureType: FailureType, message?: string, props?: object) => void` |
### Contributors
Bjørn Egil Hansen (@bjornegil)
### Sponsors
[Fram X](https://framx.no) - a cross platform app company from Norway.
---
_Source: https://npm.io/package/assert-ts · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._