tessl/npm-immutability-helper

Mutate a copy of data without changing the original source

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Array Operations

Name: tessl/npm-immutability-helper
Author: tessl

Core operations for modifying arrays including adding items to the beginning or end, and performing splice operations. All operations create new arrays without mutating the original.

Capabilities

Push Operation

Appends items to the end of an array.

/**
 * Push items to the end of an array
 * @param value - Array of items to append
 * @returns New array with items appended
 */
{ $push: ReadonlyArray<T> }

Usage Examples:

import update from "immutability-helper";

// Basic push
const arr = [1, 2, 3];
const result = update(arr, { $push: [4, 5] });
// Result: [1, 2, 3, 4, 5]

// Push to nested array
const data = { items: ['a', 'b'] };
const updated = update(data, { items: { $push: ['c', 'd'] } });
// Result: { items: ['a', 'b', 'c', 'd'] }

// Empty push preserves reference
const original = [1, 2, 3];
const unchanged = update(original, { $push: [] });
console.log(unchanged === original); // true

Unshift Operation

Prepends items to the beginning of an array.

/**
 * Add items to the beginning of an array
 * @param value - Array of items to prepend
 * @returns New array with items prepended
 */
{ $unshift: ReadonlyArray<T> }

Usage Examples:

import update from "immutability-helper";

// Basic unshift
const arr = [3, 4, 5];
const result = update(arr, { $unshift: [1, 2] });
// Result: [1, 2, 3, 4, 5]

// Unshift to nested array
const data = { queue: ['task2', 'task3'] };
const updated = update(data, { queue: { $unshift: ['task1'] } });
// Result: { queue: ['task1', 'task2', 'task3'] }

Splice Operation

Performs multiple splice operations on an array. Each splice operation is specified as an array of arguments that would be passed to Array.prototype.splice().

/**
 * Perform splice operations on an array
 * @param value - Array of splice operation arguments
 * Each splice operation: [start, deleteCount?, ...itemsToInsert]
 * @returns New array with splice operations applied sequentially
 */
{ $splice: ReadonlyArray<[number, number?] | [number, number, ...T[]]> }

Usage Examples:

import update from "immutability-helper";

// Remove items
const arr = [1, 2, 3, 4, 5];
const removed = update(arr, { $splice: [[1, 2]] }); // Remove 2 items starting at index 1
// Result: [1, 4, 5]

// Replace items
const replaced = update(arr, { $splice: [[1, 1, 'a', 'b']] }); // Replace 1 item at index 1 with 'a', 'b'
// Result: [1, 'a', 'b', 3, 4, 5]

// Multiple splice operations (applied sequentially)
const multi = update([0, 1, 2, 3, 4], { 
  $splice: [
    [1, 1],        // Remove 1 item at index 1
    [2, 0, 'x']    // Insert 'x' at index 2 (after first operation)
  ] 
});
// Result: [0, 2, 'x', 3, 4]

// Insert without removing
const inserted = update(arr, { $splice: [[2, 0, 'new']] });
// Result: [1, 2, 'new', 3, 4, 5]

// Delete element at specific index (common pattern)
const items = ['a', 'b', 'c', 'd'];
const index = 2;
const withDeleted = update(items, { $splice: [[index, 1]] });
// Result: ['a', 'b', 'd'] (removed 'c' at index 2)

// Nested array splice
const data = { list: [10, 20, 30, 40] };
const updated = update(data, { 
  list: { $splice: [[1, 1, 25]] } 
});
// Result: { list: [10, 25, 30, 40] }

// Computed property names (ES2015 feature)
const collection = { children: ['zero', 'one', 'two'] };
const index = 1;
const updated = update(collection, { 
  children: { [index]: { $set: 'updated' } } 
});
// Result: { children: ['zero', 'updated', 'two'] }

Error Handling

Array operations validate their inputs and throw descriptive errors:

$push and $unshift require the target to be an array
$push and $unshift require the spec value to be an array
$splice requires the target to be an array
$splice requires the spec value to be an array of arrays
Each splice operation must be an array of valid splice arguments

// These will throw errors:
update(123, { $push: [1] }); // Target must be array
update([1], { $push: 123 }); // Spec must be array
update([1], { $splice: 123 }); // Spec must be array of arrays
update([1], { $splice: [123] }); // Each splice must be array

Performance Notes

Operations preserve reference equality when no changes occur (e.g., empty push/unshift)
Only creates new arrays when modifications are actually made
Splice operations are applied sequentially, so order matters for indices
Uses shallow copying for optimal performance