https://github.com/aycangulez/fn-arg-validator
A lightweight JavaScript library to validate function arguments.
https://github.com/aycangulez/fn-arg-validator
defensive-programming validation validation-library
Last synced: about 2 months ago
JSON representation
A lightweight JavaScript library to validate function arguments.
- Host: GitHub
- URL: https://github.com/aycangulez/fn-arg-validator
- Owner: aycangulez
- License: mit
- Created: 2023-11-24T18:59:47.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-04-02T11:19:20.000Z (about 2 years ago)
- Last Synced: 2024-07-31T09:46:16.078Z (over 1 year ago)
- Topics: defensive-programming, validation, validation-library
- Language: JavaScript
- Homepage:
- Size: 58.6 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
fn-arg-validator is a lightweight JavaScript library for validating function arguments.
## Installation
### Node.js
```bash
npm install --save fn-arg-validator
```
### Browsers
Install as above and use the `fn-arg-validator.js` file found in the node_modules directory. You will also need to include lodash if you aren't already using it in your application.
```html
```
## Usage
First, a quick example:
```js
const is = require('fn-arg-validator');
function createUser(firstName, lastName, birthDate) {
is.valid(is.string, is.string, is.date, arguments);
// ...
}
createUser('Thomas', 'Anderson', '1971-09-13');
// [WARN] 1971-09-13 failed date check
}
```
**is.valid()** uses a functional style interface where you pass type check functions (built-in or your own) for each function argument, and as the final argument, you simply pass the *arguments* object to avoid writing the function parameters again.
The *arguments* object isn't available for arrow functions, so you need to type the parameter names in an array like *[firstName, lastName, birthDate]* for those.
The above code will normally log a warning and continue to run, but you may choose to check the return value of **is.valid** to stop the execution of the rest of the code. The decision depends on how you want to handle type errors. Sometimes, a warning is enough, and sometimes you need to be strict and throw an error.
### Boundary Checks and Maybe Types
In addition to strict type checks, it's possible to do things like string length checks, and use maybe types that also accept undefined/null values:
```js
function createUser(firstName, lastName, birthDate) {
is.valid(is.stringBetween(1, 20), is.stringLTE(20), is.maybeDate, arguments);
// ...
}
```
### Object Property and Type Checks
**is.objectWithProps** can be used to check if an object has the specified properties and those properties have the correct types.
```js
const userObjectProps = { id: is.number, firstName: is.string, lastName: is.string, birthDate: is.date };
function updateUser(user) {
if (!is.valid(is.objectWithProps(userObjectProps), arguments)) {
throw new Error('Invalid user object');
}
// ...
}
updateUser({ id: 1, firstName: 'Thomas', lastName: 'Anderson', birthDate: '1971-09-13' });
/*
[WARN] {"id":1,"firstName":"Thomas","lastName":"Anderson","birthDate":"1971-09-13"} failed objectWithProps check
Error: Invalid user object
...
*/
```
**Note:** You can have one-level of nested object property checks as shown below:
```js
is.valid(
is.objectWithProps({
a: is.number,
b: is.objectWithProps({ c: is.string, d: is.number }),
}),
arguments
);
```
## Built-in Type Check Functions
### Strict Type Checks
* **is.array:** Returns true if the argument is an array.
* **is.boolean:** Returns true if the argument is a boolean.
* **is.buffer:** Returns true if the argument is a buffer.
* **is.date:** Returns true if the argument is a Date object.
* **is.func:** Returns true if the argument is a function.
* **is.number:** Returns true if the argument is a number.
* **is.object:** Returns true if the argument is an object.
* **is.string:** Returns true if the argument is a string.
### Maybes
* **is.maybeArray:** Returns true if the argument is an array or undefined/null.
* **is.maybeBoolean:** Returns true if the argument is a boolean or undefined/null.
* **is.maybeBuffer:** Returns true if the argument is a buffer or undefined/null.
* **is.maybeDate:** Returns true if the argument is a Date object or undefined/null.
* **is.maybeFunc:** Returns true if the argument is a function or undefined/null.
* **is.maybeNumber:** Returns true if the argument is a number or undefined/null.
* **is.maybeObject:** Returns true if the argument is an object or undefined/null.
* **is.maybeString:** Returns true if the argument is string or undefined/null.
### Boundary Checks
* **is.numberGT(n):** Returns true if the argument is a number and greater than *n*.
* **is.numberGTE(n):** Returns true if the argument is a number and greater than or equal to *n*.
* **is.numberLT(n):** Returns true if the argument is a number and less than *n*.
* **is.numberLTE(n):** Returns true if the argument is a number and less than or equal to *n*.
* **is.numberBetween(n1, n2):** Returns true if the argument is a number and between *n1* and *n2* (inclusive).
* **is.stringGT(n):** Returns true if the argument is a string and its length is greater than *n*.
* **is.stringGTE(n):** Returns true if the argument is a string and its length is greater than or equal to *n*.
* **is.stringLT(n):** Returns true if the argument is a string and its length is less than *n*.
* **is.stringLTE(n):** Returns true if the argument is a string and its length is less than or equal to *n*.
* **is.stringBetween(n1, n2):** Returns true if the argument is a string and its length is between *n1* and *n2* (inclusive).
### Mixed Types
* **is.oneOf** returns true if an argument's type is one of the passed types. For example, **is.oneOf(is.number, is.array)** returns true for *1* and *[1]*, but not *'1'*.
### Object Property and Type Checks
* **is.objectWithProps(props):** Returns true if the argument is an object and the property-type pairs match the argument's properties and their types.
### Catch-all
* **is.any:** Returns true for everything. Great for skipping validation for certain arguments.
## Passing your Own Type Check Functions
The beauty of a functional style interface is that you aren’t limited to the built-in validation functions, you can simply pass your own. The only requirement is to give your functions names since is.valid uses function names for logging purposes.
## Throwing Exceptions
fn-arg-validator can be configured to throw exceptions on failed checks when **is.config.throw** is set to *true*.
## Log Configuration
By default, fn-arg-validator uses the *console* object for logging. However, this can be configured by assigning a different logger to **is.config.log**.
The log level can be set by changing the value of **is.config.logLevel**. The default log level is *'WARN'*, which only logs failed checks. If you would like to see successful validations, you need to set the log level to *'DEBUG'* or higher. To disable all logging, set the log level to *'OFF'*.