https://github.com/rebeccastevens/deassert
Allows for programming with assertions/invariant-based programming during development without slowing down production.
https://github.com/rebeccastevens/deassert
Last synced: 5 months ago
JSON representation
Allows for programming with assertions/invariant-based programming during development without slowing down production.
- Host: GitHub
- URL: https://github.com/rebeccastevens/deassert
- Owner: RebeccaStevens
- License: bsd-3-clause
- Created: 2024-01-05T09:43:39.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-01-04T22:43:13.000Z (5 months ago)
- Last Synced: 2025-01-04T23:25:46.499Z (5 months ago)
- Language: TypeScript
- Size: 829 KB
- Stars: 1
- Watchers: 1
- Forks: 1
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# Deassert Mono Repo
[](https://github.com/RebeccaStevens/deassert/actions/workflows/release.yml)
[](https://codecov.io/gh/RebeccaStevens/deassert)\
[](https://github.com/prettier/prettier)
[](https://github.com/RebeccaStevens/deassert/discussions)
[](https://opensource.org/licenses/BSD-3-Clause)
[](https://commitizen.github.io/cz-cli/)
[](https://github.com/semantic-release/semantic-release)
Allows for [programming with
assertions]()/[invariant-based
programming](https://en.wikipedia.org/wiki/Invariant-based_programming) during
development without slowing down production.
## Donate
[Any donations would be much appreciated](./DONATIONS.md). 😄
### Enterprise Users
`deassert` is available as part of the [Tidelift Subscription](https://tidelift.com/funding/github/npm/deassert).
Tidelift is working with the maintainers of `deassert` and a growing network of open source maintainers
to ensure your open source software supply chain meets enterprise standards now and into the future.
[Learn more.](https://tidelift.com/subscription/pkg/npm-deassert?utm_source=npm-deassert&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)
## Installation
```sh
# Install with npm
npm install -D deassert
# Install with pnpm
pnpm add -D deassert
# Install with yarn
yarn add -D deassert
# Install with bun
bun add -D deassert
```
## Thinking about Invariants
Invariant checks in your code should be thought of as a way of saying:
> If this check fails, something is very wrong elsewhere in my code.
Do not try to recover from Assertion Errors. If your error is recoverable, use a different type of error object.
## Usage
You probably don't want to use this library in your development builds.
It's designed to be used in your production builds.
### Packages
- [JS API](./packages/core/) [](https://www.npmjs.com/package/deassert)
- [CLI](./packages/cli/) [](https://www.npmjs.com/package/deassert-cli)
- [Rollup Plugin](./packages/rollup-plugin/) [](https://www.npmjs.com/package/rollup-plugin-deassert)
- [Webpack Loader](./packages/webpack-loader/) [](https://www.npmjs.com/package/deassert-loader)
## Example
Given the following code that uses assertion calls to enforce known invariants,
some of which may be expensive (line 25):
```js
import { AssertionError, ok as assert, fail as assertNever } from "node:assert/strict";
const stack = [
{
type: "foo",
children: [
/* ... */
],
},
];
const result = [];
try {
do {
const element = stack.pop() ?? assertNever("stack is empty (or contains undefined).");
switch (element.type) {
case "foo": {
assert(children.every(isExpectedType), "unexpected child type.");
stack.push(...children);
break;
}
case "bar": {
assert(element.children.length === 0, "bar elements should not have children.");
result.push(element.data);
break;
}
case "baz": {
throw new Error("Not Implemented yet.");
}
default: {
assertNever(`Unexpected type: "${element.type}"`);
}
}
} while (stack.length > 0);
console.log((assert(result.length > 0), result));
} catch (error) {
assert(error instanceof Error, "Unexpected Error.");
assert(!(error instanceof AssertionError), error);
console.error(error);
}
```
This library will transform the code into essentially the following:
```js
const stack = [
{
type: "foo",
children: [
/* ... */
],
},
];
const result = [];
try {
do {
const element = stack.pop();
switch (element.type) {
case "foo": {
stack.push(...children);
break;
}
case "bar": {
result.push(element.data);
break;
}
case "baz": {
throw new Error("Not Implemented yet.");
}
}
} while (stack.length > 0);
console.log(result);
} catch (error) {
console.error(error);
}
```
## Similar Projects
This project was inspired by [Unassert](https://github.com/unassert-js/unassert)
which has the same objective as this project.
While unassert works by modifying the inputted AST, this library
works directly on the inputted code.