Skip to content

Conversation

SebastianSedzik
Copy link

@SebastianSedzik SebastianSedzik commented Sep 15, 2025

Description

This PR introduces a new --cooldown option to ncu, inspired by Dependabot’s cooldown and pnpm’s minimumReleaseAge.

The cooldown feature reduces the risk of installing compromised packages by delaying updates to versions that were published too recently. It enforces a minimum number of days that must pass after a version’s release before it can be considered for upgrade.

Usage

ncu --cooldown [days]
ncu -c [days]

Example

Suppose your project uses version 1.0.0 of a package, and these versions are available:

  • 1.0.0 – released 60 days ago
  • 1.1.0 – released 45 days ago
  • 1.2.0 – released 20 days ago
  • 1.3.0 – released 10 days ago

Running:
ncu --cooldown 30 will upgrade to 1.1.0, since it was released 45 days ago and is the latest version outside the 30-day cooldown period. Versions 1.2.0 and 1.3.0 are skipped because they fall within the cooldown window.

Resolves: #1532

@SebastianSedzik SebastianSedzik marked this pull request as ready for review September 15, 2025 17:28
@@ -909,6 +931,16 @@ const cliOptions: CLIOption[] = [
description: 'Run on all workspaces. Add `--root` to also upgrade the root project.',
type: 'boolean',
},
{
long: 'cooldown',
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

question: (to foster discussion) Is cooldown the best name for this feature?

arg: 'n',
description:
'Delay updates to newly published versions to reduce risk. Sets a minimum number of days after publication before a version is considered for upgrade.',
type: 'number',
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

question: (to foster discussion) Is days a right unit for this feature? Maybe hours will be more flexible

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

clarification: this file is used later by unit tests related to the cooldown feature.

@raineorshine
Copy link
Owner

raineorshine commented Sep 16, 2025

Thank you!

I have one initial comment about the expected behavior. The default target for npm-check-updates is whatever version is published to the latest tag. If this version was published within the specified cooldown, then we should not upgrade, as expected. However we also cannot upgrade to an earlier version, because there is no history of versions published to the latest tag. i.e. We cannot assume that v1.1 is a stable release just because v1.2 is.

In theory you could make some assumptions and use a heuristic, but the design philosophy of npm-check-updates is to strictly follow semver and choose the conservative approach when faced with ambiguity. There are packages that publish build numbers to latest, e.g. v1.1-d67a15, which is valid semver, making it harder to come up with an accurate heuristic anyway.

If --target newest or --target greatest is specified then it's safe to upgrade to another version in the list that is returned. It's just --target @TAG and --target latest (the default) that only return a single version. In that case, we have to skip the upgrade completely if it's on cooldown.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Feature Request: Cooldown Parameter(s)
2 participants