array-move

array-move is a tiny zero-dependency JavaScript utility for repositioning an item within an array. It exports two functions: arrayMoveImmutable, which clones the array and returns a new one with the item moved, and arrayMoveMutable, which performs the move in place for cases where allocating a new array isn’t practical.

Both functions accept negative indexes for fromIndex and toIndex, mirroring the semantics of Array.prototype.slice, so items can be referenced relative to the end of the array without manually computing an offset. The package ships as native ESM, includes hand-written TypeScript declarations with generic typing for arrayMoveImmutable, and is maintained by Sindresorhus as part of his broader collection of small, focused utility modules.

What You Get

• arrayMoveImmutable(array, fromIndex, toIndex) - clones the input array and returns a new array with the item repositioned, leaving the original untouched
• arrayMoveMutable(array, fromIndex, toIndex) - splices the item into its new position directly on the given array for performance-sensitive cases
• Negative-index support - both functions accept negative fromIndex/toIndex values that count backward from the end of the array, matching Array.prototype.slice semantics
• TypeScript declarations - index.d.ts ships generic, documented type signatures with tsd-verified examples, so array-move works out of the box in typed codebases

Common Use Cases

• Reordering drag-and-drop list items - move a dragged list entry from its old index to its new drop position after a UI reorder event
• Prioritizing or demoting a task in a queue - shift a task or job to the front or back of an in-memory queue array without a manual splice
• Undo/redo step reordering - reposition entries in a history stack when a user reorders past actions
• Reordering large in-memory arrays - use arrayMoveMutable to avoid the allocation cost of copying huge arrays on every reorder

Under The Hood

Architecture array-move is a single-file library with no internal layering: index.js exports two flat functions, arrayMoveMutable and arrayMoveImmutable, and the latter is implemented purely as a thin wrapper that spreads the input into a new array before delegating to arrayMoveMutable to perform the actual splice-based move. There is no class hierarchy, dependency injection, or configuration surface — the entire data flow is: resolve negative fromIndex/toIndex against array.length, then splice the item out and back in at the new position. Because the module’s only job is a single array-mutation primitive, this flat, dependency-free structure is the correct level of abstraction rather than a limitation; if the underlying splice-based approach ever changed, both exported functions would need updating together since arrayMoveImmutable’s correctness is entirely inherited from arrayMoveMutable.

Tech Stack The package has zero runtime dependencies and ships as native ESM (type: module, a single exports entry pointing at index.js), targeting Node engines ^12.20.0 || ^14.13.1 || >=16.0.0. There is no build or bundling step — the raw ES module is published directly to npm. Development tooling consists of ava as the test runner, tsd for compile-time type assertions against the hand-written declaration file, and xo as an opinionated, Prettier-aligned ESLint preset for linting.

Code Quality test.js exercises arrayMoveImmutable across positive, negative, and out-of-range index combinations with ava’s deepEqual assertions, plus a companion assertion for arrayMoveMutable, giving the small surface area comprehensive coverage. index.test-d.ts type-checks the exported generic signature via tsd. Error handling is defensive rather than exception-based: arrayMoveMutable silently no-ops when the resolved start index falls outside the array’s bounds instead of throwing, which is a deliberate choice documented by the passing out-of-range test cases. Naming is clear and consistent (Immutable/Mutable suffixes), xo enforces consistent style, and a GitHub Actions workflow (.github/workflows/main.yml) runs npm test on every push and pull request.

API Design The public API is deliberately minimal: two verb-first functions with an unambiguous Immutable/Mutable naming split, no options object, and no configuration to learn. TypeScript generics preserve the array’s element type through arrayMoveImmutable, and negative-index handling mirrors the well-known Array.prototype.slice convention, so there’s nothing new to memorize. Every exported function carries a JSDoc block with a runnable example directly in index.d.ts, making the API discoverable from editor tooltips alone without visiting the README.