Support for nvm aliases 🔖

includies lts/aliases, stable, personal ones, indirections and cycle protection

:hammer_and_wrench: This is a rework of https://github.com/AdrieanKhisbe/normalize-node-version/commits/support-nvm-aliases--original prototype when #1 was still in building 🏗️

Author: AdrieanKhisbe

README.md

@@ -25,6 +25,7 @@ await normalizeNodeVersion('<7') // '6.17.1'
 await normalizeNodeVersion('*') // Latest Node version, e.g. '12.8.0'
 await normalizeNodeVersion('_') // Node version used by current process
 await normalizeNodeVersion('.') // Node version from a '.nvmrc', '.node-version' or '.naverc' file in the current directory or any parent directory
+await normalizeNodeVersion('default') // Nvm default version, if nvm is available
 await normalizeNodeVersion('not_a_version') // Error: Invalid Node version
 
 // All available options
@@ -85,6 +86,14 @@ _Default_: `process.cwd()`
 When using the [`.` alias](#supported-aliases), start looking for a Node.js
 version file from this directory.
 
+#### nvmDir
+
+_Type_: `string`\
+_Default_: `process.env.NVM_DIR`
+
+Override to specify what path to consider for Nvm directory. Defaults to content
+of `NVM_DIR` environment variable that nvm makes point to the `.nvm` directory
+
 # See also
 
 - [`nve`](https://github.com/ehmicky/nve): Run a specific Node.js version (CLI)

src/alias.js

@@ -1,5 +1,69 @@
+import { promises as fs } from 'fs'
+
+import { validRange, rsort } from 'semver'
+
+const NODE_LATEST_ALIASES = new Set(['stable', 'node', 'latest'])
+const NODE_LTS_CODE_NAMES = new Set([
+  'argon',
+  'boron',
+  'carbon',
+  'dubnium',
+  'erbium',
+  'fermium',
+  'gallium',
+  'hydrogen',
+  'iron',
+])
+
+const resolveNvmLatestNode = async ({ nvmDir }) => {
+  const nodeVersions = await fs.readdir(`${nvmDir}/versions/node`)
+  return rsort(nodeVersions)[0]
+}
+
+const getAliasedVersion = async ({ nvmDir, alias }) => {
+  const aliasWithImplicitLts = NODE_LTS_CODE_NAMES.has(alias)
+    ? `lts/${alias}`
+    : alias
+  const aliasPath = `${nvmDir}/alias/${aliasWithImplicitLts}`
+
+  await fs.stat(aliasPath).catch((error) => {
+    if (error.code === 'ENOENT')
+      throw new Error(`alias ${alias} does not exist`)
+    throw error
+  })
+  const content = await fs.readFile(aliasPath, 'utf-8')
+  return content.trim()
+}
+
+const resolveNvmAlias = async (
+  alias,
+  { nvmDir, previousAliases = [] } = {},
+) => {
+  if (NODE_LATEST_ALIASES.has(alias)) {
+    return resolveNvmLatestNode({ nvmDir })
+  }
+
+  if (previousAliases.includes(alias)) {
+    throw new Error(
+      `Nvm alias cycle detected ${previousAliases.join(' -> ')} -> ${alias}`,
+    )
+  }
+
+  const resolvedVersion = await getAliasedVersion({ nvmDir, alias })
+  if (validRange(resolvedVersion)) return resolvedVersion
+
+  return resolveNvmAlias(resolvedVersion, {
+    nvmDir,
+    previousAliases: [...previousAliases, alias],
+  })
+}
+
 // nvm allows several aliases like `lts/*`
-export const replaceAliases = function (versionRange) {
+export const replaceAliases = function (versionRange, { nvmDir } = {}) {
+  if (nvmDir) {
+    return resolveNvmAlias(versionRange, { nvmDir })
+  }
+
   const aliasedVersionRange = ALIASES[versionRange]
 
   if (aliasedVersionRange === undefined) {

src/aliases.js

@@ -1,5 +1,8 @@
 import { version as processVersion } from 'process'
 
+import { validRange } from 'semver'
+
+import { replaceAliases } from './alias.js'
 import { getProjectVersion } from './project.js'
 
 // `versionRange` can be one of the following aliases:
@@ -8,11 +11,15 @@ import { getProjectVersion } from './project.js'
 export const resolveAlias = function (versionRange, opts) {
   const getVersion = ALIASES[versionRange]
 
-  if (getVersion === undefined) {
-    return versionRange
+  if (getVersion !== undefined) {
+    return getVersion(opts)
+  }
+
+  if (!validRange(versionRange) && opts.nvmDir) {
+    return replaceAliases(versionRange, opts)
   }
 
-  return getVersion(opts)
+  return versionRange
 }
 
 const getCurrentVersion = function () {

src/main.js

@@ -8,8 +8,8 @@ import { getOpts } from './options.js'
 
 // Retrieve the Node version matching a specific `versionRange`
 const normalizeNodeVersion = async function (versionRange, opts) {
-  const { cwd, ...optsA } = getOpts(opts)
-  const versionRangeA = await resolveAlias(versionRange, { cwd })
+  const { cwd, nvmDir, ...optsA } = getOpts(opts)
+  const versionRangeA = await resolveAlias(versionRange, { cwd, nvmDir })
   const versions = await getVersions(versionRangeA, optsA)
 
   const version = maxSatisfying(versions, versionRangeA)

src/options.js

@@ -1,4 +1,4 @@
-import { cwd as getCwd } from 'process'
+import { cwd as getCwd, env as processEnv } from 'process'
 
 import { validate } from 'jest-validate'
 
@@ -12,6 +12,7 @@ export const getOpts = function (opts = {}) {
 const DEFAULT_OPTS = () => ({
   cache: true,
   cwd: getCwd(),
+  nvmDir: processEnv.NVM_DIR,
 })
 
 const EXAMPLE_OPTS = () => ({

test/aliases.js

@@ -14,8 +14,16 @@ const VERSIONS = {
   nvmrc: '4.2.6',
   nodeVersion: '4.3.2',
   current: versions.node,
+  NVM: {
+    carbon: '8.17.0',
+    node: '12.16.2',
+    personal: '12.12.0',
+    default: '10.10.0',
+  },
 }
 
+const NVM_OPTS = { nvmDir: `${FIXTURES_DIR}/nvm-dir` }
+
 each(
   [
     { versionRange: '.', fixture: 'naverc', result: VERSIONS.nave },
@@ -28,6 +36,20 @@ each(
     { versionRange: '.', fixture: 'mixed', result: VERSIONS.nodeVersion },
     { versionRange: '.', opts: { cwd: '/' }, result: VERSIONS.current },
     { versionRange: '_', result: VERSIONS.current },
+    { versionRange: 'node', opts: NVM_OPTS, result: VERSIONS.NVM.node },
+    { versionRange: 'stable', opts: NVM_OPTS, result: VERSIONS.NVM.node },
+    { versionRange: 'latest', opts: NVM_OPTS, result: VERSIONS.NVM.node },
+    { versionRange: 'default', opts: NVM_OPTS, result: VERSIONS.NVM.default },
+    {
+      versionRange: 'personal-alias',
+      opts: NVM_OPTS,
+      result: VERSIONS.NVM.personal,
+    },
+    { versionRange: 'lts/carbon', opts: NVM_OPTS, result: VERSIONS.NVM.carbon },
+    // implicit lts prefix for lts node codenames
+    { versionRange: 'carbon', opts: NVM_OPTS, result: VERSIONS.NVM.carbon },
+    // recursive resolving
+    { versionRange: 'carbon14', opts: NVM_OPTS, result: VERSIONS.NVM.carbon },
   ],
   ({ title }, { versionRange, opts, fixture, result }) => {
     test(`Resolve aliases | ${title}`, async (t) => {
@@ -39,6 +61,28 @@ each(
   },
 )
 
+test('Resolve nvm aliases ignored if no NVM_DIR configured', async (t) => {
+  await t.throwsAsync(
+    () =>
+      normalizeNodeVersion('default', {
+        nvmDir: '',
+      }),
+    { message: 'Invalid Node version: default' },
+  )
+})
+
+test('Resolved  nvm alias fails and do not loop infinitely if alias cycle is present', async (t) => {
+  const AVA_TIMEOUT_CYCLE = 2000
+  t.timeout(AVA_TIMEOUT_CYCLE)
+  await t.throwsAsync(() => normalizeNodeVersion('cycle', NVM_OPTS), {
+    message: 'Nvm alias cycle detected cycle -> ping -> pong -> ping',
+  })
+})
+
+test('Resolve nvm aliases fails if nvm alias does not exists', async (t) => {
+  await t.throwsAsync(() => normalizeNodeVersion('awol', NVM_OPTS))
+})
+
 test.serial('Option cwd defaults to the current directory', async (t) => {
   const currentCwd = getCwd()
   chdir(`${FIXTURES_DIR}/nvmrc`)

test/fixtures/nvm-dir/alias/carbon14

@@ -0,0 +1 @@
+lts/carbon

test/fixtures/nvm-dir/alias/cycle

@@ -0,0 +1 @@
+ping

test/fixtures/nvm-dir/alias/default

@@ -0,0 +1 @@
+v10.10

test/fixtures/nvm-dir/alias/lts/*

@@ -0,0 +1 @@
+lts/erbium