@onsetsoftware/mutable-js
v0.6.0
Published
MutableJS is a zero-dependency library for mutating Javascript objects and arrays _in place_, where typically a new object or array would be created.
Downloads
20
Readme
MutableJS
MutableJS is a zero-dependency library for mutating Javascript objects and arrays in place, where typically a new object or array would be created.
This is especially useful when working with Automerge documents, where all changes are required to mutate the document in place.
Installation
npm install @onsetsoftware/mutable-js
Functions
Deduplicate
Removes duplicate values from an array.
import { deduplicate } from "@onsetsoftware/mutable-js";
const arr = [1, 2, 3, 4, 5, 1, 2, 3, 4, 5];
deduplicate(arr); // => arr = [1, 2, 3, 4, 5]
Filter
Removes values from an array that do not match a predicate.
import { filter } from "@onsetsoftware/mutable-js";
const arr = [1, 2, 3, 4, 5];
filter(arr, (x) => x % 2 === 0); // => arr = [2, 4]
Map
Applies a function to each value in an array.
import { map } from "@onsetsoftware/mutable-js";
const arr = [1, 2, 3, 4, 5];
map(arr, (x) => x * 2); // => arr = [2, 4, 6, 8, 10]
Move Within
There are 2 functions for moving values within an array.
moveWithin(items: T[], insertIndex: number, indices: number[])
Moves items within an array to a new position, in the order defined by the indices.
import { moveWithin } from "@onsetsoftware/mutable-js";
const arr = ["a", "b", "c", "d", "e"];
const indices = [2, 4, 1];
moveWithin(arr, 0, indices); // => arr = ["c", "e", "b", "a", "d"]
moveWithinOrdered(items: T[], insertIndex: number, indices: number[])
Moves items within an array to a new position, keeping the order of the moved items in original array order, regardless of the order of the indices provided.
This is useful when (for example) a number of selections have been made in a list and the user wants to move them all to a new position, keeping them in the order of the original array
import { moveWithinOrdered } from "@onsetsoftware/mutable-js";
const arr = ["a", "b", "c", "d", "e"];
const indices = [2, 4, 1];
moveWithinOrdered(arr, 0, indices); // => arr = ["b", "c", "e", "a", "d"]
Entities
These are a set of mutable utilities for working with entities in an entity state:
import { EntityState } from "@onsetsoftware/mutable-js";
const people: EntityState<{ id: string }> = {
ids: ["id-1"],
entities: {
"id-1": {
name: "John",
age: 20,
id: "id-1",
},
},
};
The EntityState<T>
type is included for your convenience.
export type EntityState<T extends { id: string }> = {
ids: string[];
entities: Record<string, T>;
};
addEntity
Adds an entity to an entity state.
import { EntityState, addEntity } from "@onsetsoftware/mutable-js";
const person: Person = {
name: "Jane",
id: "id-2",
age: 21,
};
addEntity(people, person);
addEntities
Adds multiple entities to an entity state.
import { addEntities } from "@onsetsoftware/mutable-js";
const morePeople: Person[] = [
{
name: "Jane",
id: "id-2",
age: 21,
},
{
name: "Jack",
id: "id-3",
age: 22,
},
];
addEntities(people, morePeople);
updateEntity
Updates an entity in an entity state. This takes a partial entity (which must include an id
).
const person = {
id: "id-1",
age: 21,
};
updateEntity(people, person); // => john's age === 21
deleteEntity
Deletes an entity from an entity state.
deleteEntity(people, "id-1"); // => people = { ids: [], entities: {} }
Update Array
Updates a source array in place, based on the values in a target array.
updateArray
const source = ["a", "b", "c"];
const target = ["b", "c", "a", "d"];
updateArray(source, target);
// source => ['b', 'c', 'a', 'd']