Encourages programming with assertions by providing tools to compile them away.

See: "unassert - encourage reliable programming by writing assertions in production" -- talk at NodeFest 2015, and "One more thing..." in talk at NodeFest 2016, titled "From Library to Tool - power-assert as a General Purpose Assertion Enhancement Tool"

RELATED MODULES

• unassertify: Browserify transform for unassert
• babel-plugin-unassert: Babel plugin for unassert
• webpack-unassert-loader: Webpack loader for unassert
• gulp-unassert: Gulp plugin for unassert
• unassert-cli: CLI for unassert
• rollup-plugin-unassert: RollupJS plugin for unassert

INSTALL

$ npm install --save-dev unassert

EXAMPLE

For given math.js below,

const assert = require('node:assert');

function add (a, b) {
  assert(typeof a === 'number');
  console.assert(!isNaN(a));
  assert.equal(typeof b, 'number');
  assert.ok(!isNaN(b));
  return a + b;
}

Apply unassertAst then generate modified code to console.

via CJS code

const { unassertAst } = require('unassert');
const { parse } = require('acorn');
const { generate } = require('escodegen');
const { readFileSync } = require('node:fs');
const { join, dirname } = require('node:path');

const filepath = join(__dirname, 'math.js');
const ast = parse(readFileSync(filepath), { ecmaVersion: '2022' });
const modifiedAst = unassertAst(ast);

console.log(generate(modifiedAst));

or via ESM code

import { unassertAst } from 'unassert';
import { parse } from 'acorn';
import { generate } from 'escodegen';
import { readFileSync } from 'node:fs';
import { join, dirname } from 'node:path';
import { fileURLToPath } from 'node:url';
const __dirname = dirname(fileURLToPath(import.meta.url));

const filepath = join(__dirname, 'math.js');
const ast = parse(readFileSync(filepath), { ecmaVersion: '2022' });
const modifiedAst = unassertAst(ast);

console.log(generate(modifiedAst));

Then you will see assert calls disappear.

function add(a, b) {
  return a + b;
}

API

unassert package exports four functions.

Main functions:

• unassertAst
• unassertCode

For customization:

• createVisitor
• defaultOptions

const modifiedAst = unassertAst(ast, options)

const { unassertAst } = require('unassert')

import { unassertAst } from 'unassert'

return type
object (ECMAScript AST)

Remove assertion calls from ast (ECMAScript AST). Default behaviour can be customized by options. ast is manipulated directly so returned modifiedAst will be the same instance of ast.

options

Object for configuration options. passed options is Object.assigned with default options. If not passed, default options will be used.

options.modules

Target module names for assertion call removal.

For example, the default target modules are as follows.

{
  modules: [
    'assert',
    'assert/strict',
    'node:assert',
    'node:assert/strict'
  ]
}

In this case, unassert will remove assert variable declarations such as,

• import assert from "assert"
• import assert from "assert/strict"
• import assert from "node:assert"
• import assert from "node:assert/strict"
• import * as assert from "assert"
• import * as assert from "node:assert"
• import * as assert from "assert/strict"
• import * as assert from "node:assert/strict"
• import { strict as assert } from "assert"
• import { strict as assert } from "node:assert"
• import { default as assert } from "assert"
• import { default as assert } from "node:assert"
• const assert = require("assert")
• const assert = require("node:assert")
• const assert = require("assert/strict")
• const assert = require("node:assert/strict")
• const assert = require("assert").strict
• const assert = require("node:assert").strict
• const { strict: assert } = require("assert")
• const { strict: assert } = require("node:assert")

and assignments.

• assert = require("assert")
• assert = require("node:assert")
• assert = require("assert/strict")
• assert = require("node:assert/strict")
• assert = require("assert").strict
• assert = require("node:assert").strict

In this default case, unassert will remove assertion calls such as,

• assert(value, [message])
• assert.ok(value, [message])
• assert.equal(actual, expected, [message])
• assert.notEqual(actual, expected, [message])
• assert.strictEqual(actual, expected, [message])
• assert.notStrictEqual(actual, expected, [message])
• assert.deepEqual(actual, expected, [message])
• assert.notDeepEqual(actual, expected, [message])
• assert.deepStrictEqual(actual, expected, [message])
• assert.notDeepStrictEqual(actual, expected, [message])
• assert.match(string, regexp[, message])
• assert.doesNotMatch(string, regexp[, message])
• assert.throws(block, [error], [message])
• assert.doesNotThrow(block, [message])
• await assert.rejects(asyncFn, [error], [message])
• await assert.doesNotReject(asyncFn, [error], [message])
• assert.fail([message])
• assert.fail(actual, expected, message, operator)
• assert.ifError(value)

