Skip to content

Commit

Permalink
README: Add filter/reject predicate help.
Browse files Browse the repository at this point in the history
  • Loading branch information
@raineorshine
raineorshine committed Oct 4, 2023
1 parent 6d0c3e3 commit 8fa50ac
Show file tree
Hide file tree
Showing 4 changed files with 225 additions and 15 deletions.
108 changes: 105 additions & 3 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -437,6 +437,32 @@ Example:
✓ react-dnd 10.0.0 → 11.1.3
Saving partially upgraded package.json

## filter

Usage:

ncu --filter [p]
ncu -f [p]

Include only package names matching the given string, wildcard, glob, comma-or-space-delimited list, /regex/, or predicate function.

The predicate function is only available in .ncurc.js or when importing npm-check-updates as a module, not on the command line.

```js
/**
@param name The name of the dependency.
@param parsedVersion A parsed Semver object of the upgraded version.
(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, parsedVersion) => {
if (name.startsWith('@myorg/')) {
return false
}
return true
}
```

## filterResults

Filters out upgrades based on a user provided function.
Expand Down Expand Up @@ -466,6 +492,31 @@ filterResults: (packageName, { current, currentSemver, upgraded, upgradedSemver
For the SemVer type definition, see: https://git.coolaj86.com/coolaj86/semver-utils.js#semverutils-parse-semverstring
## filterVersion
Usage:
ncu --filterVersion [p]
Include only versions matching the given string, wildcard, glob, comma-or-space-delimited list, /regex/, or predicate function.
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.
```js
/**
@param name The name of the dependency.
@param parsedVersion A parsed Semver object of the upgraded version.
(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, parsedVersion) => {
if (name.startsWith('@myorg/') && parseInt(parsedVersion?.major) > 5) {
return false
}
return true
}
```
## format
Usage:
Expand All @@ -486,7 +537,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.
Only available in .ncurc.js or when importing npm-check-updates as a module, not on the command line.
```js
/**
Expand Down Expand Up @@ -617,6 +668,57 @@ registry.json:
</td></tr>
</table>
## reject
Usage:
ncu --reject [p]
ncu -x [p]
The inverse of --filter. Exclude package names matching the given string, wildcard, glob, comma-or-space-delimited list, /regex/, or predicate function.
The predicate function is only available in .ncurc.js or when importing npm-check-updates as a module, not on the command line.
```js
/**
@param name The name of the dependency.
@param parsedVersion A parsed Semver object of the upgraded version.
(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, parsedVersion) => {
if (name.startsWith('@myorg/')) {
return true
}
return false
}
```
## rejectVersion
Usage:
ncu --rejectVersion [p]
The inverse of --filterVersion. Exclude versions matching the given string, wildcard, glob, comma-or-space-delimited list, /regex/, or predicate function.
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.
```js
/**
@param name The name of the dependency.
@param parsedVersion A parsed Semver object of the upgraded version.
(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.
*/
filterVersionFunction: (name, parsedVersion) => {
if (name.startsWith('@myorg/') && parseInt(parsedVersion?.major) > 5) {
return true
}
return false
}
```
## target
Usage:
Expand All @@ -641,8 +743,8 @@ You can also specify a custom function in your .ncurc.js file, or when importing
```js
/** Upgrade major version zero to the next minor version, and everything else to latest.
@param dependencyName The name of the dependency.
@param parsedVersion A parsed Semver object from semver-utils.
(See https://git.coolaj86.com/coolaj86/semver-utils.js#semverutils-parse-semverstring)
@param parsedVersion A parsed Semver object of the upgraded version.
(See: https://git.coolaj86.com/coolaj86/semver-utils.js#semverutils-parse-semverstring)
@returns One of the valid target values (specified in the table above).
*/
target: (dependencyName, [{ semver, version, operator, major, minor, patch, release, build }]) => {
Expand Down
116 changes: 112 additions & 4 deletions src/cli-options.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -199,11 +199,115 @@ const extendedHelpInstall: ExtendedHelp = ({ markdown }) => {
`
}

/** Extended help for the --filter option. */
const extendedHelpFilterFunction: ExtendedHelp = ({ markdown }) => {
return `Include only package names matching the given string, wildcard, glob, comma-or-space-delimited list, /regex/, or predicate function.
The predicate function is only available in .ncurc.js or when importing npm-check-updates as a module, not on the command line.
${codeBlock(
`${chalk.gray(`/**
@param name The name of the dependency.
@param parsedVersion A parsed Semver object of the upgraded version.
(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, parsedVersion) ${chalk.cyan('=>')} {
${chalk.red('if')} (name.startsWith(${chalk.yellow(`'@myorg/'`)})) {
${chalk.red('return')} ${chalk.cyan('false')}
}
${chalk.red('return')} ${chalk.cyan('true')}
}`,
{ markdown },
)}
`
}

/** Extended help for the --filterVersion option. */
const extendedHelpFilterVersionFunction: ExtendedHelp = ({ markdown }) => {
return `Include only versions matching the given string, wildcard, glob, comma-or-space-delimited list, /regex/, or predicate function.
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.
${codeBlock(
`${chalk.gray(`/**
@param name The name of the dependency.
@param parsedVersion A parsed Semver object of the upgraded version.
(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, parsedVersion) ${chalk.cyan('=>')} {
${chalk.red('if')} (name.startsWith(${chalk.yellow(`'@myorg/'`)}) ${chalk.red(
'&&',
)} parseInt(parsedVersion?.major) ${chalk.cyan('>')} ${chalk.cyan(`5`)}) {
${chalk.red('return')} ${chalk.cyan('false')}
}
${chalk.red('return')} ${chalk.cyan('true')}
}`,
{ markdown },
)}
`
}

/** Extended help for the --reject option. */
const extendedHelpRejectFunction: ExtendedHelp = ({ markdown }) => {
return `The inverse of --filter. Exclude package names matching the given string, wildcard, glob, comma-or-space-delimited list, /regex/, or predicate function.
The predicate function is only available in .ncurc.js or when importing npm-check-updates as a module, not on the command line.
${codeBlock(
`${chalk.gray(`/**
@param name The name of the dependency.
@param parsedVersion A parsed Semver object of the upgraded version.
(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, parsedVersion) ${chalk.cyan('=>')} {
${chalk.red('if')} (name.startsWith(${chalk.yellow(`'@myorg/'`)})) {
${chalk.red('return')} ${chalk.cyan('true')}
}
${chalk.red('return')} ${chalk.cyan('false')}
}`,
{ markdown },
)}
`
}

/** Extended help for the --rejectVersion option. */
const extendedHelpRejectVersionFunction: ExtendedHelp = ({ markdown }) => {
return `The inverse of --filterVersion. Exclude versions matching the given string, wildcard, glob, comma-or-space-delimited list, /regex/, or predicate function.
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.
${codeBlock(
`${chalk.gray(`/**
@param name The name of the dependency.
@param parsedVersion A parsed Semver object of the upgraded version.
(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('filterVersionFunction')}: (name, parsedVersion) ${chalk.cyan('=>')} {
${chalk.red('if')} (name.startsWith(${chalk.yellow(`'@myorg/'`)}) ${chalk.red(
'&&',
)} parseInt(parsedVersion?.major) ${chalk.cyan('>')} ${chalk.cyan(`5`)}) {
${chalk.red('return')} ${chalk.cyan('true')}
}
${chalk.red('return')} ${chalk.cyan('false')}
}`,
{ markdown },
)}
`
}

/** Extended help for the --group option. */
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.
Only available in .ncurc.js or when importing npm-check-updates as a module, not on the command line.
${codeBlock(
`${chalk.gray(`/**
Expand All @@ -220,7 +324,7 @@ ${chalk.green('groupFunction')}: (name, defaultGroup, currentSpec, upgradedSpec,
)} defaultGroup ${chalk.red('===')} ${chalk.yellow(`'minor'`)}) {
${chalk.red('return')} ${chalk.yellow(`'major'`)}
}
${chalk.red('if')} (name.startsWith('@myorg/')) {
${chalk.red('if')} (name.startsWith(${chalk.yellow(`'@myorg/'`)})) {
${chalk.red('return')} ${chalk.yellow(`'My Org'`)}
}
${chalk.red('return')} defaultGroup
Expand Down Expand Up @@ -266,8 +370,8 @@ You can also specify a custom function in your .ncurc.js file, or when importing
${codeBlock(
`${chalk.gray(`/** Upgrade major version zero to the next minor version, and everything else to latest.
@param dependencyName The name of the dependency.
@param parsedVersion A parsed Semver object from semver-utils.
(See https://git.coolaj86.com/coolaj86/semver-utils.js#semverutils-parse-semverstring)
@param parsedVersion A parsed Semver object of the upgraded version.
(See: https://git.coolaj86.com/coolaj86/semver-utils.js#semverutils-parse-semverstring)
@returns One of the valid target values (specified in the table above).
*/`)}
${chalk.green(
Expand Down Expand Up @@ -506,6 +610,7 @@ const cliOptions: CLIOption[] = [
'Include only package names matching the given string, wildcard, glob, comma-or-space-delimited list, /regex/, or predicate function.',
type: 'string | RegExp | (string | RegExp)[] | FilterFunction',
parse: (value, accum) => [...(accum || []), value],
help: extendedHelpFilterFunction,
},
{
long: 'filterResults',
Expand All @@ -521,6 +626,7 @@ const cliOptions: CLIOption[] = [
description: 'Filter on package version using comma-or-space-delimited list, /regex/, or predicate function.',
type: 'string | RegExp | (string | RegExp)[] | FilterFunction',
parse: (value, accum) => [...(accum || []), value],
help: extendedHelpFilterVersionFunction,
},
{
long: 'format',
Expand Down Expand Up @@ -662,13 +768,15 @@ const cliOptions: CLIOption[] = [
'Exclude packages matching the given string, wildcard, glob, comma-or-space-delimited list, /regex/, or predicate function.',
type: 'string | RegExp | (string | RegExp)[] | FilterFunction',
parse: (value, accum) => [...(accum || []), value],
help: extendedHelpRejectFunction,
},
{
long: 'rejectVersion',
arg: 'p',
description: 'Exclude package.json versions using comma-or-space-delimited list, /regex/, or predicate function.',
type: 'string | RegExp | (string | RegExp)[] | FilterFunction',
parse: (value, accum) => [...(accum || []), value],
help: extendedHelpRejectVersionFunction,
},
{
long: 'removeRange',
Expand Down
8 changes: 4 additions & 4 deletions src/types/RunOptions.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -268,7 +268,7 @@
"type": "string"
}
],
"description": "Include only package names matching the given string, wildcard, glob, comma-or-space-delimited list, /regex/, or predicate function."
"description": "Include only package names matching the given string, wildcard, glob, comma-or-space-delimited list, /regex/, or predicate function. Run \"ncu --help --filter\" for details."
},
"filterResults": {
"description": "Filters out upgrades based on a user provided function. Run \"ncu --help --filterResults\" for details.",
Expand Down Expand Up @@ -300,7 +300,7 @@
"type": "string"
}
],
"description": "Filter on package version using comma-or-space-delimited list, /regex/, or predicate function."
"description": "Filter on package version using comma-or-space-delimited list, /regex/, or predicate function. Run \"ncu --help --filterVersion\" for details."
},
"format": {
"description": "Modify the output formatting or show additional information. Specify one or more comma-delimited values: group, ownerChanged, repo, time, lines. Run \"ncu --help --format\" for details.",
Expand Down Expand Up @@ -419,7 +419,7 @@
"type": "string"
}
],
"description": "Exclude packages matching the given string, wildcard, glob, comma-or-space-delimited list, /regex/, or predicate function."
"description": "Exclude packages matching the given string, wildcard, glob, comma-or-space-delimited list, /regex/, or predicate function. Run \"ncu --help --reject\" for details."
},
"rejectVersion": {
"anyOf": [
Expand Down Expand Up @@ -447,7 +447,7 @@
"type": "string"
}
],
"description": "Exclude package.json versions using comma-or-space-delimited list, /regex/, or predicate function."
"description": "Exclude package.json versions using comma-or-space-delimited list, /regex/, or predicate function. Run \"ncu --help --rejectVersion\" for details."
},
"removeRange": {
"description": "Remove version ranges from the final package version.",
Expand Down
8 changes: 4 additions & 4 deletions src/types/RunOptions.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -73,13 +73,13 @@ export interface RunOptions {
*/
errorLevel?: number

/** Include only package names matching the given string, wildcard, glob, comma-or-space-delimited list, /regex/, or predicate function. */
/** Include only package names matching the given string, wildcard, glob, comma-or-space-delimited list, /regex/, or predicate function. Run "ncu --help --filter" for details. */
filter?: string | RegExp | (string | RegExp)[] | FilterFunction

/** Filters out upgrades based on a user provided function. Run "ncu --help --filterResults" for details. */
filterResults?: FilterResultsFunction

/** Filter on package version using comma-or-space-delimited list, /regex/, or predicate function. */
/** Filter on package version using comma-or-space-delimited list, /regex/, or predicate function. Run "ncu --help --filterVersion" for details. */
filterVersion?: string | RegExp | (string | RegExp)[] | FilterFunction

/** Modify the output formatting or show additional information. Specify one or more comma-delimited values: group, ownerChanged, repo, time, lines. Run "ncu --help --format" for details. */
Expand Down Expand Up @@ -145,10 +145,10 @@ export interface RunOptions {
/** Specify whether --registry refers to a full npm registry or a simple JSON file or url: npm, json. (default: npm) Run "ncu --help --registryType" for details. */
registryType?: 'npm' | 'json'

/** Exclude packages matching the given string, wildcard, glob, comma-or-space-delimited list, /regex/, or predicate function. */
/** Exclude packages matching the given string, wildcard, glob, comma-or-space-delimited list, /regex/, or predicate function. Run "ncu --help --reject" for details. */
reject?: string | RegExp | (string | RegExp)[] | FilterFunction

/** Exclude package.json versions using comma-or-space-delimited list, /regex/, or predicate function. */
/** Exclude package.json versions using comma-or-space-delimited list, /regex/, or predicate function. Run "ncu --help --rejectVersion" for details. */
rejectVersion?: string | RegExp | (string | RegExp)[] | FilterFunction

/** Remove version ranges from the final package version. */
Expand Down

0 comments on commit 8fa50ac

Please sign in to comment.