diff --git a/README.md b/README.md index 741e3f7..944f704 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,18 @@ # validator.js-asserts + A set of extra asserts for [validator.js](https://github.com/guillaumepotier/validator.js). ## Status -[![npm version][npm-image]][npm-url] [![build status][travis-image]][travis-url] + +[![npm version][npm-image]][npm-url] +[![build status][ci-image]][ci-url] ## Installation + Install the package via `npm`: ```sh -$ npm install --save validator.js-asserts +npm install --save validator.js-asserts ``` ### Peer dependencies @@ -19,121 +23,149 @@ Peer dependencies are listed on `package.json` under `peerDependencies`. The `peerDependenciesMeta` key identifies which peer dependencies are optional. NPM will not automatically install optional peer dependencies. See [the NPM documentation](https://docs.npmjs.com/cli/v11/configuring-npm/package-json#peerdependenciesmeta) for more information. ## Asserts + The following set of extra asserts are provided by this package: -- [AbaRoutingNumber](#abaroutingnumber) (requires `abavalidator`) -- [BankIdentifierCode](#bankidentifiercode-bic) (_BIC_) -- [BigNumber](#bignumber) (requires `bignumber.js`) -- [BigNumberEqualTo](#bignumberequalto) (requires `bignumber.js`) -- [BigNumberGreaterThan](#bignumbergreaterthan) (requires `bignumber.js`) -- [BigNumberGreaterThanOrEqualTo](#bignumbergreaterthanorequalto) (requires `bignumber.js`) -- [BigNumberLessThan](#bignumberlessthan) (requires `bignumber.js`) -- [BigNumberLessThanOrEqualTo](#bignumberlessthanorequalto) (requires `bignumber.js`) -- [Boolean](#boolean) -- [Callback](#callback) (requires `callback`) -- [CaZipCode](#cazipcode) -- [CpfNumber](#cpfnumber) (requires `cpf`) -- [CreditCard](#creditcard) (requires `creditcard`) -- [CurpNumber](#curpnumber) (requires `curp`) -- [Date](#date) (requires `moment` for format validation only) -- [DateDiffGreaterThan](#datediffgreaterthan) (requires `moment`) -- [DateDiffGreaterThanOrEqualTo](#datediffgreaterthanorequalto) (requires `moment`) -- [DateDiffLessThan](#datedifflessthan) (requires `moment`) -- [DateDiffLessThanOrEqualTo](#datedifflessthanorequalto) (requires `moment`) -- [Email](#email) (requires `validator`) -- [EqualKeys](#equalkeys) -- [Hash](#hash) -- [Integer](#integer) -- [InternationalBankAccountNumber](#internationalbankaccountnumber-iban) (_IBAN_, requires `iban`) -- [Ip](#ip) -- [Iso3166Country](#iso3166country) (requires `isoc`) -- [Json](#json) -- [NotEmpty](#notempty) -- [NullOr](#nullor) -- [NullOrDate](#nullordate) -- [NullOrBoolean](#nullorboolean) -- [NullOrString](#nullorstring) -- [Phone](#phone) (requires `google-libphonenumber`) -- [PlainObject](#plainobject) -- [RfcNumber](#rfcnumber) (requires `validate-rfc`) -- [TaxpayerIdentificationNumber](#taxpayeridentificationnumber) (_TIN_, requires `tin-validator`) -- [UkModulusChecking](#ukmoduluschecking) (requires `uk-modulus-checking`) -- [Uri](#uri) (requires `urijs`) -- [UsSubdivision](#ussubdivision) -- [UsZipCode](#uszipcode) -- [Uuid](#uuid) + +| Assert | Peer Dependency | +| :------------------------------------------------------------------------------ | :--------------------------------------------------- | +| [AbaRoutingNumber](#abaroutingnumber) | [`abavalidator`][abavalidator-url] | +| [BankIdentifierCode](#bankidentifiercode-bic) (_BIC_) | | +| [BigNumber](#bignumber) | [`bignumber.js`][bignumber-url] | +| [BigNumberEqualTo](#bignumberequalto) | [`bignumber.js`][bignumber-url] | +| [BigNumberGreaterThan](#bignumbergreaterthan) | [`bignumber.js`][bignumber-url] | +| [BigNumberGreaterThanOrEqualTo](#bignumbergreaterthanorequalto) | [`bignumber.js`][bignumber-url] | +| [BigNumberLessThan](#bignumberlessthan) | [`bignumber.js`][bignumber-url] | +| [BigNumberLessThanOrEqualTo](#bignumberlessthanorequalto) | [`bignumber.js`][bignumber-url] | +| [Boolean](#boolean) | | +| [Callback](#callback) | [`callback`][callback-url] | +| [CaZipCode](#cazipcode) | | +| [CpfNumber](#cpfnumber) | [`cpf`][cpf-url] | +| [CreditCard](#creditcard) | [`creditcard`][creditcard-url] | +| [CurpNumber](#curpnumber) | [`curp`][curp-url] | +| [Date](#date) | [`moment`][moment-url] | +| [DateDiffGreaterThan](#datediffgreaterthan) | [`moment`][moment-url] | +| [DateDiffGreaterThanOrEqualTo](#datediffgreaterthanorequalto) | [`moment`][moment-url] | +| [DateDiffLessThan](#datedifflessthan) | [`moment`][moment-url] | +| [DateDiffLessThanOrEqualTo](#datedifflessthanorequalto) | [`moment`][moment-url] | +| [Email](#email) | [`validator`][validator-url] | +| [EqualKeys](#equalkeys) | | +| [Hash](#hash) | | +| [Integer](#integer) | | +| [InternationalBankAccountNumber](#internationalbankaccountnumber-iban) (_IBAN_) | [`iban`][iban-url] | +| [Ip](#ip) | | +| [Iso3166Country](#iso3166country) | [`isoc`][isoc-url] | +| [Json](#json) | | +| [NotEmpty](#notempty) | | +| [NullOr](#nullor) | | +| [NullOrDate](#nullordate) | | +| [NullOrBoolean](#nullorboolean) | | +| [NullOrString](#nullorstring) | | +| [Phone](#phone) | [`google-libphonenumber`][google-libphonenumber-url] | +| [PlainObject](#plainobject) | | +| [RfcNumber](#rfcnumber) | [`validate-rfc`][validate-rfc-url] | +| [TaxpayerIdentificationNumber](#taxpayeridentificationnumber) (_TIN_) | [`tin-validator`][tin-validator-url] | +| [UkModulusChecking](#ukmoduluschecking) | [`uk-modulus-checking`][uk-modulus-checking-url] | +| [Uri](#uri) | [`urijs`][urijs-url] | +| [UsSubdivision](#ussubdivision) | | +| [UsZipCode](#uszipcode) | | +| [Uuid](#uuid) | | ### AbaRoutingNumber + Tests if the value is a valid [ABA Routing Number](http://www.accuity.com/PageFiles/255/ROUTING_NUMBER_POLICY.pdf). -### BankIdentifierCode (*BIC*) +### BankIdentifierCode (_BIC_) + Tests if the value is a valid Bank Identifier Code (_BIC_) as defined in the [ISO-9362](http://www.iso.org/iso/home/store/catalogue_tc/catalogue_detail.htm?csnumber=60390) standard. ### BigNumber + Tests if the value is a valid `BigNumber`. ### BigNumberEqualTo + Tests if a `BigNumber` is equal to a given value. #### Arguments + - `value` (required) ### BigNumberGreaterThan + Tests if a `BigNumber` is greater than a given threshold. #### Arguments + - `threshold` (required) ### BigNumberGreaterThanOrEqualTo + Tests if a `BigNumber` is greater than or equal to a given threshold. #### Arguments + - `threshold` (required) ### BigNumberLessThan + Tests if a `BigNumber` is less than a given threshold. #### Arguments + - `threshold` (required) ### BigNumberLessThanOrEqualTo + Tests if a `BigNumber` is less than or equal to a given threshold. #### Arguments + - `threshold` (required) ### Boolean + Tests if the value is a boolean. ### Callback + Allows you to add custom rules by giving a callback function and a custom class. #### Arguments + - `callback` (required) - the callback function. - `customClass` (required) - the name of the class. ### CaZipCode -Tests if the value is valid Canada zip code. + +Tests if the value is a valid Canada zip code (postal code). We only allow initial characters from the list on the [site](https://www.canadapost-postescanada.ca/cpc/en/support/articles/addressing-guidelines/postal-codes.page). ### CpfNumber -Tests if the value is valid CPF number. + +Tests if the value is a valid Brazilian CPF (Cadastro de Pessoas Físicas) number. ### CreditCard + Tests if the value is a valid credit card number using the Luhn10 algorithm. ### CurpNumber -Tests if the value is valid CURP number. + +Tests if the value is a valid Mexican CURP (Clave Única de Registro de Población) number. ### Date + Tests if the value is a valid date. #### Arguments + - `format` (optional) - the format in which the date must be in. ### DateDiffGreaterThan + Tests if the difference between two dates is greater than a given threshold. #### Arguments + - `threshold` (required) - `options` - `absolute` - whether the comparison should use the absolute value of the measured difference. @@ -142,9 +174,11 @@ Tests if the difference between two dates is greater than a given threshold. - `unit` - the unit of the difference measurement (`years`, `months`, `weeks`, `days`, `hours`, `minutes` and `seconds`). ### DateDiffGreaterThanOrEqualTo + Tests if the difference between two dates is greater than or equal to a given threshold. #### Arguments + - `threshold` (required) - `options` - `absolute` - whether the comparison should use the absolute value of the measured difference. @@ -153,9 +187,11 @@ Tests if the difference between two dates is greater than or equal to a given th - `unit` - the unit of the difference measurement (`years`, `months`, `weeks`, `days`, `hours`, `minutes` and `seconds`). ### DateDiffLessThan + Tests if the difference between two dates is less than a given threshold. #### Arguments + - `threshold` (required) - `options` - `absolute` - whether the comparison should use the absolute value of the measured difference. @@ -164,9 +200,11 @@ Tests if the difference between two dates is less than a given threshold. - `unit` - the unit of the difference measurement (`years`, `months`, `weeks`, `days`, `hours`, `minutes` and `seconds`). ### DateDiffLessThanOrEqualTo + Tests if the difference between two dates is less than or equal to a given threshold. #### Arguments + - `threshold` (required) - `options` - `absolute` - whether the comparison should use the absolute value of the measured difference. @@ -175,106 +213,135 @@ Tests if the difference between two dates is less than or equal to a given thres - `unit` - the unit of the difference measurement (`years`, `months`, `weeks`, `days`, `hours`, `minutes` and `seconds`). ### Email + Tests if the value is a valid email. ### EqualKeys + Tests if the object has the exact given set of keys (missing or extra keys are not allowed). #### Arguments + - `keys` (optional) - the keys that the object being tested must equal. If none are defined, no keys will be allowed. ### Hash + Tests if the value is a valid hash. #### Arguments + - `algorithm` (required) - the algorithm to test the hash for. Supported algorithms are `sha1`, `sha256` and `sha512`. ### Integer + Tests if the value is an integer. -### InternationalBankAccountNumber (*IBAN*) +### InternationalBankAccountNumber (_IBAN_) + Tests if the value is a valid International Bank Account Number (_IBAN_) as defined in the [13616-1](http://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=41031) standard. ### Ip -Tests if the value is a valid ip (v4 or v6). + +Tests if the value is a valid `IP` (v4 or v6). ### Iso3166Country + Tests if the value is a valid ISO-3166 country by alpha-3 code, alpha-2 code, short name or uppercase name. All officially-assigned, transitionally-assigned and user-assigned codes are considered valid. ### Json -Tests if the value is valid json. + +Tests if the value is valid `JSON`. ### NotEmpty + Tests if the value is not an empty (empty object, empty array, empty string, etc). ### NullOr -Tests if the value is a `null` or validates agains the assert received as an argument. + +Tests if the value is a `null` or validates against the assert received as an argument. ### NullOrBoolean + Tests if the value is a `null` or `boolean`. ### NullOrString + Tests if the value is a `null` or `string`, optionally within some boundaries. #### Arguments + - `boundaries` (optional) - `max` and/or `min` boundaries to test the string for. ### Phone + Tests if the phone is valid and optionally if it belongs to the given country. The phone can be in the national or E164 formats. #### Arguments + - `countryCode` (optional) - the ISO-3166 alpha-2 country code to test the phone validity in. ### PlainObject + Tests if the value is a plain object. ### RfcNumber -Tests if the value is a valid RFC number. + +Tests if the value is a valid Mexican `RFC` (Registro Federal de Contribuyentes) number. ### TaxpayerIdentificationNumber -Tests if the value is a valid Taxpayer Identification Number (_TIN_) as defined by the [U.S. IRS](http://www.irs.gov/Individuals/International-Taxpayers/Taxpayer-Identification-Numbers-TIN). + +Tests if the value is a valid Taxpayer Identification Number `TIN` as defined by the [U.S. IRS](http://www.irs.gov/Individuals/International-Taxpayers/Taxpayer-Identification-Numbers-TIN). ### UkModulusChecking + Tests if the given `accountNumber` and `sortCode` represent a valid `Faster Payment Account`. ### Uri -Tests if the value is a valid `uri` which must contain at least a protocol and a hostname. + +Tests if the value is a valid `URI` (Uniform Resource Identifier) which must contain at least a protocol and a hostname. #### Arguments -- `constraints` (optional) - additional uri parts to test for (e.g. `{ is: 'domain', protocol: 'https' }`). + +- `constraints` (optional) - additional `URI` parts to test for (e.g. `{ is: 'domain', protocol: 'https' }`). ### UsSubdivision + Tests if the value is a valid US subdivision or not. By default, codes in the short ("alpha2", e.g. `CA`) or full form (e.g. `US-CA`) are allowed. All US subdivisions categories are supported: `districts` (1), `states` (50) and `outlying` territories (6). #### Arguments + - `alpha2Only` (optional) - whether to restrict validation to the "alpha2" short code form only. - `categories` (optional) - a list of categories to restrict code validation to (e.g. `['states', 'outlying']`). ### UsZipCode + Tests if the value is a valid US zip code. ### Uuid -Tests if the value is a valid uuid. + +Tests if the value is a valid `UUID`. #### Arguments -- `version` (optional) - the version to test the uuid for. Supported version are `3`, `4` and `5`. Defaults to test for `all` three if omitted. + +- `version` (optional) - the version to test the `UUID` for. Supported versions are `3`, `4` and `5`. Defaults to test for `all` three if omitted. ## Usage -The following is an example for the extra ip assert: + +The following is an example for the extra IP assert: ```js const Validator = require('validator.js').Validator; const is = require('validator.js').Assert.extend(require('validator.js-asserts')); const validator = new Validator(); -// Validate ip `1.3.3.7`. +// Validate IP `1.3.3.7`. let violation = validator.validate('1.3.3.7', is.ip()); if (true === violation) { console.log('"1.3.3.7" is a valid IP'); // => "1.3.3.7" is a valid IP } -// Validate ip `foo`. +// Validate IP `foo`. violation = validator.validate('foo', is.ip()); if (true !== violation) { @@ -293,7 +360,7 @@ if (true === violation) { ## Tests ```sh -$ npm test +npm test ``` ## Release process @@ -301,9 +368,25 @@ $ npm test The release of a version is automated via the [release](https://github.com/uphold/validator.js-asserts/actions/workflows/release.yaml) GitHub workflow. Run it by clicking the "Run workflow" button. ## License + MIT [npm-image]: https://img.shields.io/npm/v/validator.js-asserts.svg?style=flat-square [npm-url]: https://npmjs.org/package/validator.js-asserts -[travis-image]: https://img.shields.io/travis/uphold/validator.js-asserts.svg?style=flat-square -[travis-url]: https://travis-ci.org/uphold/validator.js-asserts +[ci-image]: https://github.com/uphold/validator.js-asserts/actions/workflows/ci.yaml/badge.svg?branch=master +[ci-url]: https://github.com/uphold/validator.js-asserts/actions/workflows/ci.yaml +[abavalidator-url]: https://www.npmjs.com/package/abavalidator +[bignumber-url]: https://www.npmjs.com/package/bignumber.js +[callback-url]: https://www.npmjs.com/package/callback +[cpf-url]: https://www.npmjs.com/package/cpf +[creditcard-url]: https://www.npmjs.com/package/creditcard +[curp-url]: https://www.npmjs.com/package/curp +[google-libphonenumber-url]: https://www.npmjs.com/package/google-libphonenumber +[iban-url]: https://www.npmjs.com/package/iban +[isoc-url]: https://www.npmjs.com/package/isoc +[moment-url]: https://www.npmjs.com/package/moment +[tin-validator-url]: https://www.npmjs.com/package/tin-validator +[uk-modulus-checking-url]: https://www.npmjs.com/package/uk-modulus-checking +[urijs-url]: https://www.npmjs.com/package/urijs +[validate-rfc-url]: https://www.npmjs.com/package/validate-rfc +[validator-url]: https://www.npmjs.com/package/validator