react-immutable-proptypes

What is react-immutable-proptypes?

The react-immutable-proptypes package provides PropTypes validators that are specifically designed to work with Immutable.js data structures. This allows developers to enforce the types of Immutable.js collections in their React components, ensuring that the data passed through props adheres to the expected structure.

What are react-immutable-proptypes's main functionalities?

List

This feature allows you to validate that a prop is an Immutable.js List. The code sample demonstrates a React component that expects a prop named `myList` to be an Immutable List.

import React from 'react';
import PropTypes from 'prop-types';
import ImmutablePropTypes from 'react-immutable-proptypes';
import { List } from 'immutable';

const MyComponent = ({ myList }) => (
  <div>{myList.join(', ')}</div>
);

MyComponent.propTypes = {
  myList: ImmutablePropTypes.list
};

export default MyComponent;

Map

This feature allows you to validate that a prop is an Immutable.js Map. The code sample demonstrates a React component that expects a prop named `myMap` to be an Immutable Map.

import React from 'react';
import PropTypes from 'prop-types';
import ImmutablePropTypes from 'react-immutable-proptypes';
import { Map } from 'immutable';

const MyComponent = ({ myMap }) => (
  <div>{myMap.get('key')}</div>
);

MyComponent.propTypes = {
  myMap: ImmutablePropTypes.map
};

export default MyComponent;

OrderedMap

This feature allows you to validate that a prop is an Immutable.js OrderedMap. The code sample demonstrates a React component that expects a prop named `myOrderedMap` to be an Immutable OrderedMap.

import React from 'react';
import PropTypes from 'prop-types';
import ImmutablePropTypes from 'react-immutable-proptypes';
import { OrderedMap } from 'immutable';

const MyComponent = ({ myOrderedMap }) => (
  <div>{myOrderedMap.get('key')}</div>
);

MyComponent.propTypes = {
  myOrderedMap: ImmutablePropTypes.orderedMap
};

export default MyComponent;

Set

This feature allows you to validate that a prop is an Immutable.js Set. The code sample demonstrates a React component that expects a prop named `mySet` to be an Immutable Set.

import React from 'react';
import PropTypes from 'prop-types';
import ImmutablePropTypes from 'react-immutable-proptypes';
import { Set } from 'immutable';

const MyComponent = ({ mySet }) => (
  <div>{Array.from(mySet).join(', ')}</div>
);

MyComponent.propTypes = {
  mySet: ImmutablePropTypes.set
};

export default MyComponent;

Other packages similar to react-immutable-proptypes

prop-types

The prop-types package is the standard library for type-checking props in React components. While it does not provide specific validators for Immutable.js data structures, it is widely used for general prop type validation in React applications.

immutable-prop-types

The immutable-prop-types package provides PropTypes validators for Immutable.js data structures, similar to react-immutable-proptypes. It offers a similar set of validators for Immutable.js collections, making it a direct alternative.

README

react-immutable-proptypes

PropType validators that work with Immutable.js.

Version Updates

0.1.3 updated package.json to support React v0.11.0+ (including 0.13.1). Thanks Andrey Okonetchnikov!

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 an Immutable.Map shape. 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.shape({
        someNumberProp: React.PropTypes.number.isRequired
      })
    ).isRequired
  }
  // ...
});

Installation

Installing via npmjs

npm install --save react-immutable-proptypes

API

React-Immutable-PropTypes has just two validators that cover 100% of my use cases, and probably 99% of everybody's use cases.

• ImmutablePropTypes.listOf is based on React.PropTypes.array and is specific to Immutable.List.

• ImmutablePropTypes.mapOf is basically the same as listOf, but it is specific to Immutable.Map. I am open to creating an ImmutablePropTypes.iterableOf that would validate against any Immutable.Iterable if anybody wants it.

• ImmutablePropTypes.shape is based on React.PropTypes.shape and will try to work with any Immutable.Iterable. In practice, I would recommend limiting this to Immutable.Map or Immutable.OrderedMap. However, it is possible to abuse shape to validate an array via Immutable.List.

    // ...
    aList: ImmutablePropTypes.shape({
      0: React.PropTypes.number.isRequired,
      1: React.PropTypes.string.isRequired,
      2: React.PropTypes.string
    })
    // ...
    <SomeComponent aList={new Immutable.List([1, '2'])} />
  

  That said, don't do this. Please, just... don't.

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.