feat(cooldown): support for cooldown predicate function (#1563)

Author: SebastianSedzik

README.md

@@ -460,6 +460,18 @@ Note for latest/tag targets:
 
 > :warning: For packages that update frequently (e.g. daily releases), using a long cooldown period (7+ days) with the default `--target latest` or `--target @tag` may prevent all updates since new versions will be published before older ones meet the cooldown requirement. Please consider this when setting your cooldown period.
 
+You can also provide a custom function in your .ncurc.js file or when importing npm-check-updates as a module.
+
+> :warning: The predicate function is only available in .ncurc.js or when importing npm-check-updates as a module, not on the command line. To convert a JSON config to a JS config, follow the instructions at https://github.com/raineorshine/npm-check-updates#config-functions.
+
+```js
+/** Set cooldown to 3 days but skip it for `@my-company` packages.
+  @param packageName     The name of the dependency.
+  @returns               Cooldown days restriction for given package (when null cooldown will be skipped for given package).
+*/
+cooldown: packageName => (packageName.startsWith('@my-company') ? null : 3)
+```
+
 ## doctor
 
 Usage:

src/cli-options.ts

@@ -599,6 +599,18 @@ ${chalk.bold('Note for latest/tag targets')}:
 
 > :warning: For packages that update frequently (e.g. daily releases), using a long cooldown period (7+ days) with the default \`--target latest\` or \`--target @tag\` may prevent all updates since new versions will be published before older ones meet the cooldown requirement. Please consider this when setting your cooldown period.
 
+You can also provide a custom function in your .ncurc.js file or when importing npm-check-updates as a module.
+
+> :warning: The predicate function is only available in .ncurc.js or when importing npm-check-updates as a module, not on the command line. To convert a JSON config to a JS config, follow the instructions at https://github.com/raineorshine/npm-check-updates#config-functions.
+
+${codeBlock(
+  `${chalk.gray(`/** Set cooldown to 3 days but skip it for \`@my-company\` packages.
+  @param packageName     The name of the dependency.
+  @returns               Cooldown days restriction for given package (when null cooldown will be skipped for given package).
+*/`)}
+${chalk.green('cooldown')}: (packageName) ${chalk.cyan('=>')} packageName.startsWith(${chalk.yellow("'@my-company'")}) ? ${chalk.cyan('null')} : ${chalk.cyan('3')}`,
+  { markdown },
+)}
 `
 }
 
@@ -971,7 +983,7 @@ const cliOptions: CLIOption[] = [
     arg: 'n',
     description:
       'Sets a minimum age (in days) for package versions to be considered for upgrade, reducing the risk of installing newly published, potentially compromised packages.',
-    type: 'number',
+    type: `number | CooldownFunction`,
     help: extendedHelpCooldown,
     parse: s => parseInt(s, 10),
   },

src/lib/initOptions.ts

@@ -183,8 +183,13 @@ async function initOptions(runOptions: RunOptions, { cli }: { cli?: boolean } =
     programError(options, `--registry must be a valid URL. Invalid value: "${options.registry}"`)
   }
 
