Xunnamius
A collection of general purpose check functions for yargs and Black Flag
@black-flag/checks
A collection of general purpose [check functions][1] for yargs and Black Flag.
Install
To install:
npm install @black-flag/checks
Usage
BFC provides the below functions, each of which can be plugged into Black Flag's
(or Yargs's) [check builder property][1].
checkArrayNoConflicts
⪢ API reference:
checkArrayNoConflicts[!WARNING]
A non-array type option will always fail this check regardless of the argument value.
This check passes when at most only one element from each conflict tuple is
present in the array.
import { withBuilderExtensions } from '@black-flag/extensions';
import { checkArrayNoConflicts } from '@black-flag/checks';
export const name = 'my-command';
export const [builder, withHandlerExtensions] = withBuilderExtensions({
x: {
string: true,
array: true,
check: checkArrayNoConflicts('x', [
['1', '2'], // <-- one "conflict tuple"
['3', '4', '5'] // <-- another "conflict tuple"
])
}
});
export const handler = withHandlerExtensions(async (argv) => {
// ...
});
$ my-command ✅
$ my-command -x ✅
$ my-command -x 1 ✅
$ my-command -x 2 ✅
$ my-command -x 1 3 6 ✅
$ my-command -x 2 1 ❌
Array option "x" allows only one of the following values: 1, 2
$ my-command -x 2 4 0 5 ❌
Array option "x" allows only one of the following values: 3, 4, 5
checkArrayNotEmpty
⪢ API reference:
checkArrayNotEmpty[!WARNING]
A non-array type option will always fail this check regardless of the argument value.
This check passes when each member of an array-type argument is a non-empty non-nullish value and the array itself is non-empty.
import { withBuilderExtensions } from '@black-flag/extensions';
import { checkArrayNoConflicts } from '@black-flag/checks';
export const name = 'my-command';
export const [builder, withHandlerExtensions] = withBuilderExtensions({
x: {
string: true,
array: true,
check: checkArrayNotEmpty('x')
}
});
export const handler = withHandlerExtensions(async (argv) => {
// ...
});
$ my-command ✅
$ my-command -x 1 ✅
$ my-command -x 2 ✅
$ my-command -x 1 3 6 ✅
$ my-command -x ❌
Array option "x" requires at least one non-empty value
$ my-command -x '' ❌
Array option "x" requires at least one non-empty value
checkArrayUnique
⪢ API reference:
checkArrayUnique[!WARNING]
A non-array type option will always fail this check regardless of the argument value.
This check passes when each element in the array is unique.
import { withBuilderExtensions } from '@black-flag/extensions';
import { checkArrayNoConflicts } from '@black-flag/checks';
export const name = 'my-command';
export const [builder, withHandlerExtensions] = withBuilderExtensions({
x: {
string: true,
array: true,
check: checkArrayUnique('x')
}
});
export const handler = withHandlerExtensions(async (argv) => {
// ...
});
$ my-command ✅
$ my-command -x ✅
$ my-command -x 1 ✅
$ my-command -x 2 ✅
$ my-command -x 1 3 6 ✅
$ my-command -x 1 1 ❌
Array option "x" must contain only unique values
$ my-command -x true true ❌
Array option "x" must contain only unique values
checkIsNotNegative
⪢ API reference:
checkIsNotNegative
This check passes when an argument value is a non-negative number.
import { withBuilderExtensions } from '@black-flag/extensions';
import { checkArrayNoConflicts } from '@black-flag/checks';
export const name = 'my-command';
export const [builder, withHandlerExtensions] = withBuilderExtensions({
x: {
number: true,
check: checkIsNotNegative('x')
}
});
export const handler = withHandlerExtensions(async (argv) => {
// ...
});
$ my-command ✅
$ my-command -x ✅
$ my-command -x 1 ✅
$ my-command -x 2 ✅
$ my-command -x 0 ✅
$ my-command -x -1 ❌
Array option "x" must have a non-negative value
$ my-command -x -5 ❌
Array option "x" must have a non-negative value
checkIsNotNil
⪢ API reference:
checkIsNotNil
This check passes when an argument value is not falsy.
import { withBuilderExtensions } from '@black-flag/extensions';
import { checkArrayNoConflicts } from '@black-flag/checks';
export const name = 'my-command';
export const [builder, withHandlerExtensions] = withBuilderExtensions({
x: {
string: true,
check: checkIsNotNil('x'),
coerce(arg: string) {
switch (arg) {
case '0': {
return 0;
}
case 'false': {
return false;
}
case 'null': {
return null;
}
case 'undefined': {
return undefined;
}
}
return arg;
}
}
});
export const handler = withHandlerExtensions(async (argv) => {
// ...
});
$ my-command ✅
$ my-command -x 1 ✅
$ my-command -x -1 ✅
$ my-command -x zero ✅
$ my-command -x '!true' ✅
$ my-command -x ❌
Array option "x" must have a non-empty (non-falsy) value
$ my-command -x '' ❌
Array option "x" must have a non-empty (non-falsy) value
$ my-command -x 0 ❌
Array option "x" must have a non-empty (non-falsy) value
$ my-command -x false ❌
Array option "x" must have a non-empty (non-falsy) value
$ my-command -x null ❌
Array option "x" must have a non-empty (non-falsy) value
$ my-command -x undefined ❌
Array option "x" must have a non-empty (non-falsy) value
Appendix
Further documentation can be found under docs/.
Published Package Details
This is a [CJS2 package][x-pkg-cjs-mojito] with statically-analyzable exports
built by Babel for use in Node.js versions that are not end-of-life. For
TypeScript users, this package supports both "Node10" and "Node16" module
resolution strategies.
require(...)) and ESM (via import { ... } from ...
or await import(...)) source will load this package from the same entry points
when using Node. This has several benefits, the foremost being: less code
shipped/smaller package size, avoiding [dual package
hazard][x-pkg-dual-package-hazard] entirely, distributables are not
packed/bundled/uglified, a drastically less complex build process, and CJS
consumers aren't shafted.
Each entry point (i.e. ENTRY) in package.json's
exports[ENTRY] object includes one or more [export
conditions][x-pkg-exports-conditions]. These entries may or may not include: an
[exports[ENTRY].types][x-pkg-exports-types-key] condition pointing to a type
declaration file for TypeScript and IDEs, a
[exports[ENTRY].module][x-pkg-exports-module-key] condition pointing to
(usually ESM) source for Webpack/Rollup, a exports[ENTRY].node and/or
exports[ENTRY].default condition pointing to (usually CJS2) source for Node.js
require/import and for browsers and other environments, and [other
conditions][x-pkg-exports-conditions] not enumerated here. Check the
package.json file to see which export conditions are
supported.
Note that, regardless of the [{ "type": "..." }][x-pkg-type] specified in
package.json, any JavaScript files written in ESM
syntax (including distributables) will always have the .mjs extension. Note
also that package.json may include the
[sideEffects][x-pkg-side-effects-key] key, which is almost always false for
optimal tree shaking where appropriate.
License
See LICENSE.
Contributing and Support
[New issues][x-repo-choose-new-issue] and pull requests are always welcome and greatly appreciated! 🤩 Just as well, you can star 🌟 this project to let me know you found it useful! ✊🏿 Or buy me a beer, I'd appreciate it. Thank you!
See CONTRIBUTING.md and SUPPORT.md for more information.
Contributors
See the table of contributors.
[x-badge-blm-image]: https://xunn.at/badge-blm 'Join the movement!'
[x-badge-codecov-image]: https://img.shields.io/codecov/c/github/Xunnamius/black-flag/main?style=flat-square&token=HWRIOBAAPW&flag=package.main_checks 'Is this package well-tested?'
[x-badge-downloads-image]: https://img.shields.io/npm/dm/@black-flag/checks?style=flat-square 'Number of times this package has been downloaded per month'
[x-badge-lastcommit-image]: https://img.shields.io/github/last-commit/Xunnamius/black-flag?style=flat-square 'Latest commit timestamp' [x-badge-license-image]: https://img.shields.io/npm/l/@black-flag/checks?style=flat-square "This package's source license" [x-badge-license-link]: https://github.com/Xunnamius/black-flag/blob/main/LICENSE [x-badge-npm-image]: https://xunn.at/npm-pkg-version/@black-flag/checks 'Install this package using npm or yarn!'
[x-badge-semanticrelease-image]: https://xunn.at/badge-semantic-release 'This repo practices continuous integration and deployment!' [x-badge-semanticrelease-link]: https://github.com/semantic-release/semantic-release [x-pkg-cjs-mojito]: https://dev.to/jakobjingleheimer/configuring-commonjs-es-modules-for-nodejs-12ed#publish-only-a-cjs-distribution-with-property-exports [x-pkg-dual-package-hazard]: https://nodejs.org/api/packages.html#dual-package-hazard [x-pkg-exports-conditions]: https://webpack.js.org/guides/package-exports#reference-syntax [x-pkg-exports-module-key]: https://webpack.js.org/guides/package-exports#providing-commonjs-and-esm-version-stateless [x-pkg-exports-types-key]: https://devblogs.microsoft.com/typescript/announcing-typescript-4-5-beta#packagejson-exports-imports-and-self-referencing [x-pkg-side-effects-key]: https://webpack.js.org/guides/tree-shaking#mark-the-file-as-side-effect-free
[x-pkg-type]: https://github.com/nodejs/node/blob/8d8e06a345043bec787e904edc9a2f5c5e9c275f/doc/api/packages.md#type [x-repo-choose-new-issue]: https://github.com/Xunnamius/black-flag/issues/new/choose
[1]: ../extensions/docs/index/type-aliases/BfeBuilderObjectValueExtensions.md#check