Awesome
react-immutable-proptypes
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:
- Primitive Types
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)
ImmutablePropTypes.contains
(formerlyshape
) is based onReact.PropTypes.shape
and will try to work with anyImmutable.Iterable
. In my usage it is the most used validator, as I'm often trying to validate that a map has certain properties with certain values.
// ...
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]})} />
-
ImmutablePropTypes.listOf
is based onReact.PropTypes.array
and is specific toImmutable.List
. -
ImmutablePropTypes.mapOf
allows you to control both map values and keys (in Immutable.Map, keys could be anything including another Immutable collections). It accepts two arguments - first one for values, second one for keys (optional). If you are interested in validation of keys only, just passReact.PropTypes.any
as the first argument.
// ...
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} />
-
ImmutablePropTypes.orderedMapOf
is basically the same asmapOf
, but it is specific toImmutable.OrderedMap
. -
ImmutablePropTypes.orderedSetOf
is basically the same aslistOf
, but it is specific toImmutable.OrderedSet
. -
ImmutablePropTypes.stackOf
is basically the same aslistOf
, but it is specific toImmutable.Stack
. -
ImmutablePropTypes.iterableOf
is the generic form of listOf/mapOf. It is useful when there is no need to validate anything other than Immutable.js compatible (ie.Immutable.Iterable
). Continue to uselistOf
and/ormapOf
when you know the type. -
ImmutablePropTypes.recordOf
is likecontains
, except it operates on Record properties.
// ...
aRecord: ImmutablePropTypes.recordOf({
keyA: React.PropTypes.string,
keyB: ImmutablePropTypes.list.isRequired
})
// ...
ImmutablePropTypes.mapContains
is based onReact.PropTypes.shape
and will only work withImmutable.Map
.
// ...
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.