Registry / serialization / minim-api-description

minim-api-description

library0.9.1jsnpmunverified

The `minim-api-description` library provides a programmatic interface for working with the Refract API Description namespace, a structured representation for describing APIs. It is built upon the `Minim` library, which offers a generic Abstract Syntax Tree (AST) for working with structured data. Currently at version `0.9.1`, this package is a foundational component within the broader API Elements ecosystem, which includes parsers for OpenAPI/Swagger and API Blueprint. While this specific package has not seen a recent version bump, it is actively maintained as part of the `api-elements.js` project, which sees frequent updates to its parsers and serializers. Its key differentiator lies in offering a low-level, object-oriented way to construct, traverse, and manipulate API descriptions, allowing for advanced tooling and transformations beyond what declarative formats alone typically provide.

serialization http-networking data

npm install minim-api-description

github ↗package ↗

INSTALL

IMPORT

SIG · MINIM-API-DESCRIPT

minim-api-description

serializationjavascriptv0.9.1

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.

apiDescription

✓ import apiDescription from 'minim-api-description';

✗ const apiDescription = require('minim-api-description');

The primary way to import the namespace plugin for ESM. CommonJS environments (Node.js < 12) should use `require`.

minim

✓ import minim from 'minim';

✗ import { minim } from 'minim';

Minim is a default export. Ensure you import it as such for ESM. For CommonJS, use `const minim = require('minim');`

Category

✓ const Category = namespace.getElementClass('category');

Elements like 'Category' are not directly imported from the package; they are accessed via the `namespace` object after applying the `apiDescription` plugin.

This example demonstrates how to initialize the API Description namespace, create core elements like `Category` and `Copy`, and access their properties.

import minim from 'minim'; import apiDescription from 'minim-api-description'; // Initialize a Minim namespace and extend it with API Description types const namespace = minim.namespace() .use(apiDescription); // Access and instantiate elements directly from the extended namespace const Category = namespace.getElementClass('category'); let category = new Category(['My API Section']); const Copy = namespace.getElementClass('copy'); let copy = new Copy('This is a description for the API section.'); category.push(copy); console.log(`Category Name: ${category.toValue()}`); console.log(`Category Description: ${category.copy.first().toValue()}`); // Example of accessing properties specific to API Description elements const Resource = namespace.getElementClass('resource'); let resource = new Resource(); resource.attributes.set('href', '/users'); category.resources.push(resource); console.log(`Resource Href: ${category.resources.first().attributes.get('href').toValue()}`);

Debug

Known issues

gotchaThe package `minim-api-description` is currently in version `0.9.1`. As a pre-1.0 release, its API might not be fully stable, and breaking changes could occur in subsequent minor versions before a `1.0.0` release. Users should pin exact versions and review changelogs for updates.

fix

Monitor releases closely and pin package versions (`"minim-api-description": "~0.9.1"` or `"minim-api-description": "0.9.1"`) to prevent unexpected breakage.

affects: <1.0.0

gotchaThis library heavily relies on `Minim` for its core AST capabilities. Understanding `Minim`'s Element types (e.g., `Element`, `ArrayElement`, `StringElement`) and their `.toValue()`, `.attributes`, and `.meta` properties is crucial for effective use of `minim-api-description`.

fix

Familiarize yourself with the `Minim` documentation, especially the core `Element` types and their methods, before diving deep into `minim-api-description`.

affects: >=0.1.0

gotchaElement accessors like `category.resources` or `category.copy` return `ArrayElement` instances, not plain JavaScript arrays. You must use `ArrayElement` methods (e.g., `.first()`, `.get(index)`, or iterate over it) to access the contained elements.

fix

Always treat return values of element accessors as `ArrayElement` instances. For example, use `category.resources.first()` instead of `category.resources[0]`.

affects: >=0.1.0

Errors

Common errors & fixes

TypeError: minim.namespace(...).use is not a function

Attempting to use `minim.namespace()` as a method when `minim` might not be correctly imported or is an older version.

fix

Ensure `minim` is imported as a default export (`import minim from 'minim';`) and that you are using a compatible version of `minim` (check its documentation for the `.namespace()` method availability).

TypeError: Cannot read properties of undefined (reading 'toValue')

Attempting to call `.toValue()` on an element that is `undefined`, often because an `ArrayElement` accessor (like `category.copy`) returned an empty array, or an attribute was not found.

fix

Always check if an element or attribute exists before attempting to access its properties or call methods on it. For example, `category.copy.first()?.toValue()` or `if (category.copy.length > 0) { ... }`.

Upgrade

Version history

0.9.1latest on npm

Audit

Dependencies

minimrequiredCore dependency providing the base AST types and namespace functionality that minim-api-description extends.

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/apiaryio/api-elements.js ↗

packagehttps://www.npmjs.com/package/minim-api-description ↗