Skip to content

API.md

Latest commit

 

History

History
737 lines (485 loc) · 21.9 KB

API.md

File metadata and controls

737 lines (485 loc) · 21.9 KB

Reform API docs

Autogenerated from source code

index Module src

Reform Object literal src

default export for the entire library.

// using the default export
import Reform from '@franleplant/reform'

// importing only the needed parts
import { reactMixins } from '@franleplant/reform'

{
  core: ./src/core
  reactHelpers: ./src/reactHelpers
  reactMixins: ./src/reactMixins
  types: ./src/types
  validators: ./src/validators
}

core Module src

fieldIsValid Function src

Evaluate whether a field is valid or not.

This function is a lightweight wrapper of validateField. It has two variants, as listed below. The first one is not so different from validateField, the only difference is that it will return whether that field is valid (all values in FieldErrors are false) or is invalid (at least one value in FieldErrors is true).

The second variant accepts an already calculated FieldErrors and just check if all values are false (valid field) or some are true (invalid field). This is useful if you already calculated FieldErrors in another event. In this way you can avoid re calculating them again each time you want to know if the field is valid.

fieldIsValid(value: string | number, rules: Rules): boolean


fieldIsValid(fieldErrors: FieldErrors): boolean

formIsValid Function src

Analogous to fieldIsValid but operating for forms. There are also two variants, the first one accepts values and rules and calculates the formErrors and then check that all fields are valid, and the second one accepts an already calculated formErrors.

formIsValid(fieldsValues: Fields, rulesMap: RulesMap): boolean


formIsValid(formErrors: FormErrors): boolean

validateField Function src

Validate value against rules and return which rules are valid with a value false and which rules ar invalid with a value of true.

One of the central functions in Reform.core. Accepts inline, ad-hoc, validators as well as available ones (required, pattern, etc).

Example

// a required empty value should be invalid.
const fieldErrors = validateField('', {required: true});
assert(fieldErrors, {required: true});

// an invalid email value
const fieldErrors = validateField('not an email', {email: true});
assert(fieldErrors, {email: true});
// a valid email value
const fieldErrors = validateField('email@domain.com', {email: true});
assert(fieldErrors, {email: false});

// And of course you can combine them
const fieldErrors = validateField('email@domain.com', {required: true, email: true});
assert(fieldErrors, {required: false, email: false});

The most important part is that the result of this function, which is of the type FieldErrors will be an object that has rule names as keys with boolean values. If the value is true it means that there is an error, otherwise, it does not have an error, and that rule is passing.

validateField(value: string | number, rules: Rules): FieldErrors

validateForm Function src

A simple generalization of validateField but for an entire form. It will basically run validateField on each value and each rules indexed by fieldName and return FormErrors which is, an object that has fieldNames as keys and FieldErrors as values.

validateForm(fieldsValues: Fields, rulesMap: RulesMap): FormErrors

reactHelpers Module src

fieldErrors Function src

Another error helper to make displaying field errors easier. Instead of fieldIfError which is more procedural, use this helper if you have an structured way of displaying your errors.

It returns an Array of Failed Rules. Each Failed Rule will be, in turn, an array of the form ['ruleName', 'ruleArgument'].

