perpetual-js

A light weight version of Immutable.js. This library comes in at 8kb minified and 3kb minified + gzipped.

Because of efforts to keep bundle size small not all methods are included in Perpetual. Just the essential ones.

Installation

Install perpetual-js using npm or yarn.

npm install perpetual-js
yarn add perpetual-js

Requirements

Object.assign()
rest/spread
{ ...object }

Usage

Perpetual comes with two different immutable collections: Map and List. Map: is a collection of key value pairs. List: is a collection of values.

Example

• Can import multiple different ways.

import { Map, List } from 'perpetual-js';
 
const map = Map({ value: 'value' });
const list = List([1, 2, 3, 4]);

fromJS()

Deeply converts plain JS objects and arrays to Immutable Maps and Lists.

fromJS(jsValue: any): any

is()

Value equality check with semantics similar to Object.is, but treats Immutable Collections as values, equal if the second Collection includes equivalent values.

is(first: any, second: any): boolean

Map

*get()

Returns the value associated with the provided key, or notSetValue if the Collection does not contain this key.

get<NSV>(key: K, notSetValue: NSV): V | NSV
get(key: K): V | undefined

*getIn()

Returns the value found by following a path of keys or indices through nested Collections.

getIn(searchKeyPath: Iterable<array>, notSetValue?: any): any

*hashCode()

The hashCode() function is an important part of how Perpetual determines if two values are equivalent and is used to determine how to store those values.

hashCode(): number

*has()

True if a key exists within this Collection.

has(key: K): boolean

*hasIn()

True if the result of following a path of keys or indices through nested Collections results in a set value.

hasIn(searchKeyPath: Iterable<array>): boolean

*map()

Returns a new Map with values passed through a mapper function.

map<M>(mapper: (value: V, key: K, iter: this) => M, context?: any): Map<K, M>

*merge()

Returns a new Map resulting from merging the provided Collections (or JS objects) into this Map. In other words, this takes each entry of each collection and sets it on this Map.

merge<KC, VC>(...collections: Array<Iterable<[KC, VC]>>): Map<K | KC, V | VC>
merge<C>(...collections: Array<{[key: string]: C}>): Map<K | string, V | C>

*mergeDeep()

Like merge(), but when two Collections conflict, it merges them as well, recursing deeply through the nested data.

mergeDeep(...collections: Array<Iterable<[K, V]> | {[key: string]: V}>): this

*mergeDeepIn()

A combination of updateIn and mergeDeep, returning a new Map, but performing the deep merge at a point arrived at by following the keyPath.

mergeDeepIn(keyPath: Iterable<array>, ...collections: Array<any>): this

*mergeIn()

A combination of updateIn and merge, returning a new Map, but performing the merge at a point arrived at by following the keyPath.

mergeIn(keyPath: Iterable<array>, ...collections: Array<any>): this

*set()

Returns a new Map also containing the new key, value pair. If an equivalent key already exists in this Map, it will be replaced.

set(key: K, value: V): this

*setIn()

Returns a new Map having set value at this keyPath. If any keys in keyPath do not exist, a new immutable Map will be created at that key.

setIn(keyPath: Iterable<array>, value: any): this

*spread()

Returns an Object with the values provided to the spread method.

spread(...keys: keyPath<array> | key<string>) : Object

*delete()

Returns a new Map which exludes this key.

delete(key: K): this

alias: remove()

*deleteIn()

Returns a new Map having removed the value at this keyPath. If any keys in keyPath do not exist, no change will occur.

deleteIn(keyPath: Iterable<array>): this

*reduce()

Returns a new Map with values passed through a reduce function.

reduce<R>(
reducer: (reduction: R, value: [K, V], key: number, iter: this) => R,
initialReduction: R,
context?: any
): R
reduce<R>(
reducer: (reduction: T | R, value: [K, V], key: number, iter: this) => R
): R

*toJS()

Deeply converts this Keyed collection to equivalent native JavaScript Object.

toJS(): Object

*update()

Returns a new Map having updated the value at this key with the return value of calling updater with the existing value.

update(key: K, notSetValue: V, updater: (value: V) => V): this
update(key: K, updater: (value: V) => V): this
update<R>(updater: (value: this) => R): R

*updateIn()

Returns a new Map having applied the updater to the entry found at the keyPath.

updateIn(
keyPath: Iterable<array>,
notSetValue: any,
updater: (value: any) => any
): this
updateIn(keyPath: Iterable<array>, updater: (value: any) => any): this

*withMutations()

