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 77e91c3
Show file tree
Hide file tree
Showing 4 changed files with 245 additions and 27 deletions.
116 changes: 109 additions & 7 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 semver A parsed Semver array 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, semver) => {
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 semver A parsed Semver array 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, semver) => {
if (name.startsWith('@myorg/') && parseInt(semver[0]?.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 semver A parsed Semver array 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, semver) => {
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 semver A parsed Semver array 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, semver) => {
if (name.startsWith('@myorg/') && parseInt(semver[0]?.major) > 5) {
return true
}
return false
}
```
## target
Usage:
Expand All @@ -640,13 +742,13 @@ 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)
@returns One of the valid target values (specified in the table above).
@param name The name of the dependency.
@param semver 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 }]) => {
if (major === '0') return 'minor'
target: (name, semver) => {
if (parseInt(semver[0]?.major) === '0') return 'minor'
return 'latest'
}
```
Expand Down
140 changes: 128 additions & 12 deletions src/cli-options.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -199,11 +199,125 @@ 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 semver A parsed Semver array 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, semver) ${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 semver A parsed Semver array 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, semver) ${chalk.cyan('=>')} {
${chalk.red('if')} (name.startsWith(${chalk.yellow(`'@myorg/'`)}) ${chalk.red(
'&&',
)} parseInt(semver[0]?.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 }) => {
/** If markdown, surround inline code with backticks. */
const codeInline = (code: string) => (markdown ? `\`${code}\`` : code)

return `The inverse of ${codeInline(
'--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 semver A parsed Semver array 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, semver) ${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 }) => {
/** If markdown, surround inline code with backticks. */
const codeInline = (code: string) => (markdown ? `\`${code}\`` : code)

return `The inverse of ${codeInline(
'--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 semver A parsed Semver array 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, semver) ${chalk.cyan('=>')} {
${chalk.red('if')} (name.startsWith(${chalk.yellow(`'@myorg/'`)}) ${chalk.red(
'&&',
)} parseInt(semver[0]?.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 +334,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 @@ -265,17 +379,15 @@ 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)
@returns One of the valid target values (specified in the table above).
@param name The name of the dependency.
@param semver 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(
'target',
)}: (dependencyName, [{ semver, version, operator, major, minor, patch, release, build }]) ${chalk.cyan('=>')} {
${chalk.red('if')} (major ${chalk.red('===')} ${chalk.yellow("'0'")}) ${chalk.red('return')} ${chalk.yellow(
"'minor'",
)}
${chalk.green('target')}: (name, semver) ${chalk.cyan('=>')} {
${chalk.red('if')} (parseInt(semver[0]?.major) ${chalk.red('===')} ${chalk.yellow("'0'")}) ${chalk.red(
'return',
)} ${chalk.yellow("'minor'")}
${chalk.red('return')} ${chalk.yellow("'latest'")}
}`,
{ markdown },
Expand Down Expand Up @@ -506,6 +618,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 +634,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 +776,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
Loading

0 comments on commit 77e91c3

Please sign in to comment.