no-array-front-mutation.md

no-array-front-mutation

📝 Disallow front-of-array mutation.

🚫 This rule is disabled in the following configs: ✅ recommended, ☑️ unopinionated.

Forbid Array#shift() and Array#unshift() in projects that want to avoid mutating the front of arrays.

These methods are not always wrong. Small one-off uses are often fine. This rule exists for codebases that prefer to avoid front-of-array mutation because repeated FIFO-style array consumption can be inefficient and is often better represented with iteration, an index cursor, or a queue.

Use intent-specific alternatives:

• Iterate without consuming the array.
• Keep an index cursor instead of repeatedly calling shift().
• Use pop() and push() when processing from the end preserves the intended order.
• Use a queue, such as yocto-queue, for repeated FIFO work.

This rule is disabled in both the recommended and unopinionated configs because shift() and unshift() can be readable and acceptable outside hot paths.

Examples

// ❌
array.shift();

// ❌
array.unshift(item);

// ✅
for (const item of array) {
	process(item);
}

// ✅
import Queue from 'yocto-queue';

const queue = new Queue();
queue.enqueue(item);
queue.dequeue();

Limitations

This rule only checks direct .shift() and .unshift() calls. It intentionally does not track aliases, computed method names, optional method calls like array.shift?.(), or Array.prototype.shift.call(array).

The rule also skips common stream-style .unshift() paths by name: stream.unshift(chunk), this.unshift(chunk), this.stream.unshift(chunk), process.stdin.unshift(chunk), process.stdout.unshift(chunk), and process.stderr.unshift(chunk). If one of those names refers to an array, the call is still ignored.