Registry / testing / babel-plugin-jsdoc-to-assert

babel-plugin-jsdoc-to-assert

library4.0.0jsnpmunverified

A Babel plugin that converts JSDoc type annotations (@param and @type) into runtime assertion statements (console.assert) for testing. Version 4.0.0 is the current stable release, requiring Babel 7+. The plugin transforms static type documentation into executable checks, enabling runtime verification without a separate type system. Unlike TypeScript or Flow, it operates at the AST level during Babel transpilation and supports generic arrays (e.g., number[]) and rest parameters. Its primary differentiator is seamless integration into Babel workflows for development-only assertions, with options to enable/disable @param and @type checking. The package is maintained by azu and has a preset version (babel-preset-jsdoc-to-assert). Releases are infrequent, focusing on compatibility and bug fixes.

testing

npm install babel-plugin-jsdoc-to-assert

github ↗package ↗

INSTALL

IMPORT

SIG · BABEL-PLUGIN-JSDOC

babel-plugin-jsdoc-to-assert

testingjavascriptv4.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ module.exports = require('babel-plugin-jsdoc-to-assert')

✗ import plugin from 'babel-plugin-jsdoc-to-assert'

This is a Babel plugin; it is used declaratively in .babelrc or babel.config.js, not imported directly into application code.

jsdoc-to-assert plugin name

✓ "plugins": ["jsdoc-to-assert"]

✗ "plugins": ["babel-plugin-jsdoc-to-assert"]

In .babelrc or babel.config.js, the plugin name is 'jsdoc-to-assert', not the full npm package name. The 'babel-plugin-' prefix is implied.

options

✓ "plugins": [["jsdoc-to-assert", { "checkAtType": true }]]

✗ "plugins": ["jsdoc-to-assert", { "checkAtType": true }]

Options must be passed as the second element of an array within the plugins array. Incorrect nesting will cause options to be ignored.

Shows .babelrc configuration, environment-specific usage, and the runtime assertion transformation for @param types.

// .babelrc { "plugins": ["jsdoc-to-assert"], "env": { "development": { "plugins": ["jsdoc-to-assert"] } } } // Source file (src/index.js) /** * Adds two numbers. * @param {number} a - first number * @param {number} b - second number * @returns {number} sum */ function add(a, b) { return a + b; } // Build script (package.json) "scripts": { "build": "NODE_ENV=production babel src --out-dir lib --source-maps" } // After transform (development build): function add(a, b) { console.assert(typeof a === 'number'); console.assert(typeof b === 'number'); return a + b; }

Debug

Known issues

breakingv4.0.0 drops Babel 6 support; requires Babel 7 or later.

fix

Upgrade to Babel 7 and ensure @babel/core is installed.

affects: >=4.0.0

gotchacheckAtType is disabled by default because ES2015 transforms may run before this plugin, causing AssertionError with incorrect variable names (e.g., typeof _this === 'string').

fix

Set checkAtType: true only if plugin runs before ES2015 transforms (e.g., via plugin ordering). Consider using babel-preset-jsdoc-to-assert.

affects: >=2.0.0

gotchaPlugin uses console.assert, which does not throw on failure in Node.js (only prints to stderr). For test frameworks, use babel-preset-jsdoc-to-assert with useSpecReporter.

fix

Use babel-preset-jsdoc-to-assert with useSpecReporter option for throwing assertions.

affects: >=3.0.0

deprecatedv3.x and earlier used jsdoc-to-assert internally; v4.0.0 may have updated dependencies.

fix

Upgrade to v4.0.0 for Babel 7 compatibility.

affects: <4.0.0

gotchaThe plugin may fail on files with syntax errors (e.g., unterminated string constants). Reported as SyntaxError during babel build.

fix

Ensure source files are syntactically valid JavaScript. If error persists, file an issue with code sample.

affects: all

Errors

Common errors & fixes

ERROR in ./src/js/framework/Context.js Module build failed: SyntaxError: Unterminated string constant (3:16)

The plugin encounters a file with a syntax error (unterminated string) during transformation.

fix

Fix the syntax error in the source file. If the error is not reproducible without the plugin, file an issue on GitHub.

AssertionError: Invalid JSDoc: typeof _this === 'string'

checkAtType is enabled and the ES2015 arrow function transform (which renames 'this' to '_this') runs after jsdoc-to-assert, causing the generated assertion to use the incorrect variable name.

fix

Disable checkAtType or use babel-preset-jsdoc-to-assert which handles ordering. Alternatively, ensure plugin runs after ES2015 transforms.

ReferenceError: console is not defined

Using the plugin in an environment where console is not available (e.g., some older Web Workers or strict CSP).

fix

Polyfill console or consider using babel-preset-jsdoc-to-assert with useSpecReporter which uses assert instead.

Upgrade

Version history

4.0.0latest on npm

Audit

Dependencies

@babel/coreoptionalpeer dependency for Babel 7 plugin

Agent activity

18 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/azu/babel-plugin-jsdoc-to-assert ↗

packagehttps://www.npmjs.com/package/babel-plugin-jsdoc-to-assert ↗