zan

Zan

Zan is a drop in replacement for React.PropTypes:

import { types } from 'zan';
React.createClass({
  propTypes: {
    name: types.string,
    age: types.number.isOptional
  },
  render() {/*...*/},
});

The primary differences between Zan and React.PropTypes are:

• Checks are isRequired by default and expose an isOptional property
• Provides an exactShape type checker
• Provides introspection methods
• Provides methods to help you create your own type checkers

API

zan.types

Exposes all the same type-checkers as React.PropTypes. Each type-checker is required by default and has the following properties:

• isOptional - Returns an optional type checker. Optional checkers behave like React.PropType's default behavior.

• inspectArgs() - Returns the arguments passed to the type-checker creator.

  Example: shape(o).inspectArgs() === o

• inspectType() - Returns the checker type.

  Example: shape(o).inspectType() === shape.

• inspectIsOptional() - Return whether or not the checker is optional

  Example: shape(o).inspectIsOptional() === false.

  Example: shape(o).isOptional.inspectIsOptional() === true.

zan.types.exactShape(shape)

Like shape(), but disallows unrecognized keys.

zan.check(type, value, [label])

Validates value against a type checker. Useful when using Zan outside of React components. Returns null if the data validates successfully or an Error object if there's an error:

Error: Invalid prop `value.field[0].subField` of type `object` supplied to `label`, expected an array.

Usage:

// Normal
const error = zan.check(type, value, 'label');
// Curried
const check = zan.check(type);
const error = check(value, 'label');

createCustomChecker(checkerFn)

Allows you to create your own type checker. Here's how you'd create a checker that validates that data is an instance of a RegExp:

const regex = zan.createCustomChecker((props, propName /*, ...*/) => {
  const value = props[propName];
  if (!(value instanceof RegExp)) {
    return new Error('Expected a regex but found "' + (typeof value) + '".');
  }
});
// regex gets all of Zan's built-in goodness:
regex.isOptional;
regex.inspectType() === regex;

The checker is passed all the same arguments as React PropType checkers: props, propName, componentName, location, and propFullName.

A Note on Error Formats

The final checker errors will be in one of two forms:

Required prop `field.subField[0].name` was not specified in `MyComponent`.
Invalid prop `field.subField[0].name` of (type `number` OR value `xyz`) supplied to `MyComponent`...

If you return an error that doesn't start with Required or Invalid then Zan prefixes the error message with:

Invalid prop `field.subField[0].name` of value `xyz` supplied to `MyComponent`:

createCustomCheckerCreator(checkerCreatorFn)

This is like createCustomChecker() but is for checkers that require arguments:

const range = zan.createCustomCheckerCreator((min, max) =>
  (props, propName/*, ...*/) => {
    const value = props[propName];
    if (value < min || value > max) {
      return new Error('Expected number in range `' + min + '` to `' + max + '`.');
    }
  }
);
// regex gets all of Zan's build-in goodness:
range(1, 3).isOptional;
range(1, 3).inspectType() === range;

recursive(types)

Converts native arrays and objects to arrayOf() and shape() calls, so you don't have to:

import { types, recursive } from 'zan';
const { number, string } = types;

const propTypes = recursive({
  myAge: number,
  myFavoriteNumbers: [number],
  treeNode: {
    value: number
  },
  buddies: [{
    name: string,
    age: number,
  }],
});

// ...is equivalent to:

const propTypes = {
  myAge: number,
  myFavoriteNumbers: arrayOf(number),
  treeNode: shape({
    value: number,
  }),
  buddies: arrayOf(shape({
    name: string,
    age: number,
  })),
};

see test.js from more usage