Node Release Lines

Introspection API for Node.js release metadata. Provides information about release lines, their relative status along with details of each release.

See how release lines work for more context.

Currently optimized for offline mode. Release schedule has apis to support both online & offline mode.

Installation

npm install node-release-lines

Outline

Command Line
Terminology
ReleaseLine class
ReleaseLines extends Array class
Release class
Releases extends Array class
Vulnerability class
ChangeLog class
Commit class

Usage

const { ReleaseLines } = require('node-release-lines')

const releases = ReleaseLines.load('2018-09-15') // state of release lines at a point in time

if (releases.getLTS().length === 4 && // LTS release lines
    releases.getEOL().length === 6 && // release lines that have reached EOL (end of life)
    releases.getEOL().getModern().length === 4 && // "modern" EOL release lines
    releases.getEOL().getLTS().length === 1) { // LTS release lines that are EOL
  // examine supported release lines

  releases.getSupported().forEach(line => {
    let stats = line.getStats()
    console.log({
      version: line.version,
      daysToEOL: stats.days.until.eol,
      progress: `${stats.percent.total}%`,
      state: {
        lts: line.isLTS,
        isCurrent: line.isCurrent,
        isActive: line.isActive,
        isMaintenance: line.isMaintenance
      },
      releases: {
        total: line.releases.length,
        safe: line.releases.getSafe().length,
        latest: line.releases[0].version
      }
    })
  })
}

Output

{ version: 'v6',
  daysToEOL: 198,
  progress: '81%',
  state:
   { lts: true,
     isCurrent: false,
     isActive: false,
     isMaintenance: true },
  releases: { total: 39, safe: 1, latest: 'v6.14.3' } }
{ version: 'v8',
  daysToEOL: 472,
  progress: '50%',
  state:
   { lts: true,
     isCurrent: false,
     isActive: true,
     isMaintenance: false },
  releases: { total: 26, safe: 2, latest: 'v8.11.4' } }
{ version: 'v10',
  daysToEOL: 929,
  progress: '13%',
  state:
   { lts: true,
     isCurrent: true,
     isActive: false,
     isMaintenance: false },
  releases: { total: 12, safe: 6, latest: 'v10.9.0' } }

Command Line

The node-release-lines CLI options can be used globally or via npx.

Globally, where <command> is the command you'd like to use:

npm install node-release-lines -g
<command> [options]

Via npx, where <command> is the command you'd like to use:

npx node-release-lines <command> [options]

Command: `isnodesafe [options]`

isnodesafe is a CLI utility to check if Node.js is safe. The CLI defaults to checking system version, but can also check user-specified versions.

`isnodesafe` Options

-v, --version: output the version number
-c, --ci: Returns a non-zero exit code if the version of Node.js is not safe, and a zero exit code if it is safe.
-r, --release [release] Checks to see if a specific release of Node.js is safe
-h, --help output usage information

`isnodesafe` Examples

$ isnodesafe
$ isnodesafe --ci
$ isnodesafe --release 10.2.0
$ isnodesafe -rc 6.9.5

Command: `amisafe`

This command is deprecated in favor of isnodesafe. It will work as an alias of isnodesafe until node-release-lines@2.0.0, at which point it will be removed.

Command: `nodetimeline [options]`

nodetimeline is a CLI tool to understand Node.js release lines lifespans.

`nodetimeline` Options

-v, --version: output the version number
-c, --current: Returns all "Current" versions of Node.js.
-l, --lts: Returns all presently supported "LTS" versions of Node.js – regardless of whether or not they are presently active "LTS".
-a, --active: Returns all active "LTS" Node.js release lines.
-m, --maintenance: Returns all presently supported "Maintenance" versions of Node.js.
-s, --supported: Returns all presently supported Node.js version
-h, --help: output usage information

`nodetimeline` Examples

$ nodetimeline
$ nodetimeline -c
$ nodetimeline --lts

API

Terminology

EOL: (end of life) - any ReleaseLine no longer supported and recieves no more updates.
Supported: any ReleaseLine that has been started and has not reached EOL.
LTS: any ReleaseLine that has an active LTS period in the lifecycle.
Active: any ReleaseLine that is in LTS, excluding maintenance window.
Maintenance: any ReleaseLine that is in maintenance mode and has not reached EOL.
Current: any ReleaseLine that has been started, in active development, not in maintenance or LTS.
Future: any defined ReleaseLine that has yet to start.
Modern: any ReleaseLine that is v1 or greater. This does not include io.js releases (any version from v4 onwards).

`ReleaseLine` class

