Overview
The parser utilities provide functions for parsing markdown files (changelog, index) and JSON files (type maps) used during documentation generation.
Markdown Parsers
parseChangelog
Retrieves all Node.js major versions from a CHANGELOG.md file and returns an array of release entries with version and LTS status.
import { parseChangelog } from './parsers/markdown.mjs';
const releases = await parseChangelog(
'https://raw.githubusercontent.com/nodejs/node/HEAD/CHANGELOG.md'
);
parsers/markdown.mjs:22
Parameters
Path or URL to the CHANGELOG.md file
Returns
releases
Promise<ApiDocReleaseEntry[]>
Array of release entries, each containing:
Coerced semantic version object
Whether this is a Long Term Support release
Example Output
[
{ version: SemVer('20.0.0'), isLts: false },
{ version: SemVer('18.0.0'), isLts: true },
{ version: SemVer('16.0.0'), isLts: true },
]
Implementation Details
Uses regex pattern to match changelog entries:
const NODE_VERSIONS_REGEX = /\* \[Node\.js ([0-9.]+)\]\S+ (.*)\r?\n/g;
const NODE_LTS_VERSION_REGEX = /Long Term Support/i;
parseIndex
Retrieves all document titles from an index.md file for sidebar generation.
import { parseIndex } from './parsers/markdown.mjs';
const index = await parseIndex(
'https://raw.githubusercontent.com/nodejs/node/HEAD/doc/api/index.md'
);
parsers/markdown.mjs:39
Parameters
Path or URL to the index.md file. Returns empty array if path is falsy.
Returns
index
Promise<Array<{ section: string, api: string }>>
Array of index entries with section title and API name
Example Output
[
{ section: 'File system', api: 'fs' },
{ section: 'HTTP', api: 'http' },
{ section: 'Path', api: 'path' },
]
Implementation Details
Uses regex pattern to match list items:
const LIST_ITEM_REGEX = /\* \[(.*?)\]\((.*?)\.md\)/g;
JSON Parsers
parseTypeMap
Retrieves a type mapping from a JSON file, used to map Node.js types to standard types.
import { parseTypeMap } from './parsers/json.mjs';
const typeMap = await parseTypeMap('./typeMap.json');
parsers/json.mjs:11
Parameters
Path or URL to the type map JSON file. Returns empty object if path is falsy.
Returns
typeMap
Promise<Record<string, string>>
Object mapping source types to target types
{
"Integer": "number",
"String": "string",
"Boolean": "boolean",
"Buffer": "Uint8Array",
"Object": "object"
}
Example Usage
const typeMap = await parseTypeMap('./typeMap.json');
console.log(typeMap['Integer']); // 'number'
console.log(typeMap['Buffer']); // 'Uint8Array'
Shared Utilities
All parsers use the loadFromURL utility to fetch content from URLs or file paths:
import { loadFromURL } from '../utils/parser.mjs';
const content = await loadFromURL('https://example.com/file.md');
// or
const content = await loadFromURL('./local/file.md');
- HTTP/HTTPS URLs
- File system paths
- URL objects
- Error handling for network and file system errors
Integration with Configuration
Parsers are automatically invoked by the configuration system when loading configuration:
import { createRunConfiguration } from './utils/configuration/index.mjs';
// String values are automatically parsed
const config = await createRunConfiguration({
changelog: 'https://raw.githubusercontent.com/nodejs/node/HEAD/CHANGELOG.md',
index: 'https://raw.githubusercontent.com/nodejs/node/HEAD/doc/api/index.md',
typeMap: './typeMap.json',
});
// After parsing, config contains:
console.log(config.global.changelog); // Array of release entries
console.log(config.global.index); // Array of index entries
console.log(config.metadata.typeMap); // Type map object
utils/configuration/index.mjs:58
Examples
Parsing Changelog with Custom URL
import { parseChangelog } from './parsers/markdown.mjs';
const changelog = await parseChangelog(
'https://raw.githubusercontent.com/nodejs/node/v20.x/CHANGELOG.md'
);
// Filter LTS versions only
const ltsVersions = changelog.filter(release => release.isLts);
console.log('LTS versions:', ltsVersions.map(r => r.version.version));
Building Documentation Index
import { parseIndex } from './parsers/markdown.mjs';
const index = await parseIndex('./doc/api/index.md');
// Generate sidebar navigation
const sidebar = index.map(({ section, api }) => ({
title: section,
href: `/docs/api/${api}`,
}));
Loading Type Map for Generator
import { parseTypeMap } from './parsers/json.mjs';
import getConfig from './utils/configuration/index.mjs';
// Inside a generator
const config = getConfig('metadata');
const typeMap = await parseTypeMap(config.typeMap);
// Use type map to transform types
const transformType = (type) => typeMap[type] || type;
console.log(transformType('Integer')); // 'number'
Error Handling
import { parseChangelog } from './parsers/markdown.mjs';
import logger from './logger/index.mjs';
try {
const changelog = await parseChangelog(
'https://example.com/CHANGELOG.md'
);
} catch (err) {
logger.error('Failed to parse changelog', { error: err.message });
// Use default or fallback
}
Custom Parser Pattern
If you need to parse additional markdown patterns:
import { loadFromURL } from '../utils/parser.mjs';
// Parse custom list format
const parseCustomList = async (path) => {
if (!path) return [];
const content = await loadFromURL(path);
const CUSTOM_REGEX = /^- \*\*(.+?)\*\*: (.+)$/gm;
const items = Array.from(content.matchAll(CUSTOM_REGEX));
return items.map(([, key, value]) => ({ key, value }));
};
Type Definitions
ApiDocReleaseEntry
type ApiDocReleaseEntry = {
version: SemVer;
isLts: boolean;
};
IndexEntry
type IndexEntry = {
section: string;
api: string;
};
TypeMap
type TypeMap = Record<string, string>;