@cubux/readonly-array

A bunch of helper functions to work with read-only arrays.

import { insert, remove } from '@cubux/readonly-array';

const input: readonly number[] = [10, 20, 30];

console.log(insert(input, 1, 42, 37));
// => [10, 42, 37, 20, 30]

console.log(remove(input, 1));
// => [10, 30]
console.log(remove(input, 1, 2));
// => [10]

Alternative usage:

import * as RoArray from '@cubux/readonly-array';

const input: readonly number[] = [10, 20, 30];
console.log(RoArray.insert(input, 1, 42, 37));
// => [10, 42, 37, 20, 30]

Use Cases

State management

import { FC, useState } from 'react';
import { insert, remove, set } from '@cubux/readonly-array';

const TodoList: FC = () => {
  const [items, setItems] = useState<readonly string[]>([]);

  return (
    <ul>
      {items.map((item, i) => (
        <li key={i}>
          <button
            onClick={() => setItems(list => insert(list, i, ''))}
          >
            INS
          </button>
          <button
            onClick={() => setItems(list => remove(list, i))}
          >
            DEL
          </button>
          <input
            value={item}
            onChange={(e) => setItems(list => set(list, i, e.target.value))}
          />
        </li>
      ))}
      <li>
        <button onClick={() => setItems(list => [...list, ''])}>ADD</button>
      </li>
    </ul>
  );
};

Install

npm i @cubux/readonly-array

API

append()

append(
  array:    readonly T[],
  ...items: readonly T[],
): readonly T[]

Creates a new array containing items from input array and extra ...items in the end.

• Will return input array without changes when nothing to append.

const input = [10, 20, 30];
append(input, 40, 50);
// [10, 20, 30, 40, 50]

NOTICE: By default this function should be avoided when you surely add at least one element:

// Better
[...array, item1, item2]
// Instead of
append(array, item1, item2)

So, when appending items count can be zero:

// This will always create new array
[...array, ...addItems]

// But this will return origin `array` when `addItems` is empty array
append(array, ...addItems)

insert()

insert(
  array:    readonly T[],
  index:    number,
  ...items: readonly T[],
): readonly T[]

Creates new array by inserting new ...items into input array in offset index.

• Will throw RangeError when index is invalid.
• Will return input array without changes when nothing to insert.
• Allow appending with index = array.length.

const input = [10, 20, 30];
insert(input, 2, 40, 50);
// [10, 20, 40, 50, 30]

remove()

remove(
  array:  readonly T[],
  start:  number,
  length: number = 1,
): readonly T[]

Creates new array by omitting length items from input array at start offset.

• Will throw RangeError when index is invalid or length is negative.
• Will return input array when length is 0.
• Value of length can safely lead out of array.length.

const input = [10, 20, 30, 40];
remove(input, 1);     // => [10, 30, 40]
remove(input, 1, 2);  // => [10, 40]
remove(input, 1, 10); // => [10]

set()

set(
  array: readonly T[],
  index: number,
  value: T,
): readonly T[]

Creates new array from input array with item at offset index changed to value.

• Will throw RangeError when index is invalid.
• Will return input array when nothing to change (=== check).

const input = [10, 20, 30, 40];
set(input, 2, 42);
// => [10, 20, 42, 40]

// instead of
const next = [...input];
next[2] = 42;
next

swap()

swap(
  array: readonly T[],
  i:     number,
  j:     number,
): readonly T[]

Creates new array from source array by swapping two items at indices i and j.

• Will throw RangeError when either i or j is invalid.
• Will return input array when nothing to change (=== check for indices and items values).

const input = [10, 20, 30, 40];
swap(input, 2, 3);
// => [10, 30, 20, 40]

update()

update(
  array:   readonly T[],
  index:   number,
  updater: (prev: T, index: number) => T,
): readonly T[]

Creates new array from input array with item at offset index changed with a given callback updater. A callback updater(prev, index) will receive previous value and index.

• Will throw RangeError when index is invalid.
• Will return input array when nothing to change (=== check).

const input = [10, 20, 30, 40];
update(input, 2, (v, i) => 1000 * i + v);
// => [10, 20, 2030, 40]