deassert

Deassert

Allows for programming with assertions/invariant-based programming during development without slowing down production.

Donate

Any donations would be much appreciated. 😄

Installation

# 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.

Rollup Plugin

// rollup.config.js
import { rollupPlugin as deassert } from "deassert";

const isProduction = process.env.NODE_ENV === "production";

export default {
  // ...
  plugins: isProduction
    ? [
        // ...
        deassert({
          include: ["**/*.ts"], // If using TypeScript, be sure to include this config option. Otherwise remove it.
        }),
      ]
    : [
        // ...
      ],
};

CLI

npx deassert myfile.js > myfile.deasserted.js

Note: Options cannot be provided via the CLI.

API

import deassert from "deassert";

const result = deassert(code, options);
console.log(result.code);

Options

modules

An array of modules to be considered assert modules. These modules will be what is stripped out.

default

["assert", "assert/strict", "node:assert", "node:assert/strict"]

sourceMap

Determines if a source map should be generated.

MagicString source map options can be passed in.

default

false

If true is passed, then these options will be used:

{
  "hires": true,
}

ast

The AST of the code that is passed in.

Providing this is optional, but if you have the AST already then we can use that instead of generating our own.

default

undefined

acornOptions

The options provided to Acorn to parse the input code. These are not used if an AST is provided.

default

{
  "sourceType": "module",
  "ecmaVersion": "latest",
}

Example

Given the following code that uses assertion calls to enforce known invariants, some of which may be expensive (line 11):

import { ok as assert, fail as assertNever, AssertionError } 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:

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 which has the same objective as this project.

While unassert works by modifying the inputted AST, this library works directly on the inputted code.