Instance properties:

version: String
start: Date
end: Date
lts: Date or undefined
maintenance: Date or undefined
codename: String or undefined

Instance getters:

see terminology

releases: Releases see Releases section (lazy loaded)
isEOL: Boolean
isSupported: Boolean
isLTS: Boolean
isActive: Boolean
inLTS: Boolean alias for isActive
isMaintenance: Boolean
isCurrent: Boolean
isFuture: Boolean
isModern: Boolean
notStarted: Boolean

`setDate(date)`

Changes the date for calculating stats in getStats

Params:

date: Date instance (optional, defaults=Date.now)

Returns: this

`getStats(precision)`

Params:

precision: Number

Stats about the relative timeline of the release based on the current setDate.

Notes:

0 will be used for unknown values. For example maintenance, lts are not valid for some release.
If a value is negative 0 is returned instead. This is useful for a ReleaseLine that hasn't started.
returned stats object is not bound to setDate

Returns:

{ days: { 
    total: 1073, // total days release is supported
    current: 160, // days in `current` mode
    lts: 548, // days in `active` LTS
    maintenance: 365, // days in maintenance
    completed: { 
        total: 144, 
        current: 144, 
        lts: 0, 
        maintenance: 0 },
    remaining: { 
        total: 929, 
        current: 16, 
        lts: 548, 
        maintenance: 365 },
    until: { 
        start: 0, // already started
        lts: 16, 
        maintenance: 564, 
        eol: 929 } 
    },
  percent: { 
      total: 13, // complete
      current: 90, 
      lts: 0, 
      maintenance: 0 } 
}

`ReleaseLines` extends `Array` class

An array of ReleaseLine instances. Provides helper methods for updating, filtering and querying release lines.

`ReleaseLines.load(schedule, date)` static

Hydrates a schedule. If a schedule is not defined then the internal cached copy is automatically used.

Params:

schedule: an object of release lines (optional)
- key: version of the release
- value: Object
  - start: String or Date (required)
  - endt: String or Date (required)
  - lts: String or Date
  - maintenance: String or Date
  - codename: String
date: Date instance (optional, defaults=Date.now)

Returns: ReleaseLines instance

`ReleaseLines.fetch(date)` static

Params:

date: Date instance (optional, defaults=Date.now)

Returns: Promise - resolves to ReleaseLines instance

`ReleaseLines.scheduleUrl` (string) static

The url to the offical release schedule.

`get(version, resetDate)`

Params:

version: a release line name (example: v10)
resetDate: Date, String or Boolean - changes the date. (optional)

Returns: ReleaseLine or undefined

`setDate(date)`

Params:

date: Date instance (optional, defaults=Date.now)

Returns: this

`getSupported(resetDate)`

Filters ReleaseLine items by isSupported

Params:

resetDate: Date, String or Boolean - changes the date. (optional)

Returns: ReleaseLines instance with only supported release lines.

`getCurrent(resetDate)`

Filters ReleaseLine items by isCurrent

Params:

resetDate: Date, String or Boolean - changes the date. (optional)

Returns: ReleaseLines instance with only current release lines.

`getMaintenance(resetDate)`

Filters ReleaseLine items by isMaintenance

Params:

resetDate: Date, String or Boolean - changes the date. (optional)

Returns: ReleaseLines instance with only release lines in maintenance mode.

`getFuture(resetDate)`

Filters ReleaseLine items by isFuture

Params:

resetDate: Date, String or Boolean - changes the date. (optional)

Returns: ReleaseLines instance with only release lines that have yet to start.

`getActive(resetDate)`

Filters ReleaseLine items by isActive

Params:

resetDate: Date, String or Boolean - changes the date. (optional)

Returns: ReleaseLines instance with only release lines that are in LTS, excluding maintenance window.

`getEOL(resetDate)`

Filters ReleaseLine items by isEOL

Params:

resetDate: Date, String or Boolean - changes the date. (optional)

Returns: ReleaseLines instance with only release lines that have hit EOL

`getModern(resetDate)`

Filters ReleaseLine items by isModern

Params:

resetDate: Date, String or Boolean - changes the date. (optional)

Returns: ReleaseLines instance with only modern release lines.

`getLTS(resetDate)`

Filters ReleaseLine items by isLTS

Params:

resetDate: Date, String or Boolean - changes the date. (optional)

Returns: ReleaseLines instance with only release lines that have an LTS active mode in their lifecycle. Note: It does not neccessarily mean it is an active LTS (see getActive()).

`Release` class

Instance properties:

