From 13eea1bc53c42836dc91d5d517a2b5e5f34bccb0 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 | 118 +++++++++++++++++++++++++++--- src/cli-options.ts | 146 ++++++++++++++++++++++++++++++++++---- src/types/RunOptions.json | 8 +-- src/types/RunOptions.ts | 8 +-- 4 files changed, 249 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index 6b048f76..1317764a 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 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. @@ -455,7 +481,7 @@ Only available in .ncurc.js or when importing npm-check-updates as a module. @returns {boolean} Return true if the upgrade should be kept, otherwise it will be ignored. */ filterResults: (packageName, { current, currentSemver, upgraded, upgradedSemver }) => { - const currentMajor = parseInt(currentSemver?.[0]?.major, 10) + const currentMajor = parseInt(currentSemver[0]?.major, 10) const upgradedMajor = parseInt(upgradedSemver?.major, 10) if (currentMajor && upgradedMajor) { return currentMajor < upgradedMajor @@ -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: @@ -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 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: @@ -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' } ``` diff --git a/src/cli-options.ts b/src/cli-options.ts index 7e126c12..b2d86f7a 100755 --- a/src/cli-options.ts +++ b/src/cli-options.ts @@ -142,9 +142,9 @@ ${codeBlock( ${chalk.green('filterResults')}: (packageName, { current, currentSemver, upgraded, upgradedSemver }) ${chalk.cyan( '=>', )} { - ${chalk.cyan('const')} currentMajor ${chalk.red('=')} parseInt(currentSemver?.[${chalk.cyan( - '0', - )}]?.major, ${chalk.cyan('10')}) + ${chalk.cyan('const')} currentMajor ${chalk.red('=')} parseInt(currentSemver[${chalk.cyan('0')}]?.major, ${chalk.cyan( + '10', + )}) ${chalk.cyan('const')} upgradedMajor ${chalk.red('=')} parseInt(upgradedSemver?.major, ${chalk.cyan('10')}) ${chalk.red('if')} (currentMajor ${chalk.red('&&')} upgradedMajor) { ${chalk.red('return')} currentMajor ${chalk.red('<')} upgradedMajor @@ -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(`/** @@ -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 @@ -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 }, @@ -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', @@ -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', @@ -662,6 +776,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 +784,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. */