immutability_skill

Overview

This skill enforces immutable update patterns for objects and arrays in TypeScript code. It guides developers to never mutate function parameters or shared state and to always return new objects, making changes explicit and predictable. The result is fewer subtle bugs, reliable React/Redux state updates, and easier debugging and undo/redo flows.

How this skill works

It inspects code paths where objects or arrays are modified and flags direct mutations (assignments, push/pop/splice, sort without copying, delete, etc.). It recommends and demonstrates immutable alternatives using spread, filter, map, slice, and deep-copy patterns, and points to helpers like immer for complex nested updates. It emphasizes returning new references so change detection and reasoning remain correct.

When to use it

• When modifying objects or arrays
• When updating React or Redux state
• When a function receives an object or array parameter
• When data is shared across modules or components
• When state changes cause intermittent or hard-to-reproduce bugs

Best practices

• Never mutate inputs; always return new copies.
• Use spread ({ ...obj }) for shallow updates and map/filter for arrays.
• For nested updates, copy each level or use a library like immer.
• Avoid array-mutating methods (push, pop, splice, sort) directly; operate on copied arrays.
• If concerned about performance, profile first—engines optimize short-lived objects.

Example use cases

• Updating a user address without changing the original user object.
• Adding or removing items from a cart with [...cart, item] or cart.filter(...).
• Changing a theme setting nested inside config by copying each level.
• Implementing undo/redo by keeping previous immutable states in history.
• Refactoring code that mutates parameters to return new values to prevent cross-module side effects.