diff --git a/LICENSE b/LICENSE index b8a71e04..8489fbfc 100644 --- a/LICENSE +++ b/LICENSE @@ -1,4 +1,4 @@ -Copyright 2013 Tomas Junnonen +Copyright 2025 Tomas Junnonen Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. diff --git a/README.md b/README.md index b8823ad4..528fd923 100644 --- a/README.md +++ b/README.md @@ -159,9 +159,9 @@ Advanced filters: [filter](https://github.com/raineorshine/npm-check-updates#fil Options are merged with the following precedence: 1. Command line options -2. Local [Config File](#config-file) -3. Project Config File -4. User Config File +2. Local [Config File](#config-file) (current working directory) +3. Project Config File (next to package.json) +4. User Config File (`$HOME`) Options that take no arguments can be negated by prefixing them with `--no-`, e.g. `--no-peer`. @@ -459,7 +459,9 @@ Include only package names matching the given string, wildcard, glob, comma-or-s `--filter` runs _before_ new versions are fetched, in contrast to `--filterResults` which runs _after_. -The predicate function is only available in .ncurc.js or when importing npm-check-updates as a module, not on the command line. +You can also specify 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 /** @@ -468,7 +470,7 @@ The predicate function is only available in .ncurc.js or when importing npm-chec (See: https://git.coolaj86.com/coolaj86/semver-utils.js#semverutils-parse-semverstring) @returns True if the package should be included, false if it should be excluded. */ -filterFunction: (name, semver) => { +filter: (name, semver) => { if (name.startsWith('@myorg/')) { return false } @@ -482,7 +484,7 @@ Filters out upgrades based on a user provided function. `filterResults` runs _after_ new versions are fetched, in contrast to `filter`, `reject`, `filterVersion`, and `rejectVersion`, which run _before_. This allows you to filter out upgrades with `filterResults` based on how the version has changed (e.g. a major version change). -Only available in .ncurc.js 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 /** Filter out non-major version updates. Note this could also be achieved with --target semver. @@ -515,7 +517,9 @@ Include only versions matching the given string, wildcard, glob, comma-or-space- `--filterVersion` runs _before_ new versions are fetched, in contrast to `--filterResults` which runs _after_. -The predicate function is only available in .ncurc.js or when importing npm-check-updates as a module, not on the command line. This function is an alias for the `filter` option function. +You can also specify 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. This function is an alias for the `filter` option function. ```js /** @@ -524,7 +528,7 @@ The predicate function is only available in .ncurc.js or when importing npm-chec (See: https://git.coolaj86.com/coolaj86/semver-utils.js#semverutils-parse-semverstring) @returns True if the package should be included, false if it should be excluded. */ -filterVersionFunction: (name, semver) => { +filterVersion: (name, semver) => { if (name.startsWith('@myorg/') && parseInt(semver[0]?.major) > 5) { return false } @@ -553,7 +557,7 @@ Modify the output formatting or show additional information. Specify one or more Customize how packages are divided into groups when using `--format group`. -Only available in .ncurc.js or when importing npm-check-updates as a module, not on the command line. +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 /** @@ -694,7 +698,9 @@ The inverse of `--filter`. Exclude package names matching the given string, wild `--reject` runs _before_ new versions are fetched, in contrast to `--filterResults` which runs _after_. -The predicate function is only available in .ncurc.js or when importing npm-check-updates as a module, not on the command line. +You can also specify 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 /** @@ -703,7 +709,7 @@ The predicate function is only available in .ncurc.js or when importing npm-chec (See: https://git.coolaj86.com/coolaj86/semver-utils.js#semverutils-parse-semverstring) @returns True if the package should be excluded, false if it should be included. */ -rejectFunction: (name, semver) => { +reject: (name, semver) => { if (name.startsWith('@myorg/')) { return true } @@ -721,7 +727,9 @@ The inverse of `--filterVersion`. Exclude versions matching the given string, wi `--rejectVersion` runs _before_ new versions are fetched, in contrast to `--filterResults` which runs _after_. -The predicate function is only available in .ncurc.js or when importing npm-check-updates as a module, not on the command line. This function is an alias for the reject option function. +You can also specify 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. This function is an alias for the reject option function. ```js /** @@ -730,7 +738,7 @@ The predicate function is only available in .ncurc.js or when importing npm-chec (See: https://git.coolaj86.com/coolaj86/semver-utils.js#semverutils-parse-semverstring) @returns True if the package should be excluded, false if it should be included. */ -rejectVersionFunction: (name, semver) => { +rejectVersion: (name, semver) => { if (name.startsWith('@myorg/') && parseInt(semver[0]?.major) > 5) { return true } @@ -757,7 +765,13 @@ Determines the version to upgrade to. (default: "latest") @[tag]Upgrade to the version published to a specific tag, e.g. 'next' or 'beta'. -You can also specify a custom function in your .ncurc.js file, or when importing npm-check-updates as a module: +e.g. + + ncu --target semver + +You can also specify 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 /** Upgrade major version zero to the next minor version, and everything else to latest. @@ -776,9 +790,7 @@ target: (name, semver) => { ## Config File -Use a `.ncurc.{json,yml,js,cjs}` file to specify configuration information. -You can specify the file name and path using `--configFileName` and `--configFilePath` -command line options. +Add a `.ncurc.{json,yml,js,cjs}` file to your project directory to specify configuration information. For example, `.ncurc.json`: @@ -790,6 +802,30 @@ For example, `.ncurc.json`: } ``` +Options are merged with the following precedence: + +1. Command line options +2. Local Config File (current working directory) +3. Project Config File (next to package.json) +4. User Config File (`$HOME`) + +You can also specify a custom config file name or path using the `--configFileName` or `--configFilePath` command line options. + +### Config Functions + +Some options offer more advanced configuration using a function definition. These include [filter](https://github.com/raineorshine/npm-check-updates#filter), [filterVersion](https://github.com/raineorshine/npm-check-updates#filterversion), [filterResults](https://github.com/raineorshine/npm-check-updates#filterresults), [reject](https://github.com/raineorshine/npm-check-updates#reject), [rejectVersion](https://github.com/raineorshine/npm-check-updates#rejectversion), and [groupFunction](https://github.com/raineorshine/npm-check-updates#groupfunction). To define an options function, convert the config file to a JS file by adding the `.js` extension and setting module.exports: + +For example, `.ncurc.js`: + +```js +module.exports = { + upgrade: true, + filter: name => name.startsWith('@myorg/'), +} +``` + +### JSON Schema + If you write `.ncurc` config files using json or yaml, you can add the JSON Schema to your IDE settings for completions. e.g. for VS Code: diff --git a/package-lock.json b/package-lock.json index 2c52edd5..316bdcf2 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "npm-check-updates", - "version": "17.1.13", + "version": "17.1.14", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "npm-check-updates", - "version": "17.1.13", + "version": "17.1.14", "license": "Apache-2.0", "bin": { "ncu": "build/cli.js", diff --git a/package.json b/package.json index 09c38c6d..6c756d4c 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "npm-check-updates", - "version": "17.1.13", + "version": "17.1.14", "author": "Tomas Junnonen ", "license": "Apache-2.0", "contributors": [ diff --git a/src/cli-options.ts b/src/cli-options.ts index df2c300b..be820661 100755 --- a/src/cli-options.ts +++ b/src/cli-options.ts @@ -132,7 +132,7 @@ ${codeInline('filterResults')} runs _after_ new versions are fetched, in contras 'filterResults', )} based on how the version has changed (e.g. a major version change). -Only available in .ncurc.js 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(`/** Filter out non-major version updates. Note this could also be achieved with --target semver. @@ -217,7 +217,9 @@ ${codeInline('--filter')} runs _before_ new versions are fetched, in contrast to '--filterResults', )} which runs _after_. -The predicate function is only available in .ncurc.js or when importing npm-check-updates as a module, not on the command line. +You can also specify 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(`/** @@ -226,7 +228,7 @@ ${codeBlock( (See: https://git.coolaj86.com/coolaj86/semver-utils.js#semverutils-parse-semverstring) @returns True if the package should be included, false if it should be excluded. */`)} -${chalk.green('filterFunction')}: (name, semver) ${chalk.cyan('=>')} { +${chalk.green('filter')}: (name, semver) ${chalk.cyan('=>')} { ${chalk.red('if')} (name.startsWith(${chalk.yellow(`'@myorg/'`)})) { ${chalk.red('return')} ${chalk.cyan('false')} } @@ -249,7 +251,9 @@ ${codeInline('--filterVersion')} runs _before_ new versions are fetched, in cont '--filterResults', )} which runs _after_. -The predicate function is only available in .ncurc.js or when importing npm-check-updates as a module, not on the command line. This function is an alias for the ${codeInline('filter')} option function. +You can also specify 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. This function is an alias for the ${codeInline('filter')} option function. ${codeBlock( `${chalk.gray(`/** @@ -258,7 +262,7 @@ ${codeBlock( (See: https://git.coolaj86.com/coolaj86/semver-utils.js#semverutils-parse-semverstring) @returns True if the package should be included, false if it should be excluded. */`)} -${chalk.green('filterVersionFunction')}: (name, semver) ${chalk.cyan('=>')} { +${chalk.green('filterVersion')}: (name, semver) ${chalk.cyan('=>')} { ${chalk.red('if')} (name.startsWith(${chalk.yellow(`'@myorg/'`)}) ${chalk.red( '&&', )} parseInt(semver[0]?.major) ${chalk.cyan('>')} ${chalk.cyan(`5`)}) { @@ -287,7 +291,9 @@ ${codeInline('--reject')} runs _before_ new versions are fetched, in contrast to '--filterResults', )} which runs _after_. -The predicate function is only available in .ncurc.js or when importing npm-check-updates as a module, not on the command line. +You can also specify 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(`/** @@ -296,7 +302,7 @@ ${codeBlock( (See: https://git.coolaj86.com/coolaj86/semver-utils.js#semverutils-parse-semverstring) @returns True if the package should be excluded, false if it should be included. */`)} -${chalk.green('rejectFunction')}: (name, semver) ${chalk.cyan('=>')} { +${chalk.green('reject')}: (name, semver) ${chalk.cyan('=>')} { ${chalk.red('if')} (name.startsWith(${chalk.yellow(`'@myorg/'`)})) { ${chalk.red('return')} ${chalk.cyan('true')} } @@ -321,7 +327,9 @@ ${codeInline('--rejectVersion')} runs _before_ new versions are fetched, in cont '--filterResults', )} which runs _after_. -The predicate function is only available in .ncurc.js or when importing npm-check-updates as a module, not on the command line. This function is an alias for the reject option function. +You can also specify 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. This function is an alias for the reject option function. ${codeBlock( `${chalk.gray(`/** @@ -330,7 +338,7 @@ ${codeBlock( (See: https://git.coolaj86.com/coolaj86/semver-utils.js#semverutils-parse-semverstring) @returns True if the package should be excluded, false if it should be included. */`)} -${chalk.green('rejectVersionFunction')}: (name, semver) ${chalk.cyan('=>')} { +${chalk.green('rejectVersion')}: (name, semver) ${chalk.cyan('=>')} { ${chalk.red('if')} (name.startsWith(${chalk.yellow(`'@myorg/'`)}) ${chalk.red( '&&', )} parseInt(semver[0]?.major) ${chalk.cyan('>')} ${chalk.cyan(`5`)}) { @@ -348,7 +356,7 @@ ${chalk.green('rejectVersionFunction')}: (name, semver) ${chalk.cyan('=>')} { const extendedHelpGroupFunction: ExtendedHelp = ({ markdown }) => { return `Customize how packages are divided into groups when using \`--format group\`. -Only available in .ncurc.js or when importing npm-check-updates as a module, not on the command line. +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(`/** @@ -406,7 +414,13 @@ const extendedHelpTarget: ExtendedHelp = ({ markdown }) => { ${padLeft(tableString, markdown ? 0 : 4)} -You can also specify a custom function in your .ncurc.js file, or when importing npm-check-updates as a module: +e.g. + +${codeBlock(`ncu --target semver`)} + +You can also specify 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(`/** Upgrade major version zero to the next minor version, and everything else to latest. diff --git a/test/rc-config.test.ts b/test/rc-config.test.ts index 11541537..06ead762 100644 --- a/test/rc-config.test.ts +++ b/test/rc-config.test.ts @@ -214,4 +214,141 @@ describe('rc-config', () => { await fs.rm(tempDir, { recursive: true, force: true }) } }) + + describe('config functions', () => { + it('filter function', async () => { + const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'npm-check-updates-')) + const configFile = path.join(tempDir, '.ncurc.js') + const pkgFile = path.join(tempDir, 'package.json') + await fs.writeFile( + configFile, + `module.exports = { + filter: name => name.endsWith('tag') + }`, + 'utf-8', + ) + await fs.writeFile( + pkgFile, + JSON.stringify({ dependencies: { 'ncu-test-v2': '1.0.0', 'ncu-test-tag': '0.1.0' } }), + 'utf-8', + ) + try { + // awkwardly, we have to set mergeConfig to enable autodetecting the rcconfig because otherwise it is explicitly disabled for tests + const { stdout } = await spawn('node', [bin, '--mergeConfig', '--jsonUpgraded'], {}, { cwd: tempDir }) + const pkgData = JSON.parse(stdout) + pkgData.should.not.have.property('ncu-test-v2') + pkgData.should.have.property('ncu-test-tag') + } finally { + await fs.rm(tempDir, { recursive: true, force: true }) + } + }) + + it('filterVersion function', async () => { + const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'npm-check-updates-')) + const configFile = path.join(tempDir, '.ncurc.js') + const pkgFile = path.join(tempDir, 'package.json') + await fs.writeFile( + configFile, + `module.exports = { + filterVersion: version => version === '1.0.0' + }`, + 'utf-8', + ) + await fs.writeFile( + pkgFile, + JSON.stringify({ dependencies: { 'ncu-test-v2': '1.0.0', 'ncu-test-tag': '0.1.0' } }), + 'utf-8', + ) + try { + // awkwardly, we have to set mergeConfig to enable autodetecting the rcconfig because otherwise it is explicitly disabled for tests + const { stdout } = await spawn('node', [bin, '--mergeConfig', '--jsonUpgraded'], {}, { cwd: tempDir }) + const pkgData = JSON.parse(stdout) + pkgData.should.have.property('ncu-test-v2') + pkgData.should.not.have.property('ncu-test-tag') + } finally { + await fs.rm(tempDir, { recursive: true, force: true }) + } + }) + + it('filterResults function', async () => { + const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'npm-check-updates-')) + const configFile = path.join(tempDir, '.ncurc.js') + const pkgFile = path.join(tempDir, 'package.json') + await fs.writeFile( + configFile, + `module.exports = { + filterResults: (name, { upgradedVersion }) => upgradedVersion === '99.9.9' + }`, + 'utf-8', + ) + await fs.writeFile( + pkgFile, + JSON.stringify({ dependencies: { 'ncu-test-v2': '1.0.0', 'ncu-test-tag': '0.1.0' } }), + 'utf-8', + ) + try { + // awkwardly, we have to set mergeConfig to enable autodetecting the rcconfig because otherwise it is explicitly disabled for tests + const { stdout } = await spawn('node', [bin, '--mergeConfig', '--jsonUpgraded'], {}, { cwd: tempDir }) + const pkgData = JSON.parse(stdout) + pkgData.should.have.property('ncu-test-v2') + pkgData.should.have.property('ncu-test-tag') + } finally { + await fs.rm(tempDir, { recursive: true, force: true }) + } + }) + + it('reject function', async () => { + const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'npm-check-updates-')) + const configFile = path.join(tempDir, '.ncurc.js') + const pkgFile = path.join(tempDir, 'package.json') + await fs.writeFile( + configFile, + `module.exports = { + reject: name => name.endsWith('tag') + }`, + 'utf-8', + ) + await fs.writeFile( + pkgFile, + JSON.stringify({ dependencies: { 'ncu-test-v2': '1.0.0', 'ncu-test-tag': '0.1.0' } }), + 'utf-8', + ) + try { + // awkwardly, we have to set mergeConfig to enable autodetecting the rcconfig because otherwise it is explicitly disabled for tests + const { stdout } = await spawn('node', [bin, '--mergeConfig', '--jsonUpgraded'], {}, { cwd: tempDir }) + const pkgData = JSON.parse(stdout) + pkgData.should.have.property('ncu-test-v2') + pkgData.should.not.have.property('ncu-test-tag') + } finally { + await fs.rm(tempDir, { recursive: true, force: true }) + } + }) + + it('rejectVersion function', async () => { + const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'npm-check-updates-')) + const configFile = path.join(tempDir, '.ncurc.js') + const pkgFile = path.join(tempDir, 'package.json') + await fs.writeFile( + configFile, + `module.exports = { + rejectVersion: version => version === '1.0.0' + }`, + 'utf-8', + ) + await fs.writeFile( + pkgFile, + JSON.stringify({ dependencies: { 'ncu-test-v2': '1.0.0', 'ncu-test-tag': '0.1.0' } }), + 'utf-8', + ) + try { + // awkwardly, we have to set mergeConfig to enable autodetecting the rcconfig because otherwise it is explicitly disabled for tests + const { stdout } = await spawn('node', [bin, '--mergeConfig', '--jsonUpgraded'], {}, { cwd: tempDir }) + const pkgData = JSON.parse(stdout) + pkgData.should.not.have.property('ncu-test-v2') + pkgData.should.have.property('ncu-test-tag') + } finally { + await fs.rm(tempDir, { recursive: true, force: true }) + } + }) + }) })