or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-react-addons-update

Legacy React addon providing immutable update operations for state management without deep copying

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/react-addons-update@15.6.x

To install, run

npx @tessl/cli install tessl/npm-react-addons-update@15.6.0

index.mddocs/

React Addons Update

React Addons Update is a legacy React addon that provides immutable update operations for JavaScript objects and arrays. It enables efficient state management without mutating original data structures or performing expensive deep copies.

Package Information

  • Package Name: react-addons-update
  • Package Type: npm
  • Language: JavaScript (ES5)
  • Installation: npm install react-addons-update

Core Imports

import update from 'react-addons-update';

For CommonJS:

const update = require('react-addons-update');

For browser usage with React already loaded:

<!-- development version -->
<script src="https://unpkg.com/react-addons-update/react-addons-update.js"></script>
<!-- Then use React.addons.update -->

Basic Usage

import update from 'react-addons-update';

// Simple array update
const initialArray = [1, 2, 3];
const newArray = update(initialArray, {$push: [4]}); 
// Result: [1, 2, 3, 4], initialArray unchanged

// Object property update
const obj = {a: 5, b: 3};
const newObj = update(obj, {b: {$set: 6}});
// Result: {a: 5, b: 6}, obj unchanged

// Nested object update
const state = {
  user: {name: 'Alice', preferences: {theme: 'dark'}},
  posts: [1, 2, 3]
};
const newState = update(state, {
  user: {preferences: {theme: {$set: 'light'}}},
  posts: {$push: [4]}
});

Architecture

React Addons Update uses a command-based approach to immutable updates:

  • Shallow Copying: Creates shallow copies of objects/arrays using shallowCopy() function
  • Command Processing: Six specialized commands ($push, $unshift, $splice, $set, $merge, $apply) handle different update patterns
  • Recursive Updates: Nested object/array updates are processed recursively
  • Immutability: Original data structures are never modified; always returns new references
  • Performance: Avoids expensive deep copying by only copying at the level where changes occur

The library ensures data integrity through extensive invariant checking and type validation.

Capabilities

Update Function

The main function that returns an updated shallow copy of an object or array without mutating the original.

/**
 * Returns an updated shallow copy of an object without mutating the original
 * @param {any} value - The target object/array to update
 * @param {object} spec - Update specification containing commands
 * @returns {any} Updated shallow copy of the input value
 * @throws {Error} Invariant errors for invalid specifications
 */
function update(value, spec);

The spec parameter is an object that describes how to update the value. It uses special command keys prefixed with $ to specify different types of updates.

Usage Examples:

// Basic object update
const person = {name: 'John', age: 30};
const updatedPerson = update(person, {age: {$set: 31}});

// Array manipulation
const numbers = [1, 2, 3];
const moreNumbers = update(numbers, {$push: [4, 5]});

// Complex nested update
const data = {
  users: [{id: 1, name: 'Alice'}, {id: 2, name: 'Bob'}],
  settings: {theme: 'dark', notifications: true}
};
const updatedData = update(data, {
  users: {0: {name: {$set: 'Alice Smith'}}},
  settings: {$merge: {language: 'en'}}
});

Push Command

Adds items to the end of an array target.

// Command syntax: {$push: array}
// Pushes all items in the array to the target array

Usage Example:

const fruits = ['apple', 'banana'];
const moreFruits = update(fruits, {$push: ['orange', 'grape']});
// Result: ['apple', 'banana', 'orange', 'grape']

Unshift Command

Adds items to the beginning of an array target.

// Command syntax: {$unshift: array}
// Unshifts all items in the array to the target array

Usage Example:

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

Splice Command

Performs splice operations on an array target using standard Array.splice syntax.

// Command syntax: {$splice: array_of_arrays}
// Each inner array contains splice arguments: [start, deleteCount, ...items]

Usage Example:

const letters = ['a', 'b', 'c', 'd'];
const modified = update(letters, {
  $splice: [[1, 2, 'x', 'y']] // Remove 2 items at index 1, insert 'x', 'y'
});
// Result: ['a', 'x', 'y', 'd']

// Multiple splice operations
const data = [1, 2, 3, 4, 5];
const result = update(data, {
  $splice: [
    [0, 1], // Remove first item
    [2, 0, 'inserted'] // Insert at index 2
  ]
});

Set Command

Replaces the target entirely with the provided value.

// Command syntax: {$set: any}
// Replaces the target entirely with the provided value

Usage Example:

const config = {api: 'v1', timeout: 5000};
const newConfig = update(config, {api: {$set: 'v2'}});
// Result: {api: 'v2', timeout: 5000}

// Can set any type
const data = {items: [1, 2, 3]};
const cleared = update(data, {items: {$set: []}});
// Result: {items: []}

Merge Command

Performs a shallow merge of the provided object with the target object.

// Command syntax: {$merge: object}
// Merges the keys of the object with the target (shallow merge)

Usage Example:

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

// Merge with nested objects
const settings = {ui: {theme: 'dark'}, api: {version: 1}};
const newSettings = update(settings, {
  ui: {$merge: {language: 'en'}},
  api: {$merge: {timeout: 3000}}
});

Apply Command

Applies a function to the current value and updates with the returned result.

// Command syntax: {$apply: function}
// Passes current value to function and updates with returned value

Usage Example:

const counter = {count: 5};
const incremented = update(counter, {
  count: {$apply: (x) => x + 1}
});
// Result: {count: 6}

// Transform array items
const items = {data: [1, 2, 3]};
const doubled = update(items, {
  data: {$apply: (arr) => arr.map(x => x * 2)}
});
// Result: {data: [2, 4, 6]}

// Complex transformations
const text = {content: '  hello world  '};
const cleaned = update(text, {
  content: {$apply: (str) => str.trim().toUpperCase()}
});
// Result: {content: 'HELLO WORLD'}

Command Rules and Constraints

Set Command Exclusivity

When using $set, it must be the only key in the specification object:

// Valid
update(obj, {field: {$set: 'new value'}});

// Invalid - will throw error
update(obj, {field: {$set: 'new value', $merge: {other: 'data'}}});

Array Command Requirements

Array commands ($push, $unshift, $splice) require array targets:

// Valid
update([1, 2, 3], {$push: [4]});

// Invalid - will throw error
update({a: 1}, {$push: [2]});

Type Validation

All commands validate their inputs and targets:

// $apply requires a function
update(obj, {field: {$apply: 'not a function'}}); // Throws error

// $merge requires an object
update(obj, {$merge: 'not an object'}); // Throws error

// Array commands require array values
update(arr, {$push: 'not an array'}); // Throws error

Error Handling

The update function throws invariant errors for:

  • Invalid specification objects (non-objects)
  • Multiple keys when using $set command
  • Wrong types for command values (e.g., non-function for $apply)
  • Wrong target types for array commands
  • Invalid splice operation parameters

Example error handling:

try {
  const result = update(data, {$invalidCommand: 'value'});
} catch (error) {
  console.error('Update specification invalid:', error.message);
}

Migration Notes

This package is deprecated and no longer maintained. For new projects, use immutability-helper which provides the same API as a drop-in replacement.

// Migration
// Old: import update from 'react-addons-update';
// New: import update from 'immutability-helper';