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

Object Operations

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

Operations for modifying object properties including complete replacement, merging properties, toggling boolean fields, and removing properties. All operations create new objects without mutating the original.

Capabilities

Set Operation

Replaces the target entirely with a new value.

/**
 * Replace the target entirely with a new value
 * @param value - New value to replace the target
 * @returns The new value
 */
{ $set: T }

Usage Examples:

import update from "immutability-helper";

// Replace primitive value
const obj = { count: 5 };
const updated = update(obj, { count: { $set: 10 } });
// Result: { count: 10 }

// Replace object property
const data = { user: { name: 'Alice', age: 25 } };
const replaced = update(data, { 
  user: { $set: { name: 'Bob', age: 30, role: 'admin' } } 
});
// Result: { user: { name: 'Bob', age: 30, role: 'admin' } }

// Replace array
const state = { items: [1, 2, 3] };
const newState = update(state, { items: { $set: ['a', 'b'] } });
// Result: { items: ['a', 'b'] }

// Replace entire object
const result = update({ a: 1, b: 2 }, { $set: { c: 3 } });
// Result: { c: 3 }

Merge Operation

Performs a shallow merge of properties from the spec into the target object.

/**
 * Shallow merge properties into the target object
 * @param value - Object containing properties to merge
 * @returns New object with merged properties
 */
{ $merge: Partial<T> }

Usage Examples:

import update from "immutability-helper";

// Basic merge
const user = { name: 'Alice', age: 25, role: 'user' };
const updated = update(user, { 
  $merge: { age: 26, role: 'admin' } 
});
// Result: { name: 'Alice', age: 26, role: 'admin' }

// Add new properties
const obj = { a: 1 };
const merged = update(obj, { $merge: { b: 2, c: 3 } });
// Result: { a: 1, b: 2, c: 3 }

// Nested merge
const data = { 
  config: { theme: 'dark', lang: 'en' },
  user: { name: 'Alice' }
};
const result = update(data, { 
  config: { $merge: { theme: 'light', debug: true } } 
});
// Result: { 
//   config: { theme: 'light', lang: 'en', debug: true },
//   user: { name: 'Alice' }
// }

Toggle Operation

Toggles boolean fields in the target object.

/**
 * Toggle boolean fields in the target object
 * @param targets - Array of property keys to toggle
 * @returns New object with toggled boolean properties
 */
{ $toggle: ReadonlyArray<keyof T> }

Usage Examples:

import update from "immutability-helper";

// Toggle single field
const settings = { darkMode: false, notifications: true };
const toggled = update(settings, { $toggle: ['darkMode'] });
// Result: { darkMode: true, notifications: true }

// Toggle multiple fields
const flags = { 
  isActive: true, 
  isVisible: false, 
  isEditable: true 
};
const updated = update(flags, { 
  $toggle: ['isActive', 'isVisible'] 
});
// Result: { isActive: false, isVisible: true, isEditable: true }

// Nested toggle
const data = { 
  user: { isOnline: false, hasNotifications: true },
  system: { maintenanceMode: false }
};
const result = update(data, { 
  user: { $toggle: ['isOnline', 'hasNotifications'] } 
});
// Result: { 
//   user: { isOnline: true, hasNotifications: false },
//   system: { maintenanceMode: false }
// }

Unset Operation

Removes specified properties from the target object.

/**
 * Remove properties from the target object
 * @param keys - Array of property keys to remove
 * @returns New object with specified properties removed
 */
{ $unset: ReadonlyArray<keyof T> }

Usage Examples:

import update from "immutability-helper";

// Remove single property
const user = { name: 'Alice', age: 25, temp: 'remove me' };
const cleaned = update(user, { $unset: ['temp'] });
// Result: { name: 'Alice', age: 25 }

// Remove multiple properties
const obj = { a: 1, b: 2, c: 3, d: 4 };
const filtered = update(obj, { $unset: ['b', 'd'] });
// Result: { a: 1, c: 3 }

// Nested unset
const data = { 
  config: { theme: 'dark', debug: true, tempFlag: 'delete' },
  user: { name: 'Alice' }
};
const result = update(data, { 
  config: { $unset: ['debug', 'tempFlag'] } 
});
// Result: { 
//   config: { theme: 'dark' },
//   user: { name: 'Alice' }
// }

// Attempting to remove non-existent property (no effect)
const safe = update({ a: 1 }, { $unset: ['nonexistent'] });
// Result: { a: 1 } (unchanged)

Error Handling

Object operations validate their inputs and throw descriptive errors:

$set cannot be combined with other commands in the same specification object
$merge requires both the target and spec value to be objects
$toggle requires the spec value to be an array
$unset requires the spec value to be an array

// These will throw errors:
update({}, { $set: 1, $merge: {} }); // Cannot combine $set with other commands
update('string', { $merge: {} }); // Target must be object for $merge
update({}, { $merge: 'string' }); // Spec must be object for $merge
update({}, { $toggle: 'field' }); // Spec must be array for $toggle
update({}, { $unset: 'field' }); // Spec must be array for $unset