version: String - version number of release
date: Date - date of release
modules: Number - number of modules
npm: String - version
v8: String - version
uv: String - version
zlib: String - version
openssl: String - version

Instance getters:

vulns: Array of Vulnerability (lazy loading)
isSafe: Boolean - true if Release has no known vulnerabilities.
isVulnerable: Boolean - true if Release has one or more vulnerabilities.
doc: String url of docs for the specific release

`Release.load(version)` static

options:

version: String

Returns: Release or null if version does not exist

`download(arch, type)`

If arch is omitted returns directory to all download resources for release version.

Currently arch and type are not implemented

options:

arch: String
type: String (gz, xz, pkg, msi, zip)

Returns: String url of download resource

`Releases` extends `Array` class

An array of Release instances. Provides helper methods for updating, filtering and querying release lines.

`Releases.load(version)` static

Params:

version: String (example v6)

Returns: Releases instance

`getSafe()`

Filters Release items by isSafe

Returns: Releases instance with only releases that have no known vulnerabilities.

`Vulnerability` class

Instance properties:

id: String

Instance getters:

cve
ref
vulnerable
patched
description
overview
author
cvss
cvss_score
source: String - url to specific vulnerability in nodejs/security-wg repo.
isValid: Boolean

`ChangeLog` class

Currently deprecations and notable changes are not fully supported.

Instance properties:

version: String
line: String current release line (example: Current)
date: Date release date
releasedBy: String individual who performed the release
text: String meta text above other sub headers
raw: String raw markdown text of the whole release
commits: Array of Commit

`load(version)` static

options:

version: String

Returns: ChangeLog instance or null

`Commit` class

Instance properties:

sha: String commit sha
pr: String pr number associated with commit
author: String author of commit
reverts: Boolean if commit reverts prior commit(s) or behavior
desc: String commit description
topics: Array areas the commit touches (example: ['build', 'win'])

Instance getters:

shaUrl: String url to the commit in github
prUrl: String url to the pr on github

Acknowledgements

Thank you Node.js Release Team and all the contributors to the Node.js project, without you none of this is possible. Special thanks goes out to Tierney Cyren. His relentless desire to improve accessibility, visibility and communication inspired this project.

Contributing

To submit a bug report, please create an issue on GitHub.

If you'd like to contribute code to this project, please read the CONTRIBUTING.md document.

License & Copyright

node-release-lines is Copyright (c) 2018 Nathan White and licensed under the MIT license. All rights not explicitly granted in the MIT license are reserved. See the included LICENSE.md file for more details.

nw / node-release-lines

readme

Node Release Lines

Installation

Outline

Usage

Output

Command Line

Command: isnodesafe [options]

isnodesafe Options

isnodesafe Examples

Command: amisafe

Command: nodetimeline [options]

nodetimeline Options

nodetimeline Examples

API

Terminology

ReleaseLine class

setDate(date)

getStats(precision)

ReleaseLines extends Array class

ReleaseLines.load(schedule, date) static

ReleaseLines.fetch(date) static

ReleaseLines.scheduleUrl (string) static

get(version, resetDate)

setDate(date)

getSupported(resetDate)

getCurrent(resetDate)

getMaintenance(resetDate)

getFuture(resetDate)

getActive(resetDate)

getEOL(resetDate)

getModern(resetDate)

getLTS(resetDate)

Release class

Release.load(version) static

download(arch, type)

Releases extends Array class

Releases.load(version) static

getSafe()

Vulnerability class

ChangeLog class

load(version) static

Commit class

Acknowledgements

Contributing

License & Copyright

Command: `isnodesafe [options]`

`isnodesafe` Options

`isnodesafe` Examples

Command: `amisafe`

Command: `nodetimeline [options]`

`nodetimeline` Options

`nodetimeline` Examples

`ReleaseLine` class

`setDate(date)`

`getStats(precision)`

`ReleaseLines` extends `Array` class

`ReleaseLines.load(schedule, date)` static

`ReleaseLines.fetch(date)` static

`ReleaseLines.scheduleUrl` (string) static

`get(version, resetDate)`

`setDate(date)`

`getSupported(resetDate)`

`getCurrent(resetDate)`

`getMaintenance(resetDate)`

`getFuture(resetDate)`

`getActive(resetDate)`

`getEOL(resetDate)`

`getModern(resetDate)`

`getLTS(resetDate)`

`Release` class

`Release.load(version)` static

`download(arch, type)`

`Releases` extends `Array` class

`Releases.load(version)` static

`getSafe()`

`Vulnerability` class

`ChangeLog` class

`load(version)` static

`Commit` class