regbin
Form validation function generator: regularized bindings for form fields against which to test data. Built-in support for 32 default fields (so far!), async and custom validators, and Redux-Form.
Installation
npm install regbin
- Node:
const regbin = require('regbin')
- ES6+ client:
import regbin from 'regbin'
Usage
- Basic
- With React
- With React-Redux
- With Redux-Form (can be within the context of React-Redux)
Basic (you can do this in Node)
- Optionally specify configs:
;
- Specify fields:
;
- Feed in data:
;
- Catch informative messages for failing fields:
regbin;
With React (no Redux, just local state)
- Outside the form component, specify configs and fields:
const validations = city: 'required' state: zipcode: 'required' ;
- Init form component state from its constructor:
thisstate = errors: {}
- Add form component methods:
// Here event.target.value is a string... { event; ; } // ...and here event.target.value is an object of all fields and values. { event; ; }
- And now for a given form field, you can specify the onChange prop accordingly; same for onSubmit for the whole form.
With React-Redux (regbin via thunk creators)
- Same first step, specify configs and fields:
const validations = city: 'required' state: zipcode: 'required' ;
- Specify onChange and onSubmit
mapDispatch
functions for form components:
const mapDispatch = { return { event; ; } { event; ; } ;};
- Put form state onto Redux store state: specify initial state as well as action creators for changes and their corresponding reducers. Same boilerplate you'd want for any other slice of state. Note in example below, the two action creators are called "updateForm" (to update a single field's error state) and "resetForm" (to update the whole form's error state at once).
- Add onChange and onSubmit thunk creators (note you'll need the
validations
regbin in scope):
{ ; } // ...and here event.target.value is an object of all fields and values. { event; ; }
With Redux-Form
Redux-Form lets you make forms into their own kind of connected component. Instead of the connect
connector, you use the reduxForm
connector.
In providing the 'redux-form' config option, the regbin library aims to make using redux-form a smooth transition from using react-redux. Instead of having to write the extra functionality redux-form requires yourself, let regbin compose it for you!
- Same as always, specify configs and fields. Only this time, pass along the 'redux-form' config as well:
city: 'required' state: zipcode: 'required' ;
- Now, into the
reduxForm
connect function, literally all you have to do is use the spread operator on the regbin object, as follows:
form: 'exampleForm' // a unique identifier for this form ...regbinExampleFormComponent;
Functionality
Currently supported validators
While a regbin is essentially a validations wrapper, the regbin library supports the following forms of validations out of the box:
Address:
Validator Name | Failure Assertion (to be composed, along with other failing assertions for the same field, into an intelligible message) |
---|---|
street (street name) |
address must include a number and a name |
city |
must be an actual city, comprised of a word or words |
state |
must be a US state |
country |
must be an actual country |
countryCode |
must be an actual country code (see: https://developers.google.com/public-data/docs/canonical/countries_csv) |
zipcode |
must be an actual postal code |
Date:
Validator Name | Failure Assertion |
---|---|
year |
must be exactly four (4) digits long |
month |
must be between 1 and 12 |
day |
must be between 1 and 31 (except if it's February, April, June, September, or November!) |
Email:
Validator Name | Failure Assertion |
---|---|
email |
must be a valid email address |
Emoji:
Validator Name | Failure Assertion |
---|---|
emoji |
must be shortcode for an actual emoji (see: https://www.emojibase.com/) |
Name:
Validator Name | Failure Assertion |
---|---|
firstName |
must be comprised of a word or words |
lastName |
must be comprised of a word or words |
fullName or name |
must be comprised of a word or words |
username |
must be a single word of letters and/or numbers |
Phone:
Validator Name | Failure Assertion |
---|---|
phone |
must be a valid 10-digit phone number |
Math:
Validator Name | Failure Assertion |
---|---|
. |
must be a decimal amount |
{ '%': n } |
must be divisible by n |
{ range: [min, max] } |
must be between min and max characters long |
Money:
Validator Name | Failure Assertion |
---|---|
$ |
must be a valid currency amount |
Time:
Validator Name | Failure Assertion |
---|---|
{ before: [value, lub] } |
must occur before lub |
{ after: [value, glb] } |
must occur after glb |
Work:
Validator Name | Failure Assertion |
---|---|
occupation |
must be comprised of a word or words |
Additionally, the following "lower-level" validations are also supported:
Validator Name | Failure Assertion (to be composed, along with other failing assertions for the same field, into an intelligible message) |
---|---|
ascii |
must be made up of ASCII characters only |
base64 |
must be made up of Base-64 characters only |
a-z |
must be a single word of letters only |
0-9 |
must be a single figure made of numbers only |
alphaNum |
must be a single word of letters and/or numbers |
words |
must be comprised of letters only |
title |
must be comprised of a word or words |
nonEmpty (i.e., ok to just put blank spaces, but you need to put something) |
must not be left an empty field |
required |
must not be blank |
Combining validator messages
regbin "intelligently" combines messages for the same field, so that if, for instance, the email field were required, the corresponding error message would read, "Email must be a valid address, and must not be blank."
Object validators
Yes, you can pass in an object as a validator! E.g.,
username: 'required' range: 4 12 ;
Custom validators
You can, of course, supply your own validators instead of or in addition to regbin defaults.
- First define your custom validator:
const customValidator = /.*.*/i;
- You'll also want a corresponding "failure assertion," to be composed into a form validation error message for users:
const customMessage = 'must include a walrus or a carpenter';
- Now, just add to the fields object...
const fields = firstName: 'required' lastName: 'required' occupation: 'required' customValidator customMessage ;
- ...and feed that into a regbin:
;
Significantly, the above allows you to bring in your own favorite validations library and still use regbin to do the coordinating between the validations you want to use and the application you want to use them in.
Custom messages
Even without a custom validator, you can still customize a validation message in much the same way: make an array with two values, the first of which is the validation you want to use, specified as a string, and the second of which is your custom message:
;
As the example above demonstrates, validation messages can be specified as either strings or functions. (Will be significant as support is added for variables in messages.)
defaults
config option
Using the If you specify to regbin you want to use "defaults", regbin will attempt to utilize the default validator function and message for a given field name in addition to the validators you explicitly specify for that field. E.g.,
firstName: 'required' email: ;
is equivalent to
;
FAQ
What config options are currently available?
Now available:
defaults
: regbin will attempt to use default validators associated with fields you've specified. I.e., if you want to validate an email address using defaults, regbin will default to checking if the email address is valid, and send the default message, "Email should be a valid address" if it isn't.redux-form
: enabling simple integration with the redux-form library (see example above).
Is regbin really async by default?
Yes. That said, the plan is to make explicitly synchronous-only validations an additional config option.
Why is regbin async by default?
Sometimes in order to answer one question you'll ask something else. Main use case is database queries. "Is this username taken?" An app generally has to ping a database in order to answer the prior question of whether or not the username exists in the database.
You can query basically any API you please, or even scrape the web, to get an answer you're looking for. All you need to supply to regbin is a function that will take some data (among whatever other params you please) and eventually return an answer about whether or not that data is valid. As a demo of this capability/proof of concept for the possibly more-relevant-if-less-fanciful database-pinging case, regbin supports country
, countryCode
, and emoji
async validators currently powered by web scraping.
What's that style called when you just get a single function from a library and keep calling it with different inputs?
Dependencies
node-fetch
(for built-in async validators)validator
(for additional built-in validators)