insert
insert
Inserts one or multiple items into an array T[]. Returns a new array T[] and
does not mutate the original one.
Immutability is explained in the immutability & serializable state concept.
Example — inserting a single value
const creatures = [
{ id: 1, type: 'cat' },
{ id: 2, type: 'dog' },
];
const updatedCreatures = insert(creatures, { id: 3, type: 'parrot' });
// updatedCreatures will be:
// [{id: 1, type: 'cat'}, {id: 2, type: 'dog'}, {id: 3, type: 'parrot'}];
Example — inserting multiple values
const creatures = [
{ id: 1, type: 'cat' },
{ id: 2, type: 'dog' },
];
const updatedCreatures = insert(creatures, [
{ id: 3, type: 'parrot' },
{ id: 4, type: 'hamster' },
]);
// updatedCreatures will be:
// [{id: 1, type: 'cat'}, {id: 2, type: 'dog'}, {id: 3, type: 'parrot'}, {id: 4, type: 'hamster'}];
Example — with rxState()
import { Component, inject } from '@angular/core';
import { Subject } from 'rxjs';
import { rxState } from '@rx-angular/state';
import { insert } from '@rx-angular/cdk/transformations';
@Component({
/* ... */
})
export class ListComponent {
readonly insertCreature$ = new Subject<void>();
private readonly state = rxState<ComponentState>(({ connect }) => {
connect('creatures', this.insertCreature$, ({ creatures }) => {
const creatureToAdd = {
id: generateId(),
name: 'newCreature',
type: 'dinosaur',
};
return insert(creatures, creatureToAdd);
});
});
readonly creatures = this.state.signal('creatures');
// Imperative alternative
insertCreature(): void {
const creatureToAdd = {
id: generateId(),
name: 'newCreature',
type: 'dinosaur',
};
this.state.set({
creatures: insert(this.state.get('creatures'), creatureToAdd),
});
}
}
Example — signals-first
import { signal } from '@angular/core';
import { insert } from '@rx-angular/cdk/transformations';
const creatures = signal<Creature[]>([]);
creatures.update((current) => insert(current, { id: 3, type: 'parrot' }));
Edge cases
insert(null as any, items) > items;
insert(items, null as any) > items;
insert(null as any, null as any) > null;
insert(undefined as any, undefined as any) > undefined;
insert(nonArray as any, items) > items;
Signature
function insert<T>(source: T[], updates: T | T[]): T[];