-  if (options.cooldown != null && (isNaN(options.cooldown) || options.cooldown < 0)) {
-    programError(options, 'Cooldown must be a non-negative integer representing days since published')
+  if (options.cooldown != null) {
+    const isValidNumber = typeof options.cooldown === 'number' && !isNaN(options.cooldown) && options.cooldown >= 0
+    const isValidFunction = typeof options.cooldown === 'function'
+
+    if (!isValidNumber && !isValidFunction) {
+      programError(options, 'Cooldown must be a non-negative integer representing days since published or a function')
+    }
   }
 
   const target: Target = options.target || 'latest'

src/package-managers/filters.ts

@@ -1,5 +1,6 @@
 import semver from 'semver'
 import * as versionUtil from '../lib/version-util'
+import { CooldownFunction } from '../types/CooldownFunction'
 import { Index } from '../types/IndexType'
 import { Maybe } from '../types/Maybe'
 import { Options } from '../types/Options'
@@ -62,17 +63,24 @@ export function satisfiesPeerDependencies(versionResult: Partial<Packument>, pee
  * @param cooldownDays - The cooldown period in days. If not specified or invalid, the function returns true.
  * @returns `true` if the version's release date is older than the cooldown period, otherwise `false`.
  */
-export function satisfiesCooldownPeriod(versionResult: Partial<Packument>, cooldownDays: Maybe<number>): boolean {
+export function satisfiesCooldownPeriod(
+  versionResult: Partial<Packument>,
+  cooldownDaysOrPredicateFn: Maybe<number> | Maybe<CooldownFunction>,
+): boolean {
   const version = versionResult.version
   const versionTimeData = versionResult?.time?.[version!]
 
-  if (!cooldownDays) return true
+  if (!cooldownDaysOrPredicateFn) return true
   if (!versionTimeData) return false
 
   const versionReleaseDate = new Date(versionTimeData)
   const DAY_AS_MS = 86400000 // milliseconds in a day
-  const cooldownDaysAsMs = cooldownDays * DAY_AS_MS
-  return Date.now() - versionReleaseDate.getTime() >= cooldownDaysAsMs
+  const cooldownDays =
+    typeof cooldownDaysOrPredicateFn === 'function'
+      ? (cooldownDaysOrPredicateFn(versionResult.name!) ?? 0) // when null or undefined is returned cooldown is skipped for given package
+      : cooldownDaysOrPredicateFn
+
+  return Date.now() - versionReleaseDate.getTime() >= cooldownDays * DAY_AS_MS
 }
 
 /** Returns a composite predicate that filters out deprecated, prerelease, and node engine incompatibilies from version objects returns by packument. */

src/package-managers/npm.ts

@@ -123,21 +123,22 @@ const fetchPartialPackument = async (
 }
 
 /**
- * Decorates a tag-specific/version-specific packument object with the `time` property from the full packument,
+ * Decorates a tag-specific/version-specific packument object with the package name and `time` property from the full packument,
  * if the `time` information for the tag's version exists.
  *
  * @param tagPackument - A partial packument object representing a specific tag/version.
  * @param packument - The full packument object, potentially containing time metadata for versions.
- * @returns A new packument object that includes the `time` property if available for the tag's version.
+ * @returns A new packument object that includes the `time` property if available for the tag's version and package name.
  */
-const decorateTagPackumentWithTime = (
+const decorateTagPackumentWithTimeAndName = (
   tagPackument: Partial<Packument>,
   packument: Partial<Packument>,
 ): Partial<Packument> => {
   const version = tagPackument.version
 
   return {
     ...tagPackument,
+    name: packument.name,
     ...(packument?.time?.[version!] ? { time: packument.time } : null),
   }
 }
@@ -702,7 +703,7 @@ export const greatest: GetVersion = async (
     version:
       Object.values(versions || {})
         .filter(tagPackument =>
-          filterPredicate(options)(decorateTagPackumentWithTime(tagPackument, packument as Partial<Packument>)),
+          filterPredicate(options)(decorateTagPackumentWithTimeAndName(tagPackument, packument as Partial<Packument>)),
         )
         .map(o => o.version)
         .sort(versionUtil.compareVersions)
@@ -830,7 +831,7 @@ export const distTag: GetVersion = async (
         version,
       }
 
-  const tagPackumentWithTime = decorateTagPackumentWithTime(tagPackument, packument as Partial<Packument>)
+  const tagPackumentWithTime = decorateTagPackumentWithTimeAndName(tagPackument, packument as Partial<Packument>)
 
   // latest should not be deprecated
   // if latest exists and latest is not a prerelease version, return it
@@ -921,7 +922,7 @@ export const newest: GetVersion = async (
   if (options.cooldown) {
     const versionsSatisfiesfyingCooldownPeriod = versionsSortedByTime.filter(version =>
       satisfiesCooldownPeriod(
-        decorateTagPackumentWithTime((result as Packument).versions[version], result as Packument),
+        decorateTagPackumentWithTimeAndName((result as Packument).versions[version], result as Packument),
         options.cooldown,
       ),
     )
@@ -967,7 +968,7 @@ export const minor: GetVersion = async (
   const version = versionUtil.findGreatestByLevel(
     Object.values(versions || {})
       .filter(tagPackument =>
-        filterPredicate(options)(decorateTagPackumentWithTime(tagPackument, packument as Partial<Packument>)),
+        filterPredicate(options)(decorateTagPackumentWithTimeAndName(tagPackument, packument as Partial<Packument>)),
       )
       .map(o => o.version),
     currentVersion,
@@ -1011,7 +1012,7 @@ export const patch: GetVersion = async (
   const version = versionUtil.findGreatestByLevel(
     Object.values(versions || {})
       .filter(tagPackument =>
-        filterPredicate(options)(decorateTagPackumentWithTime(tagPackument, packument as Partial<Packument>)),
+        filterPredicate(options)(decorateTagPackumentWithTimeAndName(tagPackument, packument as Partial<Packument>)),
       )
       .map(o => o.version),
     currentVersion,
@@ -1057,7 +1058,7 @@ export const semver: GetVersion = async (
 
   const versionsFiltered = Object.values(versions || {})
     .filter(tagPackument =>
-      filterPredicate(options)(decorateTagPackumentWithTime(tagPackument, packument as Partial<Packument>)),
+      filterPredicate(options)(decorateTagPackumentWithTimeAndName(tagPackument, packument as Partial<Packument>)),
     )
     .map(o => o.version)
   // TODO: Upgrading within a prerelease does not seem to work.

src/scripts/build-options.ts

@@ -88,6 +88,7 @@ import { FilterResultsFunction } from './FilterResultsFunction'
 import { GroupFunction } from './GroupFunction'
 import { PackageFile } from './PackageFile'
 import { TargetFunction } from './TargetFunction'
+import { CooldownFunction } from './CooldownFunction'
 
 /** Options that can be given on the CLI or passed to the ncu module to control all behavior. */
 export interface RunOptions {

src/types/CooldownFunction.ts

@@ -0,0 +1,2 @@
+/** A function that can be provided to the --cooldown option for custom cooldown predicate. */
+export type CooldownFunction = (packageName: string) => number | null

src/types/RunOptions.json

@@ -181,8 +181,16 @@
       "type": "string"
     },
     "cooldown": {
-      "description": "Sets a minimum age (in days) for package versions to be considered for upgrade, reducing the risk of installing newly published, potentially compromised packages. Run \"ncu --help --cooldown\" for details.",
-      "type": "number"
+      "anyOf": [
+        {
+          "description": "A function that can be provided to the --cooldown option for custom cooldown predicate.",
+          "type": "object"
+        },
+        {
+          "type": "number"
+        }
+      ],
+      "description": "Sets a minimum age (in days) for package versions to be considered for upgrade, reducing the risk of installing newly published, potentially compromised packages. Run \"ncu --help --cooldown\" for details."
     },
     "cwd": {
       "description": "Working directory in which npm will be executed.",

src/types/RunOptions.ts

@@ -1,4 +1,5 @@
 /** This file is generated automatically from the options specified in /src/cli-options.ts. Do not edit manually. Run "npm run build" or "npm run build:options" to build. */
+import { CooldownFunction } from './CooldownFunction'
 import { FilterFunction } from './FilterFunction'
 import { FilterResultsFunction } from './FilterResultsFunction'
 import { GroupFunction } from './GroupFunction'
@@ -41,7 +42,7 @@ export interface RunOptions {
   configFilePath?: string
 
   /** Sets a minimum age (in days) for package versions to be considered for upgrade, reducing the risk of installing newly published, potentially compromised packages. Run "ncu --help --cooldown" for details. */
-  cooldown?: number
+  cooldown?: number | CooldownFunction
 
   /** Working directory in which npm will be executed. */
   cwd?: string

test/cooldown.test.ts

@@ -1,7 +1,6 @@
 import { expect } from 'chai'
 import Sinon from 'sinon'
 import ncu from '../src/'
-import { MockedVersions } from '../src/types/MockedVersions'
 import { PackageFile } from '../src/types/PackageFile'
 import { Packument } from '../src/types/Packument'
 import chaiSetup from './helpers/chaiSetup'
@@ -27,13 +26,13 @@ interface CreateMockParams {
  * @param params.distTags - An object representing distribution tags for the package.
  * @returns An object representing mocked package versions, including name, versions, time, and distTags.
  */
-const createMockVersion = ({ name, versions, distTags }: CreateMockParams): MockedVersions => {
+const createMockVersion = ({ name, versions, distTags }: CreateMockParams): Partial<Packument> => {
   return {
     name,
     version: Object.keys(versions)[0],
     versions: Object.fromEntries(Object.entries(versions).map(([version]) => [version, { version } as Packument])),
     time: Object.fromEntries(Object.entries(versions).map(([version, date]) => [version, date])),
-    distTags,
+    'dist-tags': distTags,
   }
 }
 
@@ -46,20 +45,18 @@ describe('cooldown', () => {
     it('throws error for negative cooldown', () => {
       expect(
         ncu({
-          packageFile: 'test/test-data/cooldown/package.json',
           cooldown: -1,
         }),
-      ).to.be.rejectedWith('Cooldown must be a non-negative integer representing days since published')
+      ).to.be.rejectedWith('Cooldown must be a non-negative integer representing days since published or a function')
     })
 
     it('throws error for non-numeric cooldown', () => {
       expect(
         ncu({
-          packageFile: 'test/test-data/cooldown/package.json',
           // @ts-expect-error -- testing invalid input
           cooldown: 'invalid',
         }),
-      ).to.be.rejectedWith('Cooldown must be a non-negative integer representing days since published')
+      ).to.be.rejectedWith('Cooldown must be a non-negative integer representing days since published or a function')
     })
   })
 
@@ -479,4 +476,83 @@ describe('cooldown', () => {
 
     stub.restore()
   })
+
+  describe('cooldown predicate function', () => {
+    it('should skip cooldown check when predicate returns null', async () => {
+      // Given: cooldown set to 10, test-package@1.0.0 installed, latest version 1.1.0 released 5 days ago (within cooldown)
+      const cooldown = 10
+      const packageData: PackageFile = {
+        dependencies: {
+          'test-package': '1.0.0',
+        },
+      }
+      const stub = stubVersions(
+        createMockVersion({
+          name: 'test-package',
+          versions: {
+            '1.1.0': new Date(NOW - 5 * DAY).toISOString(),
+          },
+          distTags: {
+            latest: '1.1.0',
+          },
+        }),
+      )
+
+      // When: cooldown predicate returns null for test-package
+      const result = await ncu({
+        packageData,
+        cooldown: packageName => (packageName === 'test-package' ? null : cooldown),
+        target: 'latest',
+      })
+
+      // Then: test-package is upgraded to version 1.1.0 (cooldown check skipped)
+      expect(result).to.have.property('test-package', '1.1.0')
+
+      stub.restore()
+    })
+
+    it('should apply custom cooldown when predicate returns a number', async () => {
+      // Given: default cooldown set to 10, test-package and test-package-2 - both installed in version 1.0.0, and both has the latest version 1.1.0 released 5 days ago (within cooldown)
+      const cooldown = 10
+      const packageData: PackageFile = {
+        dependencies: {
+          'test-package': '1.0.0',
+          'test-package-2': '1.0.0',
+        },
+      }
+      const stub = stubVersions({
+        'test-package': createMockVersion({
+          name: 'test-package',
+          versions: {
+            '1.1.0': new Date(NOW - 5 * DAY).toISOString(),
+          },
+          distTags: {
+            latest: '1.1.0',
+          },
+        }),
+        'test-package-2': createMockVersion({
+          name: 'test-package-2',
+          versions: {
+            '1.1.0': new Date(NOW - 5 * DAY).toISOString(),
+          },
+          distTags: {
+            latest: '1.1.0',
+          },
+        }),
+      })
+
+      // When: cooldown predicate returns 5 for test-package (skipping cooldown), and 10 for the rest packages
+      const result = await ncu({
+        packageData,
+        cooldown: (packageName: string) => (packageName === 'test-package' ? 5 : cooldown),
+        target: 'latest',
+      })
+
+      // Then: test-package is upgraded to version 1.1.0 (as cooldown for this package was set to 5), but test-package-2 is not upgraded (as rest of the packages use default cooldown of 10)
+      expect(result).to.have.property('test-package', '1.1.0')
+      expect(result).to.not.have.property('test-package-2')
+
+      stub.restore()
+    })
+  })
 })