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
- Usage
- checkArrayNoConflicts
- checkArrayNotEmpty
- checkArrayUnique
- checkIsNotNegative
- checkIsNotNil
- Appendix
- Published Package Details
- License
- Contributing and Support
- Contributors

Install

To install:

``shell
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].

$3

> ⪢ API reference: [checkArrayNoConflicts][2]

> [!WARNING]
>
> A non-[array type option][3] 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.

`typescript
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) => {
// ...
});
`

`shell
$ 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
`

$3

> ⪢ API reference: [checkArrayNotEmpty][4]

> [!WARNING]
>
> A non-[array type option][3] 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.

`typescript
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) => {
// ...
});
`

`shell
$ 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
`

$3

> ⪢ API reference: [checkArrayUnique][5]

> [!WARNING]
>
> A non-[array type option][3] will always fail this check regardless of the
> argument value.

This check passes when each element in the array is unique.

`typescript
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) => {
// ...
});
`

`shell
$ 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
`

$3

> ⪢ API reference: [checkIsNotNegative][6]

This check passes when an argument value is a non-negative number.

`typescript
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) => {
// ...
});
`

`shell
$ 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
`

$3

> ⪢ API reference: [checkIsNotNil][7]

This check passes when an argument value is not falsy.

`typescript
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) => {
// ...
});
`

`shell
$ 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/][x-repo-docs].

$3

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.

$3

See [LICENSE][x-repo-license].

Contributing and Support

**[New issues][x-repo-choose-new-issue] and [pull requests][x-repo-pr-compare]
are always welcome and greatly appreciated! 🤩** Just as well, you can [star 🌟
this project][x-badge-repo-link] to let me know you found it useful! ✊🏿 Or [buy
me a beer][x-repo-sponsor], I'd appreciate it. Thank you!

See [CONTRIBUTING.md][x-repo-contributing] and [SUPPORT.md][x-repo-support] for
more information.

$3

See the [table of contributors][x-repo-contributors].

[x-badge-blm-image]: https://xunn.at/badge-blm 'Join the movement!'
[x-badge-blm-link]: https://xunn.at/donate-blm
[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-codecov-link]: https://codecov.io/gh/Xunnamius/black-flag
[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-downloads-link]: https://npmtrends.com/@black-flag/checks
[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-npm-link]: https://npm.im/@black-flag/checks
[x-badge-repo-link]: https://github.com/Xunnamius/black-flag
[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-tree-shaking]: https://webpack.js.org/guides/tree-shaking
[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
[x-repo-contributing]: /CONTRIBUTING.md
[x-repo-contributors]: /README.md#contributors
[x-repo-docs]: docs
[x-repo-license]: ./LICENSE
[x-repo-package-json]: package.json
[x-repo-pr-compare]: https://github.com/Xunnamius/black-flag/compare
[x-repo-sponsor]: https://github.com/sponsors/Xunnamius
[x-repo-support]: /.github/SUPPORT.md
[1]:
../extensions/docs/index/type-aliases/BfeBuilderObjectValueExtensions.md#check
[2]: ./docs/index/functions/checkArrayNoConflicts.md
[3]: https://yargs.js.org/docs#api-reference-arraykey
[4]: ./docs/index/functions/checkArrayNotEmpty.md
[5]: ./docs/index/functions/checkArrayUnique.md
[6]: ./docs/index/functions/checkIsNotNegative.md
[7]: ./docs/index/functions/checkIsNotNil.md