Where ruleName will be the name of a failed rule, for example required, minLenght, etc. And ruleArgumentwill be the value of the rule, as defined by the user. For exampletrue`, '6', etc, respectively.

This will enable you to create functions, or components, that will render your errors automatically for you.

Check mapFieldErrors for an even more easier way.

const errors = this.fieldErrors('myField')
assert(errors, [['required', true], ['minLenght', 6], ['pattern', 'banana|apple'])

Tags

  • unstable

fieldErrors(fieldName: string): Array<[string, any]>

fieldIfError Function src

Simple helper to make conditional displaying field errors more ergonomic.

Use it if to render field errors only if that field has a particular failed rule.

{ this.fieldIfError('myField', 'required') && <span> myField is required! </span>

This function is purely for ergonomic purposes.

fieldIfError(fieldName: string, errorKey: string): boolean

fieldIsValid Function src

Calculate whether a field is valid or not depending on the already calculated fieldErrors stored in the state.

Use it to render invalid state in your inputs.

Important this function will not re calculate your field's validity

fieldIsValid(fieldName: string): boolean

formIsValid Function src

Calculate the form's validity from the values in this.state.fields and the rules in this.validationRules.

This function, in contrast to fieldIsValid, will effectively re-calculate your form's validity

Use it to disable the submit button, or to prevent onSubmit callback from normal processing of the form.

formIsValid(): boolean

mapFieldErrors Function src

An abstraction of fieldErrors for structured field error rendering. Use it if you have a very standard way of displaying field errors.

This function will use the MessageCreator map defined in this.validationMessages. It will map over the failed rules of a given field and create messages for you to display how ever you want.

//Define your validationMessages
this.validationMessages = {
  // Define a per-rule message creator
  minLenght: (ruleValue, ruleKey, fieldName) => `${fieldName} must have at least ${ruleValue} characters`
  // Define a fall back for missing message creators
  default: (ruleValue, ruleKey, fieldName) => `{fieldName} is invalid according to rule ${ruleKey}: ${ruleValue}`
}

// Example validationRules
this.validationRules = {
  myField: {minLength: 6}
}

// Use inside your render function
{this.mapFieldErrors('myField')
   .map(message => (
     <span>{message}</span>
   ))
}

//In our example it will render something like this
<span>myField must have at least 6 characters</span>

Tags

  • unstable

mapFieldErrors(fieldName: string): Array<string>

validateField Function src

Calculate the validity of a field, by fieldName, with a new value and store it in the this.state.errors[fieldName]

Will return, to improve usability, whether that field is valid or not.

Use it if you are validating onChange, because this.state.fields[fieldName] (field's value) wont be already set.

Important: This function needs to be executed in the context of a ValidationAbleInstance and will not save the value of the field in the state, that's your job.

You can either use Reform.reactMixins to automatically bind this function to your instance (this inside your Component) and use them as regular methods, or you can use bind, apply and call to run them as functions.

// Create a new bounded function (very similar to what `reactMixins` do)
const boundedFunction = Reform.reactHelpers.validateField.bind(this)

// Run it in the proper context
const isValid = Reform.reactHelpers.validateField.call(this, 'myField', 'new value');

Ultimately, the way you use it does not matter as long as it fits your style. However, if you are undecided, I suggest you start by using React.reactMixins

Important this function will modify your component state

This function will also set your form to dirty in this.state.formIsDirty

validateField(fieldName: string, value: any): boolean

validateFieldFromState Function src

A minimal variant of validateField but with the particularity of using the value already set in your component's state.

Use it if you are validating after updating your state, i.e.: onBlur, onSubmit et al,

Important this function will modify your component's state

This function will also set your form to dirty in this.state.formIsDirty

validateFieldFromState(fieldName: string): boolean

validateForm Function src

Calculate the validity of your form from fieldsValues as parameters, update your state, and return whether your form is valid or not.

Unless you have a very specific use case, most of the time you should be using validateFormFromState.

Important this function will modify your component's state

This function will also set your form to dirty in this.state.formIsDirty

validateForm(fieldsValues: Fields): boolean

validateFormFromState Function src

Calculate the validity of your form from fieldsValues as parameters, update your state, and return whether your form is valid or not.

Use it onSubmit.

Important this function will modify your component's state

This function will also set your form to dirty in this.state.formIsDirty

validateFormFromState(): boolean

reactMixins Module src

IReform Interface src

Handy interface that contains attributes corresponding to each Reform.reactHelpers.* method.

{
  fieldErrors: fieldErrors
  fieldIfError: fieldIfError
  fieldIsValid: fieldIsValid
  formIsValid: formIsValid
  mapFieldErrors: mapFieldErrors
  validateField: validateField
  validateFieldFromState: validateFieldFromState
  validateForm: validateForm
  validateFormFromState: validateFormFromState
}

functionalMixin Function src

Functional mixin to incorporate all reactHelpers methods into your Component's instance.

Use it in Javascript without the need of decorators.

Example

class MyComponent extends React.Component {
 constructor(...args) {
   super(...args)

   functionalMixin(this);

   // Now all reactHelpers will be available through this.[reactHelper]
   this.validateForm
   this.fieldIsValid
   // etc
 }
}

functionalMixin(instance: any): void

objectMixin Function src

Simplest mixin (well not really a mixin) that binds all reform helpers to your context and returns an object containing all common helerps.

Use it with typescript to get type checks and autocomplete.

 class MyForm extends React.Component<any, any> {
   reform = objectMixin(this)
 }

objectMixin(that: ValidationAbleInstance): IReform

validators Module src

validatorInterface Object literal src

Main validator interface.

It is simply a wrapper on top of an object that contains all the single functions that each officialValidators/** module exports.

The main reasons for this abstraction to exist are:

  • Throw errors when a wrong validation rule key is passed (i.e. in this.validationRules)
  • Allow the user to set new global available custom validators
  • Throw errors when the user is trying to overwrite an already existing validator

Use it if you want to add new global custom validators.

{
  get: get(key: string): Validator
  set: set(key: string, value: Validator): void
}

types Module src

FieldErrors Interface src 

{
  [ruleKey: string]: boolean
}

Fields Interface src 

{
  [fieldName: string]: any
}

FormErrors Interface src 

{
  [fieldName: string]: FieldErrors
}

Rules Interface src 

{
  [ruleKey: string]: boolean | string | Validator | any
}

RulesMap Interface src 

{
  [fieldName: string]: Rules
}

ValidationAbleInstance Interface src 

{
  setState: any
  state:
  {
    errors: FormErrors
    fields: Fields
    formIsDirty: boolean
  }
  validationMessages:
  {
    [ruleKey: string]: MessageCreator
  }
  validationRules: RulesMap
}

Validator Interface src 

{
  (value: string | number | any, ruleValue: any): boolean
}

ValidatorMap Interface src 

{
  [ruleKey: string]: Validator
}

MessageCreator Type alias src 

{
  (ruleArgument: any, ruleKey: string, fieldName: string): string
}

officialValidators/index Module src

validatorMap Object literal src

These are all the official validators HTML5 validators.

They are slightly differently expressed.

Example 1

//HTML5
<input name="myEmail" type="email" min-length=5 required />

// Reform
this.validationRules = {
 myEmail: {
   email: true,
   minLength: 5,
   required: true
 }
}

Example 2

//HTML5
<input name="myField" type="number" min=5  max=15 />

// Reform
this.validationRules = {
 myField: {
   number: true,
   minNumber: 5,
   maxNumber: 15,
 }
}

{
  maxDate: maxDate
  maxMonth: maxMonth
  maxNumber: maxNumber
  maxTime: maxTime
  maxWeek: maxWeek
  minDate: minDate
  minMonth: minMonth
  minNumber: minNumber
  minTime: minTime
  minWeek: minWeek
  month: month
  number: Validator
  range: Validator
  time: time
  url: url
  week: week
  color: color(value: any): boolean
  date: date(value: any): boolean
  email: email(value: string): boolean
  maxLength: maxLength(value: string, maxLength: number): boolean
  minLength: minLength(value: string, minLength: number): boolean
  pattern: pattern(value: string, re: RegExp): boolean
  required: required(value: any): boolean
}

officialValidators/minMonth Module src

minMonth Function src 

minMonth(value: string, min: string): boolean

officialValidators/minNumber Module src

minNumber Function src 

minNumber(value: number | string, min: number | string): boolean

officialValidators/maxMonth Module src

maxMonth Function src 

maxMonth(value: string, max: string): boolean

officialValidators/minWeek Module src

minWeek Function src 

minWeek(value: string, min: string): boolean

officialValidators/minDate Module src

minDate Function src 

minDate(value: string, min: string): boolean

officialValidators/time Module src

time Function src 

time(value: string): boolean

officialValidators/url Module src

url Function src 

url(value: string): boolean

officialValidators/week Module src

week Function src 

week(value: string): boolean

officialValidators/maxDate Module src

maxDate Function src 

maxDate(value: string, max: string): boolean

officialValidators/maxWeek Module src

maxWeek Function src 

maxWeek(value: string, max: string): boolean

officialValidators/maxNumber Module src

maxNumber Function src 

maxNumber(value: number | string, max: number | string): boolean

officialValidators/maxTime Module src

maxTime Function src 

maxTime(value: string, max: string): boolean

officialValidators/minTime Module src

minTime Function src 

minTime(value: string, min: string): boolean

officialValidators/month Module src

month Function src 

month(value: string): boolean

utils Module src

parseMonth Function src 

parseMonth(value: string): Array<number>

parseTime Function src 

parseTime(time: string): number

parseWeek Function src 

parseWeek(value: string): Array<number>

weeksInYear Function src 

weeksInYear(year: number): number