react-immutable-proptypes

React-immutable-proptypes fills a specific gap left by React’s built-in PropTypes: validating the shape of Immutable.js collections passed as props, not just their constructor. Without it, a component can only declare PropTypes.instanceOf(Immutable.List), which says nothing about what the list actually contains. This library adds listOf, mapOf, contains, mapContains, recordOf, and similar validators so a prop like aList: ImmutablePropTypes.listOf(ImmutablePropTypes.contains({ id: PropTypes.number.isRequired })) is checked at the field level, the same way PropTypes.arrayOf/PropTypes.shape work for plain JS arrays and objects.

It ships primitive-type checkers for every core Immutable.js structure (List, Map, OrderedMap, Set, OrderedSet, Stack, Seq, Record, Iterable) plus composite checkers (listOf, mapOf, orderedMapOf, setOf, orderedSetOf, stackOf, iterableOf, recordOf) and shape checkers (contains/shape, mapContains, orderedMapContains) that mirror React.PropTypes.shape but walk any Immutable.Iterable. It is a small, dependency-light utility (only invariant plus a peer dependency on immutable) that teams adopted heavily during the Immutable.js + Redux era of React development, and it remains a common dependency in codebases that have not yet migrated off Immutable.js.

What You Get

• Primitive-type checkers (list, map, orderedMap, set, orderedSet, stack, seq, record, iterable) that validate a prop is the correct Immutable.js collection type
• Composite checkers (listOf, mapOf, orderedMapOf, setOf, orderedSetOf, stackOf, iterableOf, recordOf) modeled on PropTypes.arrayOf for validating collection contents
• Shape checkers (contains/shape, mapContains, orderedMapContains) modeled on PropTypes.shape for validating that a Map/Record contains specific required keys with specific types
• mapOf support for validating both values and keys independently, since Immutable.Map keys can themselves be arbitrary values or collections
• TypeScript typings (typings/index.d.ts) shipped alongside the runtime validators
• A production build that strips all validation logic (matching React’s own PropTypes behavior) so there’s no runtime cost in production bundles

Common Use Cases

• Validating that a component’s data prop is an Immutable.List of records containing specific required fields, catching malformed Redux state shape during development
• Enforcing that a Immutable.Map prop passed down through several component layers still contains the keys a leaf component expects
• Migrating a legacy Redux + Immutable.js codebase where components previously used a bare instanceOf(Immutable.List) check and need finer-grained validation without a full data-layer rewrite
• Validating nested immutable structures produced by Immutable.fromJS() from API responses, ensuring the shape survives however deep the nesting goes
• Adding required-field validation to Immutable.Record instances passed as props, similar to how PropTypes.shape works for plain objects

Under The Hood

Architecture The entire library lives in one 293-line file, src/ImmutablePropTypes.js, built around a factory-function pattern lifted directly from React’s own internal ReactPropTypes.js: each checker is produced by a createXTypeChecker-style factory returning a validator with React’s standard (props, propName, componentName, location, propFullName) => Error|null signature, with .isRequired attached afterward. Two parallel export objects are assembled depending on process.env.NODE_ENV — the development branch wires up the real checker factories against Immutable.js’s own type guards (Immutable.List.isList, Immutable.Map.isMap, etc.), while the production branch swaps every checker for a shared no-op invariant-throwing stub, exactly mirroring how React strips PropTypes checks in production builds. There is no internal module layering beyond this single file.

Tech Stack Built with a Babel 4-era toolchain (scripts/build), linted with ESLint (.eslintrc, eslint-plugin-react), tested with Mocha and expect.js, and measured with Istanbul for coverage (reported to Code Climate via Travis CI). immutable (^3.6.2) is a peer dependency rather than a bundled one, and invariant is the only runtime dependency. The package publishes a compiled dist/ImmutablePropTypes.js as its main entry plus hand-maintained TypeScript typings at typings/index.d.ts.

Code Quality The implementation is backed by an extensive test suite (src/__tests__/ImmutablePropTypes-test.js, 1836 lines against 293 lines of implementation) exercising valid, invalid, and required-vs-optional cases for every checker, plus explicit assertions on the generated warning messages. Error messages consistently mirror React’s own console.error PropTypes conventions rather than failing silently. The implementation itself is plain ES5/ES6 JavaScript with no static types, but naming and structure closely track React’s own PropTypes source for familiarity. CI runs via Travis across Node and io.js.

What Makes It Unique The module’s own docstring states its origin plainly: it’s a deliberate port of React’s internal PropTypes validator patterns, retargeted at Immutable.js’s collection type guards and iteration APIs. Its value is comprehensive coverage of Immutable.js’s full type surface (List, Map, OrderedMap, Set, OrderedSet, Stack, Seq, Record, and generic Iterable, both as primitive and composite/contains checkers) rather than any new validation technique — it fills a specific, narrow gap that React’s own PropTypes and Flow-based alternatives at the time did not address.