From f89b0e798fce4a64e76ac131bc4ab9e3823efa01 Mon Sep 17 00:00:00 2001 From: botandbang <337765928+botandbang@users.noreply.github.com> Date: Wed, 28 Oct 2026 15:40:38 -0400 Subject: [PATCH] docs: publish API docs for every package with doc-kit --- .github/workflows/docs.yml | 65 ++++++++++++++++ README.md | 10 ++- aliases/README.md | 24 +----- core/README.md | 102 +------------------------ doc-kit.config.mjs | 92 ++++++++++++++++++++++ docs/pages/aliases.md | 36 +++++++++ docs/pages/core.md | 152 +++++++++++++++++++++++++++++++++++++ docs/pages/fetchindex.md | 33 ++++++++ docs/pages/index.md | 50 ++++++++++++ docs/pages/newest.md | 52 +++++++++++++ docs/pages/oldest.md | 52 +++++++++++++ docs/pages/opt.md | 33 ++++++++ docs/pages/parsefiles.md | 47 ++++++++++++ docs/pages/ranges.md | 117 ++++++++++++++++++++++++++++ docs/pages/static.md | 40 ++++++++++ docs/pages/translate.md | 34 +++++++++ docs/theme/Navigation.jsx | 40 ++++++++++ fetchindex/README.md | 23 +----- newest/README.md | 33 +------- oldest/README.md | 33 +------- opt/README.md | 31 +------- package.json | 10 ++- parsefiles/README.md | 45 +---------- ranges/README.md | 74 +----------------- static/README.md | 23 +----- translate/README.md | 50 +----------- 26 files changed, 897 insertions(+), 404 deletions(-) create mode 100644 .github/workflows/docs.yml create mode 100644 doc-kit.config.mjs create mode 100644 docs/pages/aliases.md create mode 100644 docs/pages/core.md create mode 100644 docs/pages/fetchindex.md create mode 100644 docs/pages/index.md create mode 100644 docs/pages/newest.md create mode 100644 docs/pages/oldest.md create mode 100644 docs/pages/opt.md create mode 100644 docs/pages/parsefiles.md create mode 100644 docs/pages/ranges.md create mode 100644 docs/pages/static.md create mode 100644 docs/pages/translate.md create mode 100644 docs/theme/Navigation.jsx diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..9e1d200 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,65 @@ +name: Docs + +on: + push: + branches: + - main + paths: &paths + - 'docs/**' + - 'doc-kit.config.mjs' + - 'package.json' + # the site shows core's version, which every release bumps + - 'core/package.json' + - '.github/workflows/docs.yml' + pull_request: + branches: + - main + paths: *paths + workflow_dispatch: + +permissions: {} + +# never cancel a deploy halfway; a PR's newer push replaces its older build +concurrency: + group: docs-${{ github.ref }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + +jobs: + build: + if: github.repository == 'cutenode/nodevu' + runs-on: ubuntu-latest + permissions: + contents: read + steps: + - name: Checkout the repository + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - name: Setup Node.js + uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0 + with: + node-version: lts/* + - name: Run npm install + run: npm install --workspaces=false + - name: Build the docs + run: npm run docs + - name: Upload the site + if: github.event_name != 'pull_request' + uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0 + with: + path: out + + deploy: + needs: build + if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main' + runs-on: ubuntu-latest + permissions: + pages: write # publish the site + id-token: write # prove the deployment comes from this workflow + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1 diff --git a/README.md b/README.md index 65127b4..445659c 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # nodevu -nodevu is a Node.js Version Utility meant to collect, merge, and reason about Node.js versions in a way that's explicitly developer friendly. +nodevu is a Node.js Version Utility meant to collect, merge, and reason about Node.js versions in a way that's explicitly developer friendly. Its docs live at [cutenode.github.io/nodevu](https://cutenode.github.io/nodevu/). nodevu is composed of a set of modules: @@ -17,3 +17,11 @@ nodevu is composed of a set of modules: - [parsefiles](./parsefiles/): this is a utility for parsing the `files` property of the [Node.js distributions JSON](https://nodejs.org/dist/index.json) file to understand the available files for any given set of identifiers from that list. It also provides additional, potentially useful information. - [opt](./opt/): this is a utility for generating a usable `options` for `@nodevu/core`. - [fetchindex](./fetchindex/): this is a utility for fetching `/dist/index.json` from `nodejs.org` for `@nodevu/core`. Might be useful for other projects. + +## Development + +- `npm test` and `npm run coverage` run every module's tests. +- `npm run lint` checks the whole repo with oxlint and oxfmt. +- `npm run docs:dev` builds the docs from `docs/pages/` with [doc-kit](https://doc-kit.nodejs.org/) and serves them locally. `npm run docs` only builds them, into `out/`. + +Merging to `main` publishes the docs to GitHub Pages. diff --git a/aliases/README.md b/aliases/README.md index ca4804a..2c25c9b 100644 --- a/aliases/README.md +++ b/aliases/README.md @@ -1,25 +1,9 @@ # @nodevu/aliases -This is a module that provides an array of aliases for ranges of Node.js release lines. +The names of the ranges of Node.js release lines that `@nodevu/ranges` works out. -## Usage - -```js -const aliases = require('@nodevu/aliases'); - -for (const alias of aliases) { - console.log(alias); -} +```bash +npm install @nodevu/aliases ``` -## API - -This module returns an `Array` of aliases: - -- 'alpha' - This represents the release line in its Alpha phase, if any. Starting with Node.js 27, each release line gets Alpha releases (`vN.0.0-alpha.X.Y.Z`) before its first Current release. -- 'current' - This represents the current Node.js release line. -- 'lts/latest' - This represents the latest LTS release line. -- 'lts/active' - This represents the active LTS release lines. -- 'lts/maintenance' - This represents the maintenance LTS release line, if any. -- 'eol' - This represents the End of Life release lines. -- 'all' - This represents all release lines. +Usage and the full API are in the [docs](https://cutenode.github.io/nodevu/aliases). diff --git a/core/README.md b/core/README.md index 5419747..e74c3d4 100644 --- a/core/README.md +++ b/core/README.md @@ -1,103 +1,9 @@ # @nodevu/core -The core, online-only utility of nodevu. +The core, online-only module of nodevu. It fetches the version information Node.js publishes and merges it into one object keyed by release line, with each line's phase, its newest and oldest LTS and security releases, and the files each release ships. -## Usage - -```js -const nodevu = require('@nodevu/core'); - -async function getData() { - const data = await nodevu(); // returns a lot of data! - console.log(data); -} - -getData(); +```bash +npm install @nodevu/core ``` -## API - -assuming you're requiring this module as `nodevu`: - -- `nodevu(options)` - returns a promise that resolves to a giant JSON blob of data. This is the default export. - - `options` (`Object`, optional): an `Object` of options to pass to the module. - - `fetch` (`Object`, optional): your chosen fetch implementation. Default: [Undici](https://github.com/nodejs/undici)'s fetch impelmentation. - - `now` (`String`, optional): a custom date `String` (ISO 8601) to do relative checks against. _Most likely_ only useful for internal testing. Default: `DateTime.now()` from [Luxon](https://moment.github.io/luxon/). - - `urls` (`Object`, optional): an `Object` that enables you to set custom values for the Node.js `index.json` file and `schedule.json` file. - - `index` (`String`, optional): a `String` that, if set, changes the URL that this module looks for the version index file at. This should be a _full_ URL that points to a JSON file. Default: `https://nodejs.org/dist/index.json`. - - `schedule` (`String`, optional): a `String` that, if set, changes the URL that this module looks for the Node.js release schedule file at. This should be a _full_ URL that points to a JSON file. Default: `https://raw.githubusercontent.com/nodejs/Release/master/schedule.json` . - -The data returned by this module follows a pretty specific structure. Here's a detailing of that structure: - -- Everything is within a top level `Object`. - - Every key in the`Object`is a semver major release line name with a 'v' prefix. Example: `v17`. Every value is an`Object`with the following properties: - - `releases` (`Object`) - an`Object`that is filled with all releases under the release line: - - Every key in the`Object`is a full Node.js release name. Example: `v17.6.0`. Every value is an`Object`with the following properties: - - `semver` (`Object`) - a small`Object`that gives semver information: - - `raw` (`String`) - the whole, raw version. - - `major` (`String`) - the semver major number. - - `minor` (`String`) - the semver minor number. - - `patch` (`String`) - the semver patch number. - - `line` (`String`) - the "name" of the release line. - - `releaseDate` (`String`) - the version's release date. - - `modules` (`Object`) - - `version` (`String`) - the ABI (Application Binary Interface) version number of Node.js, used to determine which version of Node.js compiled C++ add-on binaries can be loaded in to without needing to be re-compiled. - - `dependencies` (`Object`) - the bundled dependencies in this version of Node.js: - - `npm` (`String`) - version of the bundled npm. - - `v8` (`String`) - version of the bundled v8. - - `uv` (`String`) - version of the bundled libuv. - - `zlib` (`String`) - version of the bundled zlib. - - `openssl` (`String`) - version of the bundled openssl. - - `files` (`Object`) - an`Object`that provides context on the files available for the given release: - - `available` (`Array`) - the available files, as listed by the official [dist file](https://nodejs.org/dist/index.json). Every entry will be a String. - - `links` (`Object`) - an`Object`of the different potential links: - - `aix` (`Array`) - all AIX links (AIX is an IBM platform) links: - - `id` (`String`) - the initial identifier from `available` that was passed in. - - `files` (`Array`) - an `Array` of associated filenames for the ID. - - `architecture` (`String`) - the name of the architecture for the files in `files`. - - `headers` (`Array`) - all links to headers for the build: - - `id` (`String`) - the initial identifier from `available` that was passed in. - - `files` (`Array`) - an `Array` of associated filenames for the ID. - - `architecture` (`String`) - the name of the architecture for the files in `files`. - - `linux` (`Array`) - all the links to Linux distributions for the build: - - `id` (`String`) - the initial identifier from `available` that was passed in. - - `files` (`Array`) - an `Array` of associated filenames for the ID. - - `architecture` (`String`) - the name of the architecture for the files in `files`. - - `macos` (`Array`): - - `id` (`String`) - the initial identifier from `available` that was passed in. - - `files` (`Array`) - an `Array` of associated filenames for the ID. - - `architecture` (`String`) - the name of the architecture for the files in `files`. - - `source` (`Array`): - - `id` (`String`) - the initial identifier from `available` that was passed in. - - `files` (`Array`) - an `Array` of associated filenames for the ID. - - `architecture` (`String`) - the name of the architecture for the files in `files`. - - `windows` (`Array`): - - `id` (`String`) - the initial identifier from `available` that was passed in. - - `files` (`Array`) - An `Array` of associated filenames for the ID. - - `architecture` (`String`) - The name of the architecture for the files in `files`. - - `lts` (`Object`): - - `isLts`(Boolean) - `true` if the release is an LTS release, `false` if it's not. - - `alpha` (`Object`): - - `isAlpha` (Boolean) - `true` if the release is an Alpha release (like `v27.0.0-alpha.0.0.0`), `false` if it's not. - - `security` (`Object`): - - `isSecurity` (Boolean) - `true` if the release is a security release, `false` if it's not. - - `support` (`Object`) - An`Object`to provide information about the project's support of the given release line, including dates, status, LTS codename, and LTS version info: - - `codename` (`String`) - **Only present if applicable to the given release.** A `String` of the LTS release line's codename. - - `lts` (`Object`) - **Only present if the release line has an LTS date in schedule.json or a release flagged as LTS in index.json.** An`Object`that provides LTS versioning information. - - `newest` (`String`) - The newest release in the release line that is LTS. _Usually_, this will be the latest release in the line. - - `oldest` (`String`) - **Only present if applicable to the given release.** The oldest (first) release in the release line that was flagged as LTS. - - `phases` (`Object`) - Information about each phase of a release line's lifecycle: - - `dates` (`Object`) - Start dates for each phase of a release line's lifecycle: - - `alpha` (`String`) - **Only present if the release line has an Alpha phase.** The start date of the Alpha phase, before the first Current release of the release line (releases in this phase are `alpha`). Example: `2026-10-28`. - - `start` (`String`) - The start date of the release line's Current phase (releases in this phase are `current`). Example: `2021-04-20`. - - `lts` (`String`) - **Only present if the release line is an LTS release.** The start date of the LTS lifecycle (releases in this phase are `lts`). Example: `2021-10-26`. - - `maintenance` (`String`) - **Only present if the release line has a maintenance phase.** The start date of the maintenance phase of the lifecycle. Example: `2022-10-18`. - - `end` (`String`) - the date the release line is no longer supported. Example: `2024-04-30`. - - `current` (`String`) - The phase the release line is in, based on `now`: `alpha`, `start`, `lts`, `maintenance`, or `end`. An empty `Object` if no phase has started yet. - - `security` (`Object`): - - `all` (`Array`) - an `Array` of _all_ security releases in the release line. - - `newest` (`String`) - the newest (most recent) security release. Example: `17.3.1`. - -### Example output - -You can find an example of the output [here](https://gist.github.com/bnb/df2cd4329e9f402bbf8dc9bf8364aa34). It's big. Like, really big. GitHub will struggle to render it. It's probably worth viewing [raw](https://gist.githubusercontent.com/bnb/df2cd4329e9f402bbf8dc9bf8364aa34/raw/2602ad0738bb9b8d0f41c3ad110e8f8a58f12197/data.json) or curl'ing the raw output. +Usage and the full API are in the [docs](https://cutenode.github.io/nodevu/core). diff --git a/doc-kit.config.mjs b/doc-kit.config.mjs new file mode 100644 index 0000000..2152ada --- /dev/null +++ b/doc-kit.config.mjs @@ -0,0 +1,92 @@ +import { readFileSync } from 'node:fs'; +import { join } from 'node:path'; + +// every package is released together, so core's version is the docs' version +const { version } = JSON.parse( + readFileSync(join(import.meta.dirname, 'core', 'package.json'), 'utf8'), +); + +const repository = 'cutenode/nodevu'; + +const description = + 'nodevu collects, merges, and reasons about Node.js versions: release lines, LTS and security releases, support phases, and downloadable files.'; + +/** @type {import('@doc-kit/core/utils/configuration/types').Configuration} */ +export default { + target: ['html', 'orama-db', 'json', 'llms-txt', 'sitemap'], + + global: { + project: 'nodevu', + version, + repository, + ref: 'main', + baseURL: 'https://cutenode.github.io/nodevu', + input: ['docs/pages/**/*.md'], + output: 'out', + }, + + html: { + title: '{project} documentation', + + // all.html and 404.html load their assets from `/` unless URLs are + // absolute, which breaks under GitHub Pages' /nodevu/. CI builds what + // gets published; local builds stay relative so any static server works + useAbsoluteURLs: process.env.CI === 'true', + editURL: `https://github.com/${repository}/edit/main/docs/pages{path}.md`, + + // the default copies `static/` into the site, which here is the + // @nodevu/static workspace. copy the pages' Markdown instead, since + // llms.txt links to it + pathsToCopy: [{ [join(import.meta.dirname, 'docs', 'pages')]: '.' }], + + imports: { + '#theme/Navigation': join( + import.meta.dirname, + 'docs', + 'theme', + 'Navigation.jsx', + ), + }, + + navigation: { + sidebar: [ + { + groupName: 'Start', + items: [{ label: 'nodevu', link: '/index' }], + }, + { + groupName: 'Foundational modules', + items: [ + { label: '`@nodevu/core`', link: '/core' }, + { label: '`@nodevu/static`', link: '/static' }, + ], + }, + { + groupName: 'Utilities', + items: [ + { label: '`@nodevu/oldest`', link: '/oldest' }, + { label: '`@nodevu/newest`', link: '/newest' }, + { label: '`@nodevu/ranges`', link: '/ranges' }, + { label: '`@nodevu/aliases`', link: '/aliases' }, + { label: '`@nodevu/translate`', link: '/translate' }, + ], + }, + { + groupName: 'Helpers', + items: [ + { label: '`@nodevu/parsefiles`', link: '/parsefiles' }, + { label: '`@nodevu/opt`', link: '/opt' }, + { label: '`@nodevu/fetchindex`', link: '/fetchindex' }, + ], + }, + ], + }, + + head: { + meta: [ + { name: 'description', content: description }, + { property: 'og:description', content: description }, + ], + }, + }, +}; diff --git a/docs/pages/aliases.md b/docs/pages/aliases.md new file mode 100644 index 0000000..bc56bd6 --- /dev/null +++ b/docs/pages/aliases.md @@ -0,0 +1,36 @@ +# `@nodevu/aliases` + + + +The names of the ranges of Node.js release lines that +[`@nodevu/ranges`](ranges.md) works out. + +```bash +npm install @nodevu/aliases +``` + +The module exports an array of them: + +```js +const aliases = require('@nodevu/aliases'); + +aliases.includes('lts/active'); // true +``` + +## `aliases` + +- Type: {string[]} + +Every alias, in this order: + +- `'alpha'`: the release line in its Alpha phase, if any. Starting with + Node.js 27, each line gets Alpha releases (`vN.0.0-alpha.X.Y.Z`) before + its first Current release. +- `'current'`: the Current release line. +- `'lts/latest'`: the LTS release line in its LTS phase, before + maintenance. +- `'lts/active'`: the LTS release lines in their LTS or maintenance phase, + so `'lts/latest'` and `'lts/maintenance'` together. +- `'lts/maintenance'`: the LTS release lines in their maintenance phase. +- `'eol'`: the release lines past their end of life. +- `'all'`: every release line. diff --git a/docs/pages/core.md b/docs/pages/core.md new file mode 100644 index 0000000..ec088fd --- /dev/null +++ b/docs/pages/core.md @@ -0,0 +1,152 @@ +# `@nodevu/core` + + + +The core, online-only module of nodevu. It fetches the Node.js release index +and release schedule, then merges them into one object keyed by release line, +adding what it can work out from dates and release flags: the current phase of +each line, its newest and oldest LTS and security releases, and the files each +release ships. + +```bash +npm install @nodevu/core +``` + +Then call it for the data: + +```js +const nodevu = require('@nodevu/core'); + +const data = await nodevu(); + +console.log(data.v20.support.codename); // 'Iron' +``` + +## `nodevu([options])` + +- `options` {Object} + - `fetch` {Function} The `fetch` implementation to request the data with. + **Default:** `globalThis.fetch`. + - `now` {string} An ISO 8601 date to work out each release line's phase + against. A Luxon `DateTime` works too. Mostly useful for tests. + **Default:** `DateTime.now()` from [Luxon](https://moment.github.io/luxon/). + - `urls` {Object} + - `index` {string} The full URL of the release index. + **Default:** `'https://nodejs.org/dist/index.json'`. + - `schedule` {string} The full URL of the release schedule. + **Default:** `'https://raw.githubusercontent.com/nodejs/Release/master/schedule.json'`. +- Returns: {Promise} Fulfills with an object that has a key per + release line, newest first, such as `v22`, or `v0.10` for the `0.x` lines. Each value is + described in [Release lines](#release-lines). + +This is the module's only export. The result is large: every release Node.js +has published, with its dependencies and files. To read it without a network +request, use [`@nodevu/static`](static.md). + +## Release lines + +Each release line in the result has `releases` and `security`, and `support` +when the release schedule lists the line. + +### `line.releases` + +- Type: {Object} + +Every release in the line, newest first, keyed by version, such as `v17.6.0`. +Each value is described in [Releases](#releases). + +### `line.support` + +- Type: {Object} Only present when the release schedule has a start date for + the line. + - `codename` {string} The LTS codename, such as `'Iron'`. Only present on + lines that have one. + - `lts` {Object} Only present when the schedule has an LTS date for the + line, or the index flags one of its releases as LTS. + - `newest` {string} The newest LTS release, such as `'20.18.0'`. Usually + the newest release in the line. + - `oldest` {string} The first release flagged as LTS. + - `phases` {Object} + - `dates` {Object} The start date of each phase, such as `'2021-04-20'`. + A phase the line doesn't have is left out. + - `alpha` {string} The Alpha phase, before the first Current release. + - `start` {string} The Current phase. + - `lts` {string} The LTS phase. + - `maintenance` {string} The maintenance phase. + - `end` {string} The end of support. + - `current` {string|Object} The phase the line is in on `now`: `'alpha'`, + `'start'`, `'lts'`, `'maintenance'`, or `'end'`. An empty object when no + phase has started yet. + +### `line.security` + +- Type: {Object} + - `all` {string[]} Every security release in the line, newest first, such + as `['17.7.2', '17.3.1']`. + - `newest` {string} The newest security release. Not present when the line + has none. + - `oldest` {string} The oldest security release. Not present when the line + has none. + +## Releases + +Each release in [`line.releases`](#linereleases) has these properties. + +### `release.semver` + +- Type: {Object} + - `raw` {string} The version without its `v`, such as `'17.6.0'`. + - `major` {number} The major version. + - `minor` {number} The minor version. + - `patch` {number} The patch version. + - `line` {string} The name of the release line, such as `'v17'`. + +### `release.releaseDate` + +- Type: {string} The release date, such as `'2022-02-22'`. + +### `release.modules` + +- Type: {Object} + - `version` {string} The ABI version, which decides whether a compiled + native addon loads without being rebuilt. + +### `release.dependencies` + +- Type: {Object} The versions of the dependencies bundled with the release. + One the index doesn't list is `undefined`. + - `npm` {string} + - `v8` {string} + - `uv` {string} libuv. + - `zlib` {string} + - `openssl` {string} + +### `release.files` + +- Type: {Object} + - `available` {string[]} The file identifiers the index lists, such as + `'linux-x64'` or `'win-x64-msi'`. + - `links` {Object} The files of each identifier, grouped by type: `aix`, + `headers`, `linux`, `macos`, `source`, `sunos`, and `windows`. Only the + types the release has are present. Each one is an array of the objects + [`@nodevu/parsefiles`](parsefiles.md) returns, without their `type`: + - `id` {string} The identifier, such as `'linux-x64'`. + - `files` {string[]} The file names for the identifier. + - `architecture` {string} The architecture, such as `'x64'`. + +### `release.lts` + +- Type: {Object} + - `isLts` {boolean} Whether the index flags the release as LTS. + +### `release.alpha` + +- Type: {Object} + - `isAlpha` {boolean} Whether the release is an Alpha release, such as + `v27.0.0-alpha.0.0.0`. + +### `release.security` + +- Type: {Object} + - `isSecurity` {boolean} Whether the index flags the release as a security + release. diff --git a/docs/pages/fetchindex.md b/docs/pages/fetchindex.md new file mode 100644 index 0000000..9c2f47c --- /dev/null +++ b/docs/pages/fetchindex.md @@ -0,0 +1,33 @@ +# `@nodevu/fetchindex` + + + +Fetches the [Node.js release index](https://nodejs.org/dist/index.json), the +list of every Node.js release with its date, bundled dependencies, files, and +LTS and security flags. + +```bash +npm install @nodevu/fetchindex +``` + +It has no defaults, so pass the `fetch` to use and the URL: + +```js +const fetchindex = require('@nodevu/fetchindex'); + +const index = await fetchindex({ + fetch: globalThis.fetch, + urls: { index: 'https://nodejs.org/dist/index.json' }, +}); +``` + +## `fetchindex(options)` + +- `options` {Object} + - `fetch` {Function} The `fetch` implementation to use. + - `urls` {Object} + - `index` {string} The full URL of the release index. +- Returns: {Promise} Fulfills with the parsed index, newest release + first. + +[`@nodevu/opt`](opt.md) builds options with both set. diff --git a/docs/pages/index.md b/docs/pages/index.md new file mode 100644 index 0000000..4a67fbb --- /dev/null +++ b/docs/pages/index.md @@ -0,0 +1,50 @@ +# nodevu + + + +nodevu is a Node.js version utility: it collects, merges, and reasons about +Node.js versions in a way that's developer friendly. It's a set of small +modules, so you install only the ones you need. + +```bash +npm install @nodevu/core +``` + +Then ask it about any release line: + +```js +const nodevu = require('@nodevu/core'); + +const data = await nodevu(); + +console.log(data.v20.support.lts.newest); +``` + +## Foundational modules + +- [`@nodevu/core`](core.md): the online-only core. It fetches the version + information Node.js publishes and merges it into one object, adding what it + can work out from dates and release flags. +- [`@nodevu/static`](static.md): the offline version of core. It ships core's + data, and a few subsets of it, as JSON that's updated on a schedule. + +## Utilities + +- [`@nodevu/oldest`](oldest.md): the oldest LTS or security release of a + release line. +- [`@nodevu/newest`](newest.md): the newest LTS or security release of a + release line. +- [`@nodevu/ranges`](ranges.md): ranges of Node.js versions, such as every + release of the active LTS lines. +- [`@nodevu/aliases`](aliases.md): the names of those ranges. +- [`@nodevu/translate`](translate.md): translates the terms the Node.js + project proposed for the `support` property in `package.json` to aliases. + +## Helpers + +- [`@nodevu/parsefiles`](parsefiles.md): parses the `files` identifiers of a + release in the [Node.js release index](https://nodejs.org/dist/index.json) + into file names. +- [`@nodevu/opt`](opt.md): builds the options `@nodevu/core` takes, with + their defaults. +- [`@nodevu/fetchindex`](fetchindex.md): fetches the Node.js release index. diff --git a/docs/pages/newest.md b/docs/pages/newest.md new file mode 100644 index 0000000..42ae32e --- /dev/null +++ b/docs/pages/newest.md @@ -0,0 +1,52 @@ +# `@nodevu/newest` + + + +Finds the newest LTS or security release of a Node.js release line. + +```bash +npm install @nodevu/newest +``` + +Pass it the name of a release line: + +```js +const { lts, security } = require('@nodevu/newest'); + +await lts('v16'); // '16.20.2' +await security('v16'); // '16.20.2' +``` + +Every function fetches fresh data through [`@nodevu/core`](core.md), and +fulfills with `undefined` when there's no such release: the line has no LTS +releases (like `v25` or `v0.10`), no security releases (like `v5`), or +doesn't exist (like `v999`). [`@nodevu/oldest`](oldest.md) finds the oldest +ones. + +## `newest(name, type[, options])` + +- `name` {string} The release line, such as `'v16'` or `'v0.10'`. +- `type` {string} `'lts'` or `'security'`. Any other value fulfills with + `undefined`. +- `options` {Object} Passed to [`nodevu()`](core.md#nodevuoptions), to set a + custom `fetch` or `now`. +- Returns: {Promise} Fulfills with the version, without its + `v`. + +## `lts(name[, options])` + +- `name` {string} The release line, such as `'v16'`. +- `options` {Object} Passed to [`nodevu()`](core.md#nodevuoptions). +- Returns: {Promise} Fulfills with the newest LTS release + of the line. + +Same as `newest(name, 'lts', options)`. + +## `security(name[, options])` + +- `name` {string} The release line, such as `'v16'`. +- `options` {Object} Passed to [`nodevu()`](core.md#nodevuoptions). +- Returns: {Promise} Fulfills with the newest security + release of the line. + +Same as `newest(name, 'security', options)`. diff --git a/docs/pages/oldest.md b/docs/pages/oldest.md new file mode 100644 index 0000000..04bcd84 --- /dev/null +++ b/docs/pages/oldest.md @@ -0,0 +1,52 @@ +# `@nodevu/oldest` + + + +Finds the oldest LTS or security release of a Node.js release line. + +```bash +npm install @nodevu/oldest +``` + +Pass it the name of a release line: + +```js +const { lts, security } = require('@nodevu/oldest'); + +await lts('v16'); // '16.13.0' +await security('v16'); // '16.4.1' +``` + +Every function fetches fresh data through [`@nodevu/core`](core.md), and +fulfills with `undefined` when there's no such release: the line has no LTS +releases (like `v25` or `v0.10`), no security releases (like `v5`), or +doesn't exist (like `v999`). [`@nodevu/newest`](newest.md) finds the newest +ones. + +## `oldest(name, type[, options])` + +- `name` {string} The release line, such as `'v16'` or `'v0.10'`. +- `type` {string} `'lts'` or `'security'`. Any other value fulfills with + `undefined`. +- `options` {Object} Passed to [`nodevu()`](core.md#nodevuoptions), to set a + custom `fetch` or `now`. +- Returns: {Promise} Fulfills with the version, without its + `v`. + +## `lts(name[, options])` + +- `name` {string} The release line, such as `'v16'`. +- `options` {Object} Passed to [`nodevu()`](core.md#nodevuoptions). +- Returns: {Promise} Fulfills with the first release of the + line flagged as LTS. + +Same as `oldest(name, 'lts', options)`. + +## `security(name[, options])` + +- `name` {string} The release line, such as `'v16'`. +- `options` {Object} Passed to [`nodevu()`](core.md#nodevuoptions). +- Returns: {Promise} Fulfills with the oldest security + release of the line. + +Same as `oldest(name, 'security', options)`. diff --git a/docs/pages/opt.md b/docs/pages/opt.md new file mode 100644 index 0000000..1068bc8 --- /dev/null +++ b/docs/pages/opt.md @@ -0,0 +1,33 @@ +# `@nodevu/opt` + + + +Builds the options [`@nodevu/core`](core.md) takes, filling in a default for +each one you leave out. + +> [!NOTE] +> This module isn't published to npm yet. + +Call it with the options to override: + +```js +const opt = require('@nodevu/opt'); + +const options = opt({ + urls: { index: 'https://example.com/index.json' }, +}); +``` + +## `opt([options])` + +- `options` {Object} + - `fetch` {Function} The `fetch` implementation to use. + **Default:** `globalThis.fetch`. + - `now` {string} An ISO 8601 date, or a Luxon `DateTime`. + **Default:** `DateTime.now()` from [Luxon](https://moment.github.io/luxon/). + - `urls` {Object} + - `index` {string} The full URL of the release index. + **Default:** `'https://nodejs.org/dist/index.json'`. + - `schedule` {string} The full URL of the release schedule. + **Default:** `'https://raw.githubusercontent.com/nodejs/Release/master/schedule.json'`. +- Returns: {Object} The same shape, with every field set. diff --git a/docs/pages/parsefiles.md b/docs/pages/parsefiles.md new file mode 100644 index 0000000..e683e21 --- /dev/null +++ b/docs/pages/parsefiles.md @@ -0,0 +1,47 @@ +# `@nodevu/parsefiles` + + + +Parses an identifier from the `files` of a release in the +[Node.js release index](https://nodejs.org/dist/index.json), such as +`linux-x64` or `osx-arm64-tar`, into the file names it stands for, its +platform, and its architecture. [`@nodevu/core`](core.md) uses it for +[`release.files`](core.md#releasefiles). + +```bash +npm install @nodevu/parsefiles +``` + +Pass it an identifier and the version it belongs to: + +```js +const parsefiles = require('@nodevu/parsefiles'); + +parsefiles('linux-x64', '17.6.0'); +// { +// id: 'linux-x64', +// files: ['node-v17.6.0-linux-x64.tar.gz', 'node-v17.6.0-linux-x64.tar.xz'], +// type: 'linux', +// architecture: 'x64', +// } +``` + +## `parsefiles(file, version)` + +- `file` {string} An identifier from the release's `files`, such as + `'win-x64-msi'`. +- `version` {string} The release's version, without its `v`, such as + `'17.6.0'`. +- Returns: {Object} + - `id` {string} The identifier passed in. + - `files` {string[]} The file names that should exist for the identifier. + There's often more than one. + - `type` {string} The platform, or what kind of files these are: `'aix'`, + `'headers'`, `'linux'`, `'macos'`, `'source'`, `'sunos'`, or + `'windows'`. + - `architecture` {string} The architecture, such as `'x64'`, `'x86'`, + `'arm64'`, `'armv7l'`, `'armv6l'`, `'power'`, or `'z'`. Not present for + identifiers without one, like `'src'` and `'headers'`. + +The file names follow the patterns nodejs.org has used so far. New kinds of +identifiers can show up in the index before this module knows them. diff --git a/docs/pages/ranges.md b/docs/pages/ranges.md new file mode 100644 index 0000000..aca1499 --- /dev/null +++ b/docs/pages/ranges.md @@ -0,0 +1,117 @@ +# `@nodevu/ranges` + + + +Works out ranges of Node.js versions, such as every release of the Current +line or of the active LTS lines, with the newest and oldest releases of each. +The ranges are named by the aliases of [`@nodevu/aliases`](aliases.md). + +```bash +npm install @nodevu/ranges +``` + +Ask for one range, several, or all of them: + +```js +const ranges = require('@nodevu/ranges'); + +const data = await ranges(['current', 'lts/active']); + +console.log(data.current.newest); +``` + +## `ranges([filter[, options]])` + +- `filter` {string|string[]} One or more [aliases](aliases.md) to work out. + **Default:** `'all'`, which works out every range. +- `options` {Object} Passed to [`nodevu()`](core.md#nodevuoptions), to set a + custom `fetch` or `now`. +- Returns: {Promise} Fulfills with an object that has a key per + range, described in [Ranges](#ranges). A range with no releases is left + out. + +Rejects with an {Error} when `filter` holds an unknown alias, or is neither a +string nor an array. + +```js +const data = await ranges('alpha', { now: '2026-12-15' }); +``` + +## Ranges + +Each range has the versions in it, newest first, and the newest and oldest +of them. A field with nothing to point to, like `oldestSecurity` on a line +that hasn't had a security release, is `undefined`, and left out of JSON. + +The releases in `versions`, and `newest`, `oldest`, `newestLts`, and +`newestSecurity` in the `all` range, are versions with a `v`, such as +`'v20.18.0'`. The other LTS and security fields come from +[`@nodevu/core`](core.md#linesupport), without one, such as `'20.9.0'`. + +### `data.all` + +- Type: {Object} + - `versions` {string[]} Every release, except Alpha releases. + - `newestLts` {string} The newest LTS release. + - `newestSecurity` {string} The newest security release. + - `newest` {string} The newest release. + - `oldest` {string} The oldest release. + +### `data.alpha` + +- Type: {Object} + - `versions` {string[]} The Alpha releases (`vN.0.0-alpha.X.Y.Z`) of the + line in its Alpha phase. Alpha releases are only ever in this range. + - `newest` {string} The newest release. + - `oldest` {string} The oldest release. + +### `data.current` + +- Type: {Object} + - `versions` {string[]} The releases of the Current line. + - `oldestSecurity` {string} The oldest security release of the line. + - `newestSecurity` {string} The newest security release of the line. + - `newest` {string} The newest release. + - `oldest` {string} The oldest release. + +### `data['lts/latest']` + +- Type: {Object} + - `versions` {string[]} The LTS releases of the line in its LTS phase. + - `oldestLts` {string} The first LTS release of the line. + - `oldestSecurity` {string} The oldest security release of the line. + - `newestLts` {string} The newest LTS release of the line. + - `newestSecurity` {string} The newest security release of the line. + - `newest` {string} The newest release. + - `oldest` {string} The oldest release. + +### `data['lts/active']` + +- Type: {Object} + - `versions` {string[]} The releases of `lts/latest`, then those of + `lts/maintenance`. + - `oldestLts` {string} The `oldestLts` of `lts/maintenance`. + - `oldestSecurity` {string} The `oldestSecurity` of `lts/maintenance`. + - `newestLts` {string} The `newestLts` of `lts/latest`. + - `newestSecurity` {string} The `newestSecurity` of `lts/latest`. + - `newest` {string} The newest release. + - `oldest` {string} The oldest release. + +### `data['lts/maintenance']` + +- Type: {Object} + - `versions` {string[]} The LTS releases of the lines in their maintenance + phase. + - `oldestLts` {string} The first LTS release of the oldest line. + - `oldestSecurity` {string} The oldest security release of the oldest line. + - `newestLts` {string} The newest LTS release of the newest line. + - `newestSecurity` {string} The newest security release of the newest line. + - `newest` {string} The newest release. + - `oldest` {string} The oldest release. + +### `data.eol` + +- Type: {Object} + - `versions` {string[]} The releases of the lines past their end of life. + - `newest` {string} The newest release. + - `oldest` {string} The oldest release. diff --git a/docs/pages/static.md b/docs/pages/static.md new file mode 100644 index 0000000..f00a976 --- /dev/null +++ b/docs/pages/static.md @@ -0,0 +1,40 @@ +# `@nodevu/static` + + + +The offline version of nodevu: the data [`@nodevu/core`](core.md) returns, +and three subsets of it, shipped as JSON. A scheduled build refreshes the data +and a release publishes it, so it can lag behind Node.js releases. Use +`@nodevu/core` when you need it current. + +```bash +npm install @nodevu/static +``` + +Each export is a plain object, keyed by release line like core's result: + +```js +const { default: data, support } = require('@nodevu/static'); + +console.log(support.v20.codename); // 'Iron' +``` + +## `static.default` + +- Type: {Object} Everything [`nodevu()`](core.md#nodevuoptions) returns. + The largest export. + +## `static.releases` + +- Type: {Object} The [`releases`](core.md#linereleases) of each release line, + such as `releases.v17['v17.6.0']`. + +## `static.security` + +- Type: {Object} The [`security`](core.md#linesecurity) object of each + release line. + +## `static.support` + +- Type: {Object} The [`support`](core.md#linesupport) object of each release + line. A line the release schedule doesn't list has none. diff --git a/docs/pages/translate.md b/docs/pages/translate.md new file mode 100644 index 0000000..d3da025 --- /dev/null +++ b/docs/pages/translate.md @@ -0,0 +1,34 @@ +# `@nodevu/translate` + + + +Translates the terms of the Node.js Package Maintenance working group's +[package support document](https://github.com/nodejs/package-maintenance/blob/main/docs/PACKAGE-SUPPORT.md) +to the aliases [`@nodevu/ranges`](ranges.md) takes. + +> [!NOTE] +> This module isn't published to npm yet. + +Pass the result straight to `ranges()`: + +```js +const ranges = require('@nodevu/ranges'); +const translate = require('@nodevu/translate'); + +const supported = await ranges(await translate('supported')); +``` + +## `translate(alias)` + +- `alias` {string} A package support term. +- Returns: {Promise} Fulfills with the aliases it covers. + +Rejects with an {Error} for any other term. The terms translate to: + +| Term | Aliases | +| ------------ | ----------------------------------------------------- | +| `current` | `['current']` | +| `lts_latest` | `['lts/latest']` | +| `lts` | `['lts/active', 'lts/maintenance']` | +| `supported` | `['current', 'lts/active', 'lts/maintenance']` | +| `all` | `['current', 'lts/active', 'lts/maintenance', 'eol']` | diff --git a/docs/theme/Navigation.jsx b/docs/theme/Navigation.jsx new file mode 100644 index 0000000..3110dca --- /dev/null +++ b/docs/theme/Navigation.jsx @@ -0,0 +1,40 @@ +import SearchBox from '@doc-kit/generator-react/html/ui/components/SearchBox/index.jsx'; +import ThemeToggle from '@doc-kit/generator-react/html/ui/components/ThemeToggle.jsx'; +import { relativeOrAbsolute } from '@doc-kit/generator-react/html/ui/utils/relativeOrAbsolute.mjs'; +import NavBar from '@node-core/ui-components/Containers/NavBar'; +import GitHubIcon from '@node-core/ui-components/Icons/Social/GitHub'; + +import { repository, showSearchBox } from '#theme/config'; +import Logo from '#theme/Logo'; + +import styles from '@node-core/ui-components/Containers/NavBar/index.module.css'; + +// doc-kit's navigation bar, except the logo links to the site's index +// relative to the page. the NavBar links it to `/`, which leaves the site +// when it's served from a subpath, like GitHub Pages' /nodevu/ +export default ({ metadata }) => { + const home = `${relativeOrAbsolute('/index', metadata.path)}.html`; + + const Link = ({ href, ...props }) => ( + + ); + + return ( + + {showSearchBox && } + + + + + + ); +}; diff --git a/fetchindex/README.md b/fetchindex/README.md index cfa0b3c..2c2b3c7 100644 --- a/fetchindex/README.md +++ b/fetchindex/README.md @@ -1,24 +1,9 @@ # @nodevu/fetchindex -A tool that fetches the /dist/index.json file from the Node.js website. +Fetches the [Node.js release index](https://nodejs.org/dist/index.json), the list of every Node.js release. -## Usage - -```js -const fetchindex = require('@nodevu/fetchindex'); - -const options = { - fetch: globalThis.fetch, // use your own fetch if you want! - urls: { - index: 'https://nodejs.org/dist/index.json', - }, -}; - -const index = await fetchindex(options); // returns a huge JSON object +```bash +npm install @nodevu/fetchindex ``` -## API - -- `fetchindex(options)` - - `options` (object): Options object. - `fetch` (function): Fetch function. Default: `globalThis.fetch`. - `urls` (object): URLs object. - `index` (string): URL to fetch the index.json file from. Default: `'https://nodejs.org/dist/index.json'`. - - Returns: Promise that resolves with the fetched `index.json` object. +Usage and the full API are in the [docs](https://cutenode.github.io/nodevu/fetchindex). diff --git a/newest/README.md b/newest/README.md index 48eea58..35f5f8b 100644 --- a/newest/README.md +++ b/newest/README.md @@ -1,34 +1,9 @@ # @nodevu/newest -A module that returns newest LTS or Security release of a given Node.js release line. +Finds the newest LTS or security release of a Node.js release line. -## Usage - -```js -const { newest } = require('@nodevu/newest'); - -const newestLts = await newest('v16', 'lts'); -const newestSecurity = await newest('v16', 'security'); +```bash +npm install @nodevu/newest ``` -```js -const { lts, security } = require('@nodevu/newest'); - -const newestLts = await lts('v16'); -const newestSecurity = await security('v16'); -``` - -## API - -This module exports three async functions. Each one resolves to a version string like `16.20.2`, or `undefined` if there isn't one: the release line has no LTS releases (like `v25` or `v0.10`), no security releases (like `v5`), or doesn't exist (like `v999`). - -- `newest(name, type, options)` - - `name` (string): Node.js release line name. Examples: `v16`, `v11`, `v8`, `v0.10`. - - `type` (string): `lts` or `security`. - - `options` (object, optional): passed straight to [@nodevu/core](../core/), so you can set things like a custom `fetch` or `now`. -- `lts(name, options)` - - `name` (string): Node.js release line name. Examples: `v16`, `v11`, `v8`, `v0.10`. - - `options` (object, optional): same as above. -- `security(name, options)` - - `name` (string): Node.js release line name. Examples: `v16`, `v11`, `v8`, `v0.10`. - - `options` (object, optional): same as above. +Usage and the full API are in the [docs](https://cutenode.github.io/nodevu/newest). diff --git a/oldest/README.md b/oldest/README.md index 11a527a..a648f05 100644 --- a/oldest/README.md +++ b/oldest/README.md @@ -1,34 +1,9 @@ # @nodevu/oldest -A module that returns oldest LTS or Security release of a given Node.js release line. +Finds the oldest LTS or security release of a Node.js release line. -## Usage - -```js -const { oldest } = require('@nodevu/oldest'); - -const oldestLts = await oldest('v16', 'lts'); -const oldestSecurity = await oldest('v16', 'security'); +```bash +npm install @nodevu/oldest ``` -```js -const { lts, security } = require('@nodevu/oldest'); - -const oldestLts = await lts('v16'); -const oldestSecurity = await security('v16'); -``` - -## API - -This module exports three async functions. Each one resolves to a version string like `16.13.0`, or `undefined` if there isn't one: the release line has no LTS releases (like `v25` or `v0.10`), no security releases (like `v5`), or doesn't exist (like `v999`). - -- `oldest(name, type, options)` - - `name` (string): Node.js release line name. Examples: `v16`, `v11`, `v8`, `v0.10`. - - `type` (string): `lts` or `security`. - - `options` (object, optional): passed straight to [@nodevu/core](../core/), so you can set things like a custom `fetch` or `now`. -- `lts(name, options)` - - `name` (string): Node.js release line name. Examples: `v16`, `v11`, `v8`, `v0.10`. - - `options` (object, optional): same as above. -- `security(name, options)` - - `name` (string): Node.js release line name. Examples: `v16`, `v11`, `v8`, `v0.10`. - - `options` (object, optional): same as above. +Usage and the full API are in the [docs](https://cutenode.github.io/nodevu/oldest). diff --git a/opt/README.md b/opt/README.md index 7363ce7..5f49400 100644 --- a/opt/README.md +++ b/opt/README.md @@ -1,30 +1,5 @@ -# @nodevu/optionsparser +# @nodevu/opt -A tool that fetches the /dist/index.json file from the Node.js website. +Builds the options `@nodevu/core` takes, filling in a default for each one you leave out. Not published to npm yet. -## Usage - -```js -const opt = require('@nodevu/opt'); - -const parsedOptions = await opt(); // returns a default set of options -``` - -```js -const opt = require('@nodevu/opt'); - -const options = { - fetch: globalThis.fetch, // use your own fetch if you want! - urls: { - index: 'https://nodejs.org/dist/index.json', - }, -}; - -const parsedOptions = await parser(options); // returns a huge JSON object -``` - -## API - -- `opt(options)` - - `options` (`Object`, optional): Options object. - `fetch` (`Function`, optional): Fetch function. Default: `globalThis.fetch`. - `urls` (`Object`, optional): URLs object. - `index` (`String`, optional): URL to fetch the index.json file from. Default: `'https://nodejs.org/dist/index.json'`. - `schedule` (`String`, optional): URL to fetch the schedule.json file from. Default: `'https://raw.githubusercontent.com/nodejs/Release/master/schedule.json'`. - - Returns: `Object` with a set of default options in the structure required by `@nodevu/core`. +Usage and the full API are in the [docs](https://cutenode.github.io/nodevu/opt). diff --git a/package.json b/package.json index c963d51..a395708 100644 --- a/package.json +++ b/package.json @@ -8,7 +8,9 @@ "lint:write": "oxlint --fix && oxfmt", "coverage": "npm run coverage --ws --if-present", "test": "npm run test --ws", - "updates": "npm run updates --ws" + "updates": "npm run updates --ws", + "docs": "doc-kit generate", + "docs:dev": "doc-kit generate && sirv out --dev" }, "repository": { "type": "git", @@ -37,8 +39,12 @@ "opt" ], "devDependencies": { + "@doc-kit/cli": "1.0.5", + "@doc-kit/generator-react": "0.5.0", + "@node-core/ui-components": "1.8.1", "@oxlint/plugins": "1.89.0", "oxfmt": "0.74.0", - "oxlint": "1.89.0" + "oxlint": "1.89.0", + "sirv-cli": "3.0.1" } } diff --git a/parsefiles/README.md b/parsefiles/README.md index 4eaea6c..fdcf691 100644 --- a/parsefiles/README.md +++ b/parsefiles/README.md @@ -1,46 +1,9 @@ # @nodevu/parsefiles -a utility to parse Node.js's files information from distribution metadata into something more useful. +Parses an identifier from the `files` of a release in the [Node.js release index](https://nodejs.org/dist/index.json), such as `linux-x64`, into the file names it stands for, its platform, and its architecture. -## Usage - -```js -const parsefiles = require('@nodevu/parsefiles'); - -const version = '17.6.0'; -const files = [ - 'aix-ppc64', - 'headers', - 'linux-arm64', - 'linux-armv7l', - 'linux-ppc64le', - 'linux-s390x', - 'linux-x64', - 'osx-arm64-tar', - 'osx-x64-pkg', - 'osx-x64-tar', - 'src', - 'win-x64-7z', - 'win-x64-exe', - 'win-x64-msi', - 'win-x64-zip', - 'win-x86-7z', - 'win-x86-exe', - 'win-x86-msi', - 'win-x86-zip', -]; - -files.forEach((file) => { - const data = parsefiles(file, version); - console.log(data); -}); +```bash +npm install @nodevu/parsefiles ``` -## The Data - -When run, `@nodevu/parsefiles` will return an object with the following properties: - -- `id` (String) - the identifier (file) that was passed in. Examples: `aix-ppc64`, `linux-x64`, `osx-x64-pkg`, `osx-arm64-tar`, `win-x64-zip`, `src`, `headers`. -- `files` (Array) - an array of filenames that _should_ exist for the release. There are often more than one. -- `type` (String) - indicates either the operating system, or that the files are source/headers, parsed out of the `id`. Examples: `linux`, `macos`, `windows`, `aix`, `sunos`, `source`, `headers`. -- `architecture` (String) - a string that represents the architecture of the files. Examples: `x86`, `x64`, `arm64`, `armv7l`, `armv6l`, `power`, `z` +Usage and the full API are in the [docs](https://cutenode.github.io/nodevu/parsefiles). diff --git a/ranges/README.md b/ranges/README.md index cfa0986..2168f3c 100644 --- a/ranges/README.md +++ b/ranges/README.md @@ -1,75 +1,9 @@ # @nodevu/ranges -a module that provides information about ranges of Node.js versions. +Works out ranges of Node.js versions, such as every release of the Current line or of the active LTS lines, with the newest and oldest releases of each. -## Usage - -```js -const ranges = require('@nodevu/ranges'); - -async function generateData() { - const data = await ranges(); - - console.log(data); // will be a chunky object! -} -``` - -## API - -### `ranges(filter, options)` - -- `filter` (String or Array, optional): one or more aliases from [@nodevu/aliases](../aliases/) to limit the result to. Defaults to `'all'`, which returns every range. -- `options` (Object, optional): passed straight to [@nodevu/core](../core/), so you can set things like a custom `fetch` or `now`. - -```js -const data = await ranges('alpha', { now: '2026-12-15' }); +```bash +npm install @nodevu/ranges ``` -## Structure - -This module will return a medium-sized object with the following structure, with each property being in the context of the range it's under. A field with nothing to point to, like `oldestSecurity` on a release line that hasn't had a security release yet, is `undefined` (and left out of JSON). - -- all: - - versions (Array): An array of versions. Leaves out Alpha releases. - - newestLts (String): The newest LTS version. - - newestSecurity (String): The newest possible security release. - - newest (String): The newest version. - - oldest (String): The oldest version. -- alpha: - - versions (Array): An array of the Alpha releases (`vN.0.0-alpha.X.Y.Z`) of the release line in its Alpha phase. Alpha releases only ever show up here, never in the other ranges. - - newest (String): The newest version. - - oldest (String): The oldest version. -- current: - - versions (Array): An array of versions. - - oldestSecurity (String): The oldest security release. - - newestSecurity (String): The newest possible security release. - - newest (String): The newest version. - - oldest (String): The oldest version. -- lts/latest: - - versions (Array): An array of versions. - - oldestLts (String): The oldest LTS release. - - oldestSecurity (String): The oldest security release. - - newestLts (String): The newest LTS version. - - newestSecurity (String): The newest possible security release. - - newest (String): The newest version. - - oldest (String): The oldest version. -- lts/active: - - versions (Array): An array of versions. - - oldestLts (String): The oldest LTS release. - - oldestSecurity (String): The oldest security release. - - newestLts (String): The newest LTS version. - - newestSecurity (String): The newest possible security release. - - newest (String): The newest version. - - oldest (String): The oldest version. -- lts/maintenance: - - versions (Array): An array of versions. - - oldestLts (String): The oldest LTS release. - - oldestSecurity (String): The oldest security release. - - newestLts (String): The newest LTS version. - - newestSecurity (String): The newest possible security release. - - newest (String): The newest version. - - oldest (String): The oldest version. -- eol: - - versions (Array): An array of versions. - - newest (String): The newest version. - - oldest (String): The oldest version. +Usage and the full API are in the [docs](https://cutenode.github.io/nodevu/ranges). diff --git a/static/README.md b/static/README.md index db16a86..48071f5 100644 --- a/static/README.md +++ b/static/README.md @@ -1,24 +1,9 @@ # @nodevu/static -Static nodevu data. Automatically updated on some kind of schedule. +The offline version of nodevu: the data `@nodevu/core` returns, and a few subsets of it, shipped as JSON that's refreshed on a schedule. -## Usage - -```js -const { default, releases, security, support } = require('@nodevu/static') - -// each of these is a giant JSON blob. default is most giant, followed by releases. Security and support are relatively small. -console.log(default) -console.log(releases) -console.log(security) -console.log(support) +```bash +npm install @nodevu/static ``` -## API - -This module has four exports: - -- `default` (Object) - the default, full set of data returned by [`@nodevu/core`](https://github.com/nodevu/core)). -- `releases` (Object) - only the `releases` properties from the default set of data returned by [`@nodevu/core`](https://github.com/nodevu/core)), following the same heirarchy. -- `security` - only the `security` properties from the default set of data returned by [`@nodevu/core`](https://github.com/nodevu/core)), following the same heirarchy. -- `support` - only the `support` properties from the default set of data returned by [`@nodevu/core`](https://github.com/nodevu/core)), following the same heirarchy. +Usage and the full API are in the [docs](https://cutenode.github.io/nodevu/static). diff --git a/translate/README.md b/translate/README.md index 3159352..8733b4c 100644 --- a/translate/README.md +++ b/translate/README.md @@ -1,51 +1,5 @@ # @nodevu/translate -A translation layer to use the terms previously defined by the Node.js Package Maintenance WG's [Package Support document](https://github.com/nodejs/package-maintenance/blob/main/docs/PACKAGE-SUPPORT.md) to terms that can easily be used by [@nodevu/ranges](https://npm.im/@nodevu/ranges). +Translates the terms of the Node.js Package Maintenance working group's [package support document](https://github.com/nodejs/package-maintenance/blob/main/docs/PACKAGE-SUPPORT.md) to the aliases `@nodevu/ranges` takes. Not published to npm yet. -## Usage - -```js -const ranges = require('@nodevu/ranges'); -const translate = require('@nodevu/translate'); - -async function getTranslatedData() { - // translation for the 'current' Package Support term - const current = await ranges(await translate('current')); - - // translation for the 'lts_latest' Package Support term - const lts_latest = await ranges(await translate('lts_latest')); - - // translation for the 'lts' Package Support term - const lts = await ranges(await translate('lts')); - - // translation for the 'supported' Package Support term - const supported = await ranges(await translate('supported')); - - // translation for the 'all' Package Support term - const all = await ranges(await translate('all')); - - // return the data in a single object - return { - current, - lts_latest, - lts, - supported, - all, - }; -} - -getTranslatedData().then(console.log); -``` - -## API - -- `translate(alias)` - - `alias` (string): A Node.js Package Support Alias. - -Possible values for `alias`: - -- `current`: returns `['current']` -- `lts_latest`: returns `['lts/latest']` -- `lts`: returns `['lts/active', 'lts/maintenance']` -- `supported`: returns `['current', 'lts/active', 'lts/maintenance']` -- `all`: returns `['current', 'lts/active', 'lts/maintenance', 'eol']` +Usage and the full API are in the [docs](https://cutenode.github.io/nodevu/translate).