replaceOrAppend

Replace the first element in an array that matches the condition, or append to the end of the array if no matching element is found.

Basic Usage

import { replaceOrAppend } from 'radash'

const users = [
  { id: 1, name: 'Alice', age: 25 },
  { id: 2, name: 'Bob', age: 30 },
  { id: 3, name: 'Charlie', age: 35 }
]

const updatedUsers = replaceOrAppend(
  users,
  { id: 2, name: 'Bob', age: 31 }, // new data
  user => user.id === 2 // matching condition
)
// [
//   { id: 1, name: 'Alice', age: 25 },
//   { id: 2, name: 'Bob', age: 31 }, // updated
//   { id: 3, name: 'Charlie', age: 35 }
// ]

Syntax

function replaceOrAppend<T>(
  array: readonly T[],
  item: T,
  matcher: (item: T, index: number, array: readonly T[]) => boolean
): T[]

Parameters

• array (readonly T[]): The array to operate on
• item (T): The element to replace or append
• matcher (function): Function to match elements
  • item (T): Current element
  • index (number): Index of the current element
  • array (readonly T[]): The original array

Return Value

Returns a new array containing the replaced element or the appended new element.

Examples

Replacing Existing Elements

import { replaceOrAppend } from 'radash'

const products = [
  { id: 1, name: 'Laptop', price: 999 },
  { id: 2, name: 'Phone', price: 599 },
  { id: 3, name: 'Tablet', price: 399 }
]

const updatedProducts = replaceOrAppend(
  products,
  { id: 2, name: 'Phone', price: 549 }, // price reduced
  product => product.id === 2
)
// [
//   { id: 1, name: 'Laptop', price: 999 },
//   { id: 2, name: 'Phone', price: 549 }, // updated
//   { id: 3, name: 'Tablet', price: 399 }
// ]

Appending New Elements

import { replaceOrAppend } from 'radash'

const fruits = ['apple', 'banana', 'cherry']

const updatedFruits = replaceOrAppend(
  fruits,
  'orange',
  fruit => fruit === 'grape' // grape not found
)
// ['apple', 'banana', 'cherry', 'orange'] // orange appended to the end

Updating User Information

import { replaceOrAppend } from 'radash'

const users = [
  { id: 1, name: 'Alice', email: 'alice@example.com' },
  { id: 2, name: 'Bob', email: 'bob@example.com' }
]

const updatedUsers = replaceOrAppend(
  users,
  { id: 2, name: 'Bob', email: 'bob.new@example.com' },
  user => user.id === 2
)
// [
//   { id: 1, name: 'Alice', email: 'alice@example.com' },
//   { id: 2, name: 'Bob', email: 'bob.new@example.com' } // email updated
// ]

Handling Number Arrays

import { replaceOrAppend } from 'radash'

const numbers = [1, 2, 3, 4, 5]

// Replace the first even number
const updatedNumbers = replaceOrAppend(
  numbers,
  10,
  num => num % 2 === 0
)
// [1, 10, 3, 4, 5] // first even number 2 replaced with 10

// Replace non-existent element
const newNumbers = replaceOrAppend(
  numbers,
  100,
  num => num === 999 // 999 not found
)
// [1, 2, 3, 4, 5, 100] // 100 appended to the end

Handling String Arrays

import { replaceOrAppend } from 'radash'

const words = ['hello', 'world', 'javascript']

const updatedWords = replaceOrAppend(
  words,
  'typescript',
  word => word === 'javascript'
)
// ['hello', 'world', 'typescript'] // javascript replaced with typescript

Using Index Matching

import { replaceOrAppend } from 'radash'

const items = ['a', 'b', 'c', 'd']

const updatedItems = replaceOrAppend(
  items,
  'x',
  (_, index) => index === 1 // replace element at index 1
)
// ['a', 'x', 'c', 'd'] // 'b' replaced with 'x'

Notes

1. Keep original array unchanged: replaceOrAppend does not modify the original array, but returns a new array
2. Only replace first match: If there are multiple matching elements, only the first one is replaced
3. Append to end: If no matching element is found, the new element is appended to the end of the array
4. Performance: Time complexity is O(n), where n is the array length
5. Matcher function: The matcher function should return a boolean value

Differences from Other Methods

• map(): Processes all elements, not just the first matching one
• filter(): Only filters elements, cannot replace
• replaceOrAppend(): Specifically designed for replace or append operations
• splice(): Modifies the original array, while replaceOrAppend returns a new array

Practical Application Scenarios

1. User management: Update user information
2. Product management: Update product prices or information
3. Configuration management: Update configuration items
4. Form processing: Update form data
5. Cache management: Update cache items