Every time you call one of the above functions, a new immutable Map is created. If a pure function calls a number of these to produce a final return value, then a penalty on performance and memory has been paid by creating all of the intermediate immutable Maps.

withMutations(mutator: (mutable: this) => any): this

List

*clear()

Returns a new List with 0 size and no values in constant time.

clear(): List<T>

*concat()

Returns a new List with other values or collections concatenated to this one.

concat<C>(...valuesOrCollections: Array<Iterable<C> | C>): List<T | C>

alias: merge

*delete()

Returns a new List which excludes this index and with a size 1 less than this List. Values at indices above index are shifted down by 1 to fill the position.

delete(index: number): List<T>

*deleteIn()

Returns a new List having removed the value at this keyPath. If any keys in keyPath do not exist, no change will occur.

deleteIn(keyPath: Iterable<any>): this

*get()

Returns the value associated with the provided index, or notSetValue if the index is beyond the bounds of the Collection.

get<NSV>(index: number, notSetValue: NSV): T | NSV
get(index: number): T | undefined

*getIn()

Returns the value found by following a path of keys or indices through nested Collections.

getIn(searchKeyPath: Iterable<any>, notSetValue?: any): any

*has()

True if a key exists within this Collection.

has(key: number): boolean

*hashCode()

The hashCode() function is an important part of how Perpetual determines if two values are equivalent and is used to determine how to store those values.

hashCode(): number

*includes()

True if a value exists within this Collection, using Immutable.is to determine equality

includes(value: T): boolean

*insert()

Returns a new List with value at index with a size 1 more than this List. Values at indices above index are shifted over by 1.

insert(index: number, value: T): List<T>

*map()

Returns a new List with values passed through a mapper function.

map<M>(mapper: (value: T, key: number, iter: this) => M, context?: any): List<M>

*mergeDeepIn()

A combination of updateIn and mergeDeep, returning a new Map, but performing the deep merge at a point arrived at by following the keyPath.

mergeDeepIn(keyPath: Iterable<array>, ...collections: Array<any>): this

*mergeIn()

A combination of updateIn and merge, returning a new Map, but performing the merge at a point arrived at by following the keyPath.

mergeIn(keyPath: Iterable<array>, ...collections: Array<any>): this

*pop()

Returns a new List with a size ones less than this List, excluding the last index in this List.

pop(): List<T>

*push()

Returns a new List with the provided values appended, starting at this List's size.

push(...values: Array<T>): List<T>

*set()

Returns a new List which includes value at index. If index already exists in this List, it will be replaced.

set(index: number, value: T): List<T>

*setIn()

Returns a new List having set value at this keyPath. If any keys in keyPath do not exist, a new immutable Map will be created at that key.

setIn(keyPath: Iterable<any>, value: any): this

*shift()

Returns a new List with a size ones less than this List, excluding the first index in this List, shifting all other values to a lower index.

shift(): List<T>

*splice()

Splice returns a new indexed Collection by replacing a region of this Collection with new values. If values are not provided, it only skips the region to be removed.

splice(index: number, removeNum: number, ...values: Array<T>): this

*spread()

Returns an Array with the values provided to the spread method.

spread(...keys: keyPath<array> | key<string>) : Array

*reduce()

Reduces the Collection to a value by calling the reducer for every entry in the Collection and passing along the reduced value.

reduce<R>(
reducer: (reduction: R, value: T, key: number, iter: this) => R,
initialReduction: R,
context?: any
): R
reduce<R>(
reducer: (reduction: T | R, value: T, key: number, iter: this) => R
): R

*toJS()

Deeply converts this Indexed collection to equivalent native JavaScript Array.

toJS(): Array<any>

*unshift()

Returns a new List with the provided values prepended, shifting other values ahead to higher indices.

unshift(...values: Array<T>): List<T>

*update()

Returns a new List with an updated value at index with the return value of calling updater with the existing value, or notSetValue if index was not set. If called with a single argument, updater is called with the List itself.

update(index: number, notSetValue: T, updater: (value: T) => T): this
update(index: number, updater: (value: T) => T): this
update<R>(updater: (value: this) => R): R

*updateIn()

Returns a new Map having applied the updater to the entry found at the keyPath.

updateIn(
keyPath: Iterable<array>,
notSetValue: any,
updater: (value: any) => any
): this
updateIn(keyPath: Iterable<array>, updater: (value: any) => any): this

*withMutations()

Every time you call one of the above functions, a new immutable List is created. If a pure function calls a number of these to produce a final return value, then a penalty on performance and memory has been paid by creating all of the intermediate immutable Lists.

withMutations(mutator: (mutable: this) => any): this