in addition, unassert removes console.assert calls as well.

• console.assert(value, [message])

Auto Variable Tracking

unassert automatically removes assertion calls based on their imported variable names.

So if import declaration is as follows,

• import strictAssert, { ok, equal as eq } from 'node:assert/strict';

unassert removes all strictAssert, ok, eq calls.

Please see customization example for more details.

const unasserted = unassertCode(code, ast, options)

const { unassertCode } = require('unassert')

import { unassertCode } from 'unassert'

return type
`{ code: string; map: SourceMap

Remove assertion calls from the code. Default behaviour can be customized by options. Note that the ast is manipulated directly.

MagicString

If a MagicString is passed instead of a normal string, this function will simply modify that string and return it.

options

Object for configuration options. passed options is Object.assigned with default options. If not passed, default options will be used.

options.modules

The same as for unassertAst.

options.sourceMap

If true, a sourcemap of the changes will be generated in addition to the code.

You can alternatively specify sourcemap options if you which to customize how the sourcemap is generated.

const visitor = createVisitor(options)

const { createVisitor } = require('unassert')

import { createVisitor } from 'unassert'

return type
object (visitor object for estraverse)

Create visitor object to be used with estraverse.replace. Visitor can be customized by options.

options

Object for configuration options. passed options is Object.assigned with default options. If not passed, default options will be used.

options.modules

The same as for unassertAst.

options.code

A MagicString of the code the ast represents. If given, this code will be updated with the changes made to the ast.

const options = defaultOptions()

const { defaultOptions } = require('unassert')

import { defaultOptions } from 'unassert'

Returns default options object for unassertAst and createVisitor function. In other words, returns

{
  modules: [
    'assert',
    'assert/strict',
    'node:assert',
    'node:assert/strict'
  ]
}

CUSTOMIZATION

You can customize options such as target module names.

{
  modules: [
    'node:assert',
    'node:assert/strict',
    'power-assert',
    'invariant',
    'nanoassert',
    'uvu/assert'
  ]
}

example

For given custom.js below,

import invariant from 'invariant';
import nassert from 'nanoassert';
import * as uvuassert from 'uvu/assert';
import { strict as powerAssert } from 'power-assert';
import { default as looseAssert } from 'node:assert';
import strictAssert, { ok, equal as eq } from 'node:assert/strict';

async function add (a, b) {
  strictAssert(!isNaN(a));
  looseAssert(typeof a === 'number');
  eq(typeof b, 'number');
  ok(!isNaN(b));
  powerAssert(typeof a === typeof b);

  nassert(!isNaN(a));

  uvuassert.is(Math.sqrt(4), 2);
  uvuassert.is(Math.sqrt(144), 12);
  uvuassert.is(Math.sqrt(2), Math.SQRT2);

  invariant(someTruthyVal, 'This will not throw');
  invariant(someFalseyVal, 'This will throw an error with this message');

  await strictAssert.rejects(prms);
  await strictAssert.doesNotReject(prms2);

  return a + b;
}

Apply unassertAst with customized options then generate modified code to console.

import { unassertAst } from 'unassert';
import { parse } from 'acorn';
import { generate } from 'escodegen';
import { readFileSync } from 'node:fs';
import { join, dirname } from 'node:path';
import { fileURLToPath } from 'node:url';
const __dirname = dirname(fileURLToPath(import.meta.url));

const filepath = join(__dirname, 'custom.js');
const ast = parse(readFileSync(filepath), { ecmaVersion: '2022' });
const modifiedAst = unassertAst(ast, {
  modules: [
    'node:assert',
    'node:assert/strict',
    'power-assert',
    'invariant',
    'nanoassert',
    'uvu/assert'
  ]
});

console.log(generate(modifiedAst));

Then you will see all assert calls disappear.

async function add(a, b) {
  return a + b;
}

OUR SUPPORT POLICY

We support Node under maintenance. In other words, we stop supporting old Node version when their maintenance ends.

This means that any other environment is not supported.

NOTE: If unassert works in any of the unsupported environments, it is purely coincidental and has no bearing on future compatibility. Use at your own risk.

AUTHOR

• Takuto Wada

CONTRIBUTORS

• Renée Kooi
• Jordan Harband

LICENSE

Licensed under the MIT license.