From 8fa50ac269ccdce4bfe8a7e33f7612bb6a30b3e4 Mon Sep 17 00:00:00 2001 From: Raine Revere Date: Wed, 4 Oct 2023 21:23:33 +0000 Subject: [PATCH] README: Add filter/reject predicate help. --- README.md | 108 ++++++++++++++++++++++++++++++++++- src/cli-options.ts | 116 ++++++++++++++++++++++++++++++++++++-- src/types/RunOptions.json | 8 +-- src/types/RunOptions.ts | 8 +-- 4 files changed, 225 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 6b048f76..91882469 100644 --- a/README.md +++ b/README.md @@ -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. @@ -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: @@ -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 /** @@ -617,6 +668,57 @@ registry.json: +## 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: @@ -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 }]) => { diff --git a/src/cli-options.ts b/src/cli-options.ts index 7e126c12..74918e79 100755 --- a/src/cli-options.ts +++ b/src/cli-options.ts @@ -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(`/** @@ -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 @@ -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( @@ -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', @@ -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', @@ -662,6 +768,7 @@ 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', @@ -669,6 +776,7 @@ const cliOptions: CLIOption[] = [ 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', diff --git a/src/types/RunOptions.json b/src/types/RunOptions.json index c1e67ff2..70bdd1af 100644 --- a/src/types/RunOptions.json +++ b/src/types/RunOptions.json @@ -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.", @@ -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.", @@ -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": [ @@ -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.", diff --git a/src/types/RunOptions.ts b/src/types/RunOptions.ts index 99c666a1..200413a6 100644 --- a/src/types/RunOptions.ts +++ b/src/types/RunOptions.ts @@ -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. */ @@ -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. */