react-immutable-pure-component

react-immutable-pure-component provides ImmutablePureComponent and immutableMemo, two lightweight wrappers that teach React’s built-in optimization primitives to understand Immutable.js. React.PureComponent and React.memo only perform shallow reference equality, which misses on nearly every render when props or state are wrapped in Immutable.js Maps, Lists, or Records, even when the underlying values are unchanged. This library swaps that check for Immutable’s own is() value comparison, so components only re-render when the data they actually reference has changed.

Both the class-based ImmutablePureComponent and the function-based immutableMemo support updateOnProps and updateOnStates arrays, letting consumers scope the comparison to a subset of props or state, including nested key paths, rather than diffing everything on every render. The library has no runtime dependencies of its own beyond its peer dependencies on React and Immutable.js, and ships as a small, focused utility rather than a full state-management solution.

What You Get

• ImmutablePureComponent, a drop-in React.Component base class with an Immutable-aware shouldComponentUpdate
• immutableMemo, a React.memo wrapper with the same Immutable-aware comparison for function components
• updateOnProps / updateOnStates arrays to scope comparisons to specific props/state keys or nested paths
• TypeScript type definitions shipped in the package (types/react-immutable-pure-component.d.ts)
• Separate CommonJS and ES module builds produced via Rollup for compatibility with different bundlers

Common Use Cases

• Class components holding large Immutable.Map or List props that re-render on every parent update despite unchanged data
• Function components that need React.memo but receive Immutable.js collections as props
• Selectively re-rendering only when a specific nested field of a large Immutable Record changes
• Migrating a Redux + Immutable.js-heavy app to cut unnecessary render churn without hand-writing comparison logic

Under The Hood

Architecture The library is a flat, single-purpose module set: src/index.js exports ImmutablePureComponent (pure-component.js) and immutableMemo (memo.js), and both are thin adapters over one shared comparison primitive, check() in check.js, which itself delegates path traversal to getIn() in utils.js. There is no internal dependency injection or layering beyond this — changing check()‘s semantics changes both public entry points uniformly, and either entry point could be deleted without touching the other’s implementation, since neither depends on the other.

Tech Stack Written in plain JavaScript (not TypeScript) with hand-authored .d.ts type definitions, built with Babel 7 and bundled by Rollup into both CommonJS and ES module outputs (rollup-plugin-babel, rollup-plugin-copy). Immutable.js and React are peer dependencies rather than bundled dependencies. Linting runs through ESLint with a shared external config (eslint-config-monar) plus the flowtype plugin, and publishing is gated by publish-please, which runs the test-and-build script and checks for vulnerable dependencies, uncommitted changes, and sensitive data before allowing an npm publish.

Code Quality The core check() comparison logic is covered by a focused Jest test suite (check.test.js, pure-component.test.js, utils.test.js) using snapshot assertions and Enzyme, exercising edge cases like empty checklists, shared instances, shallow copies, and equal-by-value Immutable collections built from different instances. Error handling is minimal but explicit: check() throws a TypeError for an invalid key type rather than failing silently. No CI configuration (e.g. GitHub Actions workflow) was found in the repository, and there are no TypeScript source files, so type safety is enforced only at the boundary via the shipped .d.ts file rather than throughout the implementation.

API Design The public surface is intentionally tiny: extend one class or wrap one component, with two optional arrays (updateOnProps, updateOnStates) to scope which fields are compared, using the same array-of-keys-or-paths convention on both the class and function entry points. This symmetry between ImmutablePureComponent and immutableMemo keeps the learning curve low for anyone already familiar with either API. The README documents both APIs with type signatures and links to a live CodeSandbox example, though there is no separate docs site or CONTRIBUTING guide.