From aefa4132af7dc8303f6782ce5987b669bab9f193 Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Sat, 7 Feb 2026 16:19:40 +0100 Subject: [PATCH 01/12] fix: filter out new keys from legacy JSON generator --- src/generators/legacy-json/index.mjs | 39 +++++++++++++++++++++++++++- 1 file changed, 38 insertions(+), 1 deletion(-) diff --git a/src/generators/legacy-json/index.mjs b/src/generators/legacy-json/index.mjs index 7b6448d7..6556f631 100644 --- a/src/generators/legacy-json/index.mjs +++ b/src/generators/legacy-json/index.mjs @@ -78,7 +78,44 @@ export default { for (const section of chunkResult) { const out = join(output, `${section.api}.json`); - await writeFile(out, JSON.stringify(section, null, 2)); + await writeFile(out, JSON.stringify(section, [ + // TODO: remove this array once all the additional keys have been introduced downstream + 'added', + 'changes', + 'classes', + 'classMethods', + 'commit', + 'ctors', + 'default', + 'deprecated', + 'desc', + 'description', + 'displayName', + 'events', + 'examples', + 'globals', + 'introduced_in', + 'meta', + 'methods', + 'miscs', + ...(section.api === 'index' ? [] : ['modules']), + 'name', + 'napiVersion', + 'options', + 'params', + 'pr-url', + 'properties', + 'removed', + 'return', + 'shortDesc', + 'signatures', + 'source', + 'stability', + 'stabilityText', + 'textRaw', + 'type', + 'version', +], 2)); } } From 704b72855039bd72bcb4fdf174512284fe891db5 Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Sat, 7 Feb 2026 16:21:01 +0100 Subject: [PATCH 02/12] Remove TODO comment for additional JSON keys Removed commented TODO note about additional keys in JSON output. --- src/generators/legacy-json/index.mjs | 73 ++++++++++++++-------------- 1 file changed, 36 insertions(+), 37 deletions(-) diff --git a/src/generators/legacy-json/index.mjs b/src/generators/legacy-json/index.mjs index 6556f631..0dc53ee7 100644 --- a/src/generators/legacy-json/index.mjs +++ b/src/generators/legacy-json/index.mjs @@ -79,43 +79,42 @@ export default { const out = join(output, `${section.api}.json`); await writeFile(out, JSON.stringify(section, [ - // TODO: remove this array once all the additional keys have been introduced downstream - 'added', - 'changes', - 'classes', - 'classMethods', - 'commit', - 'ctors', - 'default', - 'deprecated', - 'desc', - 'description', - 'displayName', - 'events', - 'examples', - 'globals', - 'introduced_in', - 'meta', - 'methods', - 'miscs', - ...(section.api === 'index' ? [] : ['modules']), - 'name', - 'napiVersion', - 'options', - 'params', - 'pr-url', - 'properties', - 'removed', - 'return', - 'shortDesc', - 'signatures', - 'source', - 'stability', - 'stabilityText', - 'textRaw', - 'type', - 'version', -], 2)); + 'added', + 'changes', + 'classes', + 'classMethods', + 'commit', + 'ctors', + 'default', + 'deprecated', + 'desc', + 'description', + 'displayName', + 'events', + 'examples', + 'globals', + 'introduced_in', + 'meta', + 'methods', + 'miscs', + ...(section.api === 'index' ? [] : ['modules']), + 'name', + 'napiVersion', + 'options', + 'params', + 'pr-url', + 'properties', + 'removed', + 'return', + 'shortDesc', + 'signatures', + 'source', + 'stability', + 'stabilityText', + 'textRaw', + 'type', + 'version', + ], 2)); } } From bb9559ab6f36245efeab98a8648526e7620a673a Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Sat, 7 Feb 2026 16:21:54 +0100 Subject: [PATCH 03/12] readd TODO --- src/generators/legacy-json/index.mjs | 1 + 1 file changed, 1 insertion(+) diff --git a/src/generators/legacy-json/index.mjs b/src/generators/legacy-json/index.mjs index 0dc53ee7..3e9847e9 100644 --- a/src/generators/legacy-json/index.mjs +++ b/src/generators/legacy-json/index.mjs @@ -79,6 +79,7 @@ export default { const out = join(output, `${section.api}.json`); await writeFile(out, JSON.stringify(section, [ + // TODO: remove this array once all the additional keys have been introduced downstream 'added', 'changes', 'classes', From b69ded03b45cc6be46dd784c6e35a74e32215cfe Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Sat, 7 Feb 2026 16:23:22 +0100 Subject: [PATCH 04/12] add to legacy json-all generator --- src/generators/legacy-json-all/index.mjs | 42 +++++++++++++++++++++++- 1 file changed, 41 insertions(+), 1 deletion(-) diff --git a/src/generators/legacy-json-all/index.mjs b/src/generators/legacy-json-all/index.mjs index a98eb980..f1f7be11 100644 --- a/src/generators/legacy-json-all/index.mjs +++ b/src/generators/legacy-json-all/index.mjs @@ -85,7 +85,47 @@ export default { if (output) { await writeFile( join(output, 'all.json'), - JSON.stringify(generatedValue, null, 2) + JSON.stringify( + section, + [ + // TODO: remove this array once all the additional keys have been introduced downstream + 'added', + 'changes', + 'classes', + 'classMethods', + 'commit', + 'ctors', + 'default', + 'deprecated', + 'desc', + 'description', + 'displayName', + 'events', + 'examples', + 'globals', + 'introduced_in', + 'meta', + 'methods', + 'miscs', + 'name', + 'napiVersion', + 'options', + 'params', + 'pr-url', + 'properties', + 'removed', + 'return', + 'shortDesc', + 'signatures', + 'source', + 'stability', + 'stabilityText', + 'textRaw', + 'type', + 'version', + ], + 2, + )); ); } From 70789016ddce8782c0295d754bdde038c7ed8702 Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Sat, 7 Feb 2026 16:28:01 +0100 Subject: [PATCH 05/12] Apply suggestion from @aduh95 --- src/generators/legacy-json-all/index.mjs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/generators/legacy-json-all/index.mjs b/src/generators/legacy-json-all/index.mjs index f1f7be11..4fb68b32 100644 --- a/src/generators/legacy-json-all/index.mjs +++ b/src/generators/legacy-json-all/index.mjs @@ -125,7 +125,7 @@ export default { 'version', ], 2, - )); + ) ); } From 7da829961259024395898b069c3aecc75566d1d9 Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Sat, 7 Feb 2026 16:29:15 +0100 Subject: [PATCH 06/12] Apply suggestion from @aduh95 --- src/generators/legacy-json-all/index.mjs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/generators/legacy-json-all/index.mjs b/src/generators/legacy-json-all/index.mjs index 4fb68b32..721d83c5 100644 --- a/src/generators/legacy-json-all/index.mjs +++ b/src/generators/legacy-json-all/index.mjs @@ -86,7 +86,7 @@ export default { await writeFile( join(output, 'all.json'), JSON.stringify( - section, + generatedValue, [ // TODO: remove this array once all the additional keys have been introduced downstream 'added', From 488a2a3bef272df67159936781e3cd70e8abb3e0 Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Sat, 7 Feb 2026 23:18:09 +0100 Subject: [PATCH 07/12] move to separate function --- src/generators/legacy-json-all/index.mjs | 42 +----------------- src/generators/legacy-json/index.mjs | 39 +---------------- src/utils/generators.mjs | 54 +++++++++++++++++++++--- 3 files changed, 51 insertions(+), 84 deletions(-) diff --git a/src/generators/legacy-json-all/index.mjs b/src/generators/legacy-json-all/index.mjs index 721d83c5..bd8687b8 100644 --- a/src/generators/legacy-json-all/index.mjs +++ b/src/generators/legacy-json-all/index.mjs @@ -85,47 +85,7 @@ export default { if (output) { await writeFile( join(output, 'all.json'), - JSON.stringify( - generatedValue, - [ - // TODO: remove this array once all the additional keys have been introduced downstream - 'added', - 'changes', - 'classes', - 'classMethods', - 'commit', - 'ctors', - 'default', - 'deprecated', - 'desc', - 'description', - 'displayName', - 'events', - 'examples', - 'globals', - 'introduced_in', - 'meta', - 'methods', - 'miscs', - 'name', - 'napiVersion', - 'options', - 'params', - 'pr-url', - 'properties', - 'removed', - 'return', - 'shortDesc', - 'signatures', - 'source', - 'stability', - 'stabilityText', - 'textRaw', - 'type', - 'version', - ], - 2, - ) + legacyToJSON(generatedValue) ); } diff --git a/src/generators/legacy-json/index.mjs b/src/generators/legacy-json/index.mjs index 3e9847e9..62787a3b 100644 --- a/src/generators/legacy-json/index.mjs +++ b/src/generators/legacy-json/index.mjs @@ -78,44 +78,7 @@ export default { for (const section of chunkResult) { const out = join(output, `${section.api}.json`); - await writeFile(out, JSON.stringify(section, [ - // TODO: remove this array once all the additional keys have been introduced downstream - 'added', - 'changes', - 'classes', - 'classMethods', - 'commit', - 'ctors', - 'default', - 'deprecated', - 'desc', - 'description', - 'displayName', - 'events', - 'examples', - 'globals', - 'introduced_in', - 'meta', - 'methods', - 'miscs', - ...(section.api === 'index' ? [] : ['modules']), - 'name', - 'napiVersion', - 'options', - 'params', - 'pr-url', - 'properties', - 'removed', - 'return', - 'shortDesc', - 'signatures', - 'source', - 'stability', - 'stabilityText', - 'textRaw', - 'type', - 'version', - ], 2)); + await writeFile(out, legacyToJSON(section)); } } diff --git a/src/utils/generators.mjs b/src/utils/generators.mjs index ed0c89de..890b13cc 100644 --- a/src/utils/generators.mjs +++ b/src/utils/generators.mjs @@ -10,7 +10,7 @@ import { DOC_API_BASE_URL_VERSION } from '../constants.mjs'; * * @param {Array} nodes The API metadata Nodes to be grouped */ -export const groupNodesByModule = nodes => { +export const groupNodesByModule = (nodes) => { /** @type {Map>} */ const groupedNodes = new Map(); @@ -30,7 +30,7 @@ export const groupNodesByModule = nodes => { * * @param {import('semver').SemVer} version The version to be parsed */ -export const getVersionFromSemVer = version => +export const getVersionFromSemVer = (version) => version.minor === 0 ? `${version.major}.x` : `${version.major}.${version.minor}.x`; @@ -54,7 +54,7 @@ export const getVersionURL = (version, api) => * @param {string|import('semver').SemVer} version SemVer compatible version (maybe) * @returns {import('semver').SemVer} SemVer compatible version */ -export const coerceSemVer = version => { +export const coerceSemVer = (version) => { const coercedVersion = coerce(version); if (coercedVersion === null) { @@ -77,7 +77,7 @@ export const getCompatibleVersions = (introduced, releases) => { const coercedMajor = major(coerceSemVer(introduced)); // All Node.js versions that support the current API; If there's no "introduced_at" field, // we simply show all versions, as we cannot pinpoint the exact version - return releases.filter(release => release.version.major >= coercedMajor); + return releases.filter((release) => release.version.major >= coercedMajor); }; /** @@ -108,4 +108,48 @@ export const sortChanges = (changes, key = 'version') => { * @param {Object} source - The source object */ export const leftHandAssign = (target, source) => - Object.keys(source).forEach(k => k in target || (target[k] = source[k])); + Object.keys(source).forEach((k) => k in target || (target[k] = source[k])); + +export const legacyToJSON = (section) => + JSON.stringify( + section, + [ + // TODO: remove this array once all the additional keys have been introduced downstream + 'added', + 'changes', + 'classes', + 'classMethods', + 'commit', + 'ctors', + 'default', + 'deprecated', + 'desc', + 'description', + 'displayName', + 'events', + 'examples', + 'globals', + 'introduced_in', + 'meta', + 'methods', + 'miscs', + ...(section.api === 'index' ? [] : ['modules']), + 'name', + 'napiVersion', + 'options', + 'params', + 'pr-url', + 'properties', + 'removed', + 'return', + 'shortDesc', + 'signatures', + 'source', + 'stability', + 'stabilityText', + 'textRaw', + 'type', + 'version', + ], + 2 + ); From a8e1af597c857e898f963318523c020ee76343d5 Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Sat, 7 Feb 2026 23:21:21 +0100 Subject: [PATCH 08/12] squash! --- src/generators/legacy-json-all/index.mjs | 2 ++ src/generators/legacy-json/index.mjs | 2 +- src/utils/generators.mjs | 5 +++++ 3 files changed, 8 insertions(+), 1 deletion(-) diff --git a/src/generators/legacy-json-all/index.mjs b/src/generators/legacy-json-all/index.mjs index bd8687b8..124eeef6 100644 --- a/src/generators/legacy-json-all/index.mjs +++ b/src/generators/legacy-json-all/index.mjs @@ -3,6 +3,8 @@ import { writeFile } from 'node:fs/promises'; import { join } from 'node:path'; +import { legacyToJSON } from '../../utils/generators.mjs'; + /** * This generator consolidates data from the `legacy-json` generator into a single * JSON file (`all.json`). diff --git a/src/generators/legacy-json/index.mjs b/src/generators/legacy-json/index.mjs index 62787a3b..a897863d 100644 --- a/src/generators/legacy-json/index.mjs +++ b/src/generators/legacy-json/index.mjs @@ -4,7 +4,7 @@ import { writeFile } from 'node:fs/promises'; import { join } from 'node:path'; import { createSectionBuilder } from './utils/buildSection.mjs'; -import { groupNodesByModule } from '../../utils/generators.mjs'; +import { groupNodesByModule, legacyToJSON } from '../../utils/generators.mjs'; const buildSection = createSectionBuilder(); diff --git a/src/utils/generators.mjs b/src/utils/generators.mjs index 890b13cc..57398f82 100644 --- a/src/utils/generators.mjs +++ b/src/utils/generators.mjs @@ -110,6 +110,11 @@ export const sortChanges = (changes, key = 'version') => { export const leftHandAssign = (target, source) => Object.keys(source).forEach((k) => k in target || (target[k] = source[k])); +/** + * Transforms an object to JSON output consistent with the JSON version. + * @param {Object} section - The source object + * @returns {string} - The JSON output + */ export const legacyToJSON = (section) => JSON.stringify( section, From c2319472f7dddf122ebec517804ddff84ee5b78b Mon Sep 17 00:00:00 2001 From: Aviv Keller Date: Sat, 7 Feb 2026 17:23:38 -0500 Subject: [PATCH 09/12] fixup! format --- src/generators/legacy-json-all/index.mjs | 5 +---- src/utils/generators.mjs | 12 ++++++------ 2 files changed, 7 insertions(+), 10 deletions(-) diff --git a/src/generators/legacy-json-all/index.mjs b/src/generators/legacy-json-all/index.mjs index 124eeef6..3667b23e 100644 --- a/src/generators/legacy-json-all/index.mjs +++ b/src/generators/legacy-json-all/index.mjs @@ -85,10 +85,7 @@ export default { } if (output) { - await writeFile( - join(output, 'all.json'), - legacyToJSON(generatedValue) - ); + await writeFile(join(output, 'all.json'), legacyToJSON(generatedValue)); } return generatedValue; diff --git a/src/utils/generators.mjs b/src/utils/generators.mjs index 57398f82..4a8d7e91 100644 --- a/src/utils/generators.mjs +++ b/src/utils/generators.mjs @@ -10,7 +10,7 @@ import { DOC_API_BASE_URL_VERSION } from '../constants.mjs'; * * @param {Array} nodes The API metadata Nodes to be grouped */ -export const groupNodesByModule = (nodes) => { +export const groupNodesByModule = nodes => { /** @type {Map>} */ const groupedNodes = new Map(); @@ -30,7 +30,7 @@ export const groupNodesByModule = (nodes) => { * * @param {import('semver').SemVer} version The version to be parsed */ -export const getVersionFromSemVer = (version) => +export const getVersionFromSemVer = version => version.minor === 0 ? `${version.major}.x` : `${version.major}.${version.minor}.x`; @@ -54,7 +54,7 @@ export const getVersionURL = (version, api) => * @param {string|import('semver').SemVer} version SemVer compatible version (maybe) * @returns {import('semver').SemVer} SemVer compatible version */ -export const coerceSemVer = (version) => { +export const coerceSemVer = version => { const coercedVersion = coerce(version); if (coercedVersion === null) { @@ -77,7 +77,7 @@ export const getCompatibleVersions = (introduced, releases) => { const coercedMajor = major(coerceSemVer(introduced)); // All Node.js versions that support the current API; If there's no "introduced_at" field, // we simply show all versions, as we cannot pinpoint the exact version - return releases.filter((release) => release.version.major >= coercedMajor); + return releases.filter(release => release.version.major >= coercedMajor); }; /** @@ -108,14 +108,14 @@ export const sortChanges = (changes, key = 'version') => { * @param {Object} source - The source object */ export const leftHandAssign = (target, source) => - Object.keys(source).forEach((k) => k in target || (target[k] = source[k])); + Object.keys(source).forEach(k => k in target || (target[k] = source[k])); /** * Transforms an object to JSON output consistent with the JSON version. * @param {Object} section - The source object * @returns {string} - The JSON output */ -export const legacyToJSON = (section) => +export const legacyToJSON = section => JSON.stringify( section, [ From 870043b49dfd93cdb9f04afc9a2476650ec29a43 Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Mon, 9 Feb 2026 11:15:06 +0000 Subject: [PATCH 10/12] squash! order --- src/utils/generators.mjs | 46 +++++++++++++++++++++++++++++++++++++--- 1 file changed, 43 insertions(+), 3 deletions(-) diff --git a/src/utils/generators.mjs b/src/utils/generators.mjs index 4a8d7e91..775e848e 100644 --- a/src/utils/generators.mjs +++ b/src/utils/generators.mjs @@ -113,11 +113,51 @@ export const leftHandAssign = (target, source) => /** * Transforms an object to JSON output consistent with the JSON version. * @param {Object} section - The source object + * @param section.api + * @param section.type + * @param section.source + * @param section.introduced_in + * @param section.meta + * @param section.stability + * @param section.stabilityText + * @param section.classes + * @param section.methods + * @param section.properties + * @param section.miscs + * @param section.modules + * @param section.globals * @returns {string} - The JSON output */ -export const legacyToJSON = section => +export const legacyToJSON = ({ + api, + type, + source, + introduced_in, + meta, + stability, + stabilityText, + classes, + methods, + properties, + miscs, + modules, + globals, +}) => JSON.stringify( - section, + { + type, + source, + introduced_in, + meta, + stability, + stabilityText, + classes, + methods, + properties, + miscs, + modules, + globals, + }, [ // TODO: remove this array once all the additional keys have been introduced downstream 'added', @@ -138,7 +178,7 @@ export const legacyToJSON = section => 'meta', 'methods', 'miscs', - ...(section.api === 'index' ? [] : ['modules']), + ...(api === 'index' ? [] : ['modules']), 'name', 'napiVersion', 'options', From 236c8b0f4f1c4fe16b40f152f0ff6f86ceda59f9 Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Mon, 9 Feb 2026 12:59:43 +0000 Subject: [PATCH 11/12] fixup! squash! order --- src/utils/generators.mjs | 78 +++++++++++----------------------------- 1 file changed, 21 insertions(+), 57 deletions(-) diff --git a/src/utils/generators.mjs b/src/utils/generators.mjs index 775e848e..22dfd8a0 100644 --- a/src/utils/generators.mjs +++ b/src/utils/generators.mjs @@ -113,87 +113,51 @@ export const leftHandAssign = (target, source) => /** * Transforms an object to JSON output consistent with the JSON version. * @param {Object} section - The source object - * @param section.api - * @param section.type - * @param section.source - * @param section.introduced_in - * @param section.meta - * @param section.stability - * @param section.stabilityText - * @param section.classes - * @param section.methods - * @param section.properties - * @param section.miscs - * @param section.modules - * @param section.globals * @returns {string} - The JSON output */ -export const legacyToJSON = ({ - api, - type, - source, - introduced_in, - meta, - stability, - stabilityText, - classes, - methods, - properties, - miscs, - modules, - globals, -}) => +export const legacyToJSON = section => JSON.stringify( - { - type, - source, - introduced_in, - meta, - stability, - stabilityText, - classes, - methods, - properties, - miscs, - modules, - globals, - }, + section, + // TODO: remove this array once all the additional keys have been introduced downstream [ - // TODO: remove this array once all the additional keys have been introduced downstream + // Top-level keys (order matter): + 'type', + 'source', + 'introduced_in', + 'meta', + 'stability', + 'stabilityText', + 'classes', + 'methods', + 'properties', + 'miscs', + ...(section.api === 'index' ? [] : ['modules']), + 'globals', + + // History section 'added', + 'deprecated', + 'removed', 'changes', - 'classes', + // Remaining keys 'classMethods', 'commit', 'ctors', 'default', - 'deprecated', 'desc', 'description', 'displayName', 'events', 'examples', - 'globals', - 'introduced_in', - 'meta', - 'methods', - 'miscs', - ...(api === 'index' ? [] : ['modules']), 'name', 'napiVersion', 'options', 'params', 'pr-url', - 'properties', - 'removed', 'return', 'shortDesc', 'signatures', - 'source', - 'stability', - 'stabilityText', 'textRaw', - 'type', 'version', ], 2 From 632755b6c1971d4053c60690053ae31ad6c856cd Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Mon, 9 Feb 2026 17:41:34 +0000 Subject: [PATCH 12/12] squash! only filter and order top-level keys --- src/utils/generators.mjs | 95 +++++++++++++++++++++------------------- 1 file changed, 51 insertions(+), 44 deletions(-) diff --git a/src/utils/generators.mjs b/src/utils/generators.mjs index 22dfd8a0..87eaff95 100644 --- a/src/utils/generators.mjs +++ b/src/utils/generators.mjs @@ -113,52 +113,59 @@ export const leftHandAssign = (target, source) => /** * Transforms an object to JSON output consistent with the JSON version. * @param {Object} section - The source object + * @param section.api + * @param section.type + * @param section.source + * @param section.introduced_in + * @param section.meta + * @param section.stability + * @param section.stabilityText + * @param section.classes + * @param section.methods + * @param section.properties + * @param section.miscs + * @param section.modules + * @param section.globals * @returns {string} - The JSON output */ -export const legacyToJSON = section => +export const legacyToJSON = ({ + api, + type, + source, + introduced_in, + meta, + stability, + stabilityText, + classes, + methods, + properties, + miscs, + modules, + globals, +}) => JSON.stringify( - section, - // TODO: remove this array once all the additional keys have been introduced downstream - [ - // Top-level keys (order matter): - 'type', - 'source', - 'introduced_in', - 'meta', - 'stability', - 'stabilityText', - 'classes', - 'methods', - 'properties', - 'miscs', - ...(section.api === 'index' ? [] : ['modules']), - 'globals', - - // History section - 'added', - 'deprecated', - 'removed', - 'changes', - // Remaining keys - 'classMethods', - 'commit', - 'ctors', - 'default', - 'desc', - 'description', - 'displayName', - 'events', - 'examples', - 'name', - 'napiVersion', - 'options', - 'params', - 'pr-url', - 'return', - 'shortDesc', - 'signatures', - 'textRaw', - 'version', - ], + { + type, + source, + introduced_in, + ...(api === 'report' + ? { + stability, + stabilityText, + meta, + } + : { + meta, + stability, + stabilityText, + }), + classes, + methods, + properties, + miscs, + ...(api === 'index' ? undefined : { modules }), + globals, + }, + null, 2 );