Home

Awesome

react-immutable-proptypes

npm package Code Climate Test Coverage

PropType validators that work with Immutable.js.

About

I got tired of seeing React.PropTypes.instanceOf(Immutable.List) or React.PropTypes.instanceOf(Immutable.Map) as PropTypes for components that should be specifying an Immutable.List of something or that an Immutable.Map contains some keys. A little "googling" came up empty, unless you want to use Flow, which I do not. So, I wrote react-immutable-proptypes.

Usage is simple, they work with and like any React.PropType.* validator.

var ImmutablePropTypes = require('react-immutable-proptypes');
var MyReactComponent = React.createClass({
    // ...
    propTypes: {
        myRequiredImmutableList: ImmutablePropTypes.listOf(
            ImmutablePropTypes.contains({
                someNumberProp: React.PropTypes.number.isRequired
            })
        ).isRequired
    }
    // ...
});

Since version 0.1.7 there are convenience helpers for "primitive" Immutable.js objects.

propTypes: {
    oldListTypeChecker: React.PropTypes.instanceOf(Immutable.List),
    anotherWay: ImmutablePropTypes.list,
    requiredList: ImmutablePropTypes.list.isRequired,
    mapsToo: ImmutablePropTypes.map,
    evenIterable: ImmutablePropTypes.iterable
}

Installation

Installing via npmjs

npm install --save react-immutable-proptypes

API

React-Immutable-PropTypes has:

ImmutablePropTypes.list         // Immutable.List.isList
ImmutablePropTypes.map          // Immutable.Map.isMap
ImmutablePropTypes.orderedMap   // Immutable.OrderedMap.isOrderedMap
ImmutablePropTypes.set          // Immutable.Set.isSet
ImmutablePropTypes.orderedSet   // Immutable.OrderedSet.isOrderedSet
ImmutablePropTypes.stack        // Immutable.Stack.isStack
ImmutablePropTypes.seq          // Immutable.Seq.isSeq
ImmutablePropTypes.iterable     // Immutable.Iterable.isIterable
ImmutablePropTypes.record       // instanceof Record
ImmutablePropTypes.contains     // Immutable.Iterable.isIterable - contains(shape)
ImmutablePropTypes.mapContains  // Immutable.Map.isMap - contains(shape)
// ...
aMap: ImmutablePropTypes.contains({
    aList: ImmutablePropTypes.contains({
        0: React.PropTypes.number,
        1: React.PropTypes.string,
        2: React.PropTypes.number.isRequired,
    }).isRequired,
})
// ...
<SomeComponent aList={Immutable.fromJS({aList: [1, 'two', 3]})} />
// ...
aMap: ImmutablePropTypes.mapOf(
    React.PropTypes.any, // validation for values
    ImmutablePropTypes.mapContains({ // validation for keys
        a: React.PropTypes.number.isRequired,
        b: React.PropTypes.string
    })
)
// ...
const aMap = Immutable.Map([
    [Immutable.Map({a: 1, b: '2'}), 'foo'],
    [Immutable.Map({a: 3}), [1, '2', 3]]
]);
<SomeComponent aMap={aMap} />
// ...
aRecord: ImmutablePropTypes.recordOf({
    keyA: React.PropTypes.string,
    keyB: ImmutablePropTypes.list.isRequired
})
// ...
// ...
aMap: ImmutablePropTypes.mapContains({
    aList: ImmutablePropTypes.list.isRequired,
})
// ...
<SomeComponent aList={Immutable.fromJS({aList: [1, 2]})} />

These two validators cover the output of Immutable.fromJS on standard JSON data sources.

RFC

Please send a message or, better yet, create an issue/pull request if you know a better solution, find bugs, or want a feature. For example, should listOf work with Immutable.Seq or Immutable.Range. I can think of reasons it should, but it is not a use case I have at the present, so I'm less than inclined to implement it. Alternatively, we could add a validator for sequences and/or ranges.