Registry / http-networking / protagonist

protagonist

JSON →
library0.1.12jsnpmunverified

Protagonist is a Node.js wrapper that provides programmatic access to Drafter, the high-performance C++ API Blueprint parser. It enables developers to validate and parse API Blueprint documents, a specialized Markdown dialect for describing web APIs, directly within Node.js applications. The current stable version, 2.3.0, integrates with Drafter 5.1.0, offering features like asynchronous and synchronous parsing and validation with configurable options, such as requiring a blueprint name. While it offers direct integration with the powerful Drafter engine, its reliance on `node-gyp` for compilation of native C++ addons during installation means it requires specific build toolchains (Python 2.7, C++ compiler) on the host system. This differentiates it from the simpler-to-install `drafter-npm` package, which provides pre-built binaries and is often recommended for general use, making Protagonist suitable for environments where direct compilation or specific Drafter version control is preferred.

http-networkingserialization
npm install protagonist
github ↗package ↗
INSTALL
IMPORT
SIG · PROTAGONIST
P
protagonist
http-networkingjavascriptv0.1.12
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.

protagonist
✓ const protagonist = require('protagonist');
✗ import { protagonist } from 'protagonist';
This package is primarily designed for CommonJS. When used in an ES Module context, it will likely be consumed as a default import representing the module object. Direct named imports are not supported.
parse
✓ const protagonist = require('protagonist'); const parseResult = await protagonist.parse(source);
✗ import { parse } from 'protagonist';
'parse' is a method on the default module object exported by Protagonist, not a named export itself. Destructuring directly from the module import/require will not work without first getting the default export.
validate
✓ const protagonist = require('protagonist'); const parseResult = await protagonist.validate(source, options);
✗ import { validate } from 'protagonist';
Similar to 'parse', 'validate' is a method on the default module object. Access it via the imported `protagonist` object.

Demonstrates asynchronous parsing of a basic API Blueprint document and logs the structured result, disabling the `requireBlueprintName` option for this example.

const protagonist = require('protagonist'); const blueprint = `# My API\n\n## Group Users\n\n### User [/users/{id}]\n+ Parameters\n + id: 1 (number, required) - The ID of the user.\n\n#### Retrieve a User [GET]\n+ Response 200 (application/json)\n + Body\n { "id": 1, "name": "John Doe" }\n`; async function parseAndLog() { try { const parseResult = await protagonist.parse(blueprint, { requireBlueprintName: false }); console.log(JSON.stringify(parseResult, null, 2)); } catch (error) { console.error('Parsing failed:', error); } } parseAndLog();
Debug
Known issues
breakingProtagonist v2.3.0 and above drop support for Node.js versions earlier than 12. Users on older Node.js runtimes must upgrade or use an earlier Protagonist version.
fix
Upgrade your Node.js environment to version 12 or higher (e.g., `nvm install 16` and `nvm use 16`).
affects: >=2.3.0
gotchaInstallation requires `node-gyp` build tools, including Python 2.7 (note: Python 3.x is generally not supported for `node-gyp` builds, though newer `node-gyp` versions may support 3.x, Protagonist explicitly mentions 2.7 in its documentation) and a C++ compiler. Missing these prerequisites will lead to compilation errors during `npm install`.
fix
Ensure Python 2.7 (and not Python 3.x, unless explicitly supported by `node-gyp` in your environment) and necessary C++ build tools are installed. For Windows, use `npm install --global --production windows-build-tools`. For macOS, install Xcode Command Line Tools (`xcode-select --install`). For Linux, install `build-essential`.
affects: >=1.0.0
gotchaThe documentation recommends using the `drafter-npm` package for general use instead of Protagonist directly. `drafter-npm` provides pre-built binaries, which avoids the complexities of local compilation that Protagonist requires.
fix
Consider switching to `drafter-npm` (`npm install drafter-npm`) if local compilation issues persist or if pre-built binaries are preferred for easier deployment.
affects: >=1.0.0
gotchaUsing the synchronous APIs (`parseSync`, `validateSync`) is not recommended as they can block the Node.js event loop, impacting application performance and responsiveness.
fix
Prefer the asynchronous `parse` and `validate` APIs to avoid blocking the event loop and ensure non-blocking I/O operations.
affects: >=1.0.0
Errors
Common errors & fixes
`node-gyp rebuild` failed with exit code 1
This error typically indicates that `node-gyp` could not successfully compile the native C++ addon. Common causes include missing Python 2.7, an incompatible Python version, or missing C++ build tools (like Visual Studio Build Tools on Windows or Xcode Command Line Tools on macOS).
fix
Verify Python 2.7 is installed and configured correctly (check `python --version`). Install necessary build tools for your operating system (e.g., `npm install --global --production windows-build-tools` on Windows, `xcode-select --install` on macOS, or `sudo apt-get install build-essential` on Debian/Ubuntu).
Error: Cannot find module '.../protagonist.node'
The native addon (`protagonist.node`) was not found, usually because compilation failed during installation or the file was deleted/moved.
fix
Attempt to reinstall the package (`npm rebuild protagonist` or `npm install protagonist`) after ensuring all `node-gyp` prerequisites are met. If issues persist, consider using `drafter-npm` which provides pre-built binaries.
TypeError: protagonist.parse is not a function
This usually occurs when attempting to destructure `parse` directly from a `require` or `import` statement, or when using an incorrect ES module import syntax for a CommonJS-first library. Protagonist exports a single module object with methods like `parse`.
fix
Ensure you are importing the entire module object and then accessing the method: `const protagonist = require('protagonist'); const parseResult = await protagonist.parse(source);` (for CommonJS) or `import protagonist from 'protagonist'; const parseResult = await protagonist.parse(source);` (for ESM, relying on Node's CJS interop).
Upgrade
Version history
0.1.12latest on npm
Audit
Dependencies
node-gyprequiredRequired for compiling the native C++ addons during installation. Ensures compatibility with various Node.js versions and platforms.
Agent activity
4 hits · last 30 days
node
4
Resources
githubhttps://github.com/apiaryio/protagonist ↗
packagehttps://www.npmjs.com/package/protagonist ↗
protagonist — npm install protagonist · libregistry