API

This page is still being written so watch out!

WATCH OUT!!!

Imports

All functions can be imported from unmutable/<functionName>

import getIn from 'unmutable/getIn';
import map from 'unmutable/map';
import filter from 'unmutable/filter';

Functions

Persistent changes

set()

set(key: string|number, value: any) => (collection) => newCollection

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

When used with an indexed data type, key may be a negative number, which indexes back from the end of the collection.

If index larger than size, the returned collections's size will be large enough to include the index.

Description from Immutable.js' docs.

'// Error: Unmutable is not defined'
'// Error: Unmutable is not defined'
'// Error: Unmutable is not defined'

delete()

delete(key: string|number) => (collection) => newCollection

Returns a new collection which excludes this key.

When used with an indexed data type, this returns a new collection which excludes this index and with a size 1 less than this collection. Values at indices above index are shifted down by 1 to fill the position.

Description from Immutable.js' docs.

'// Error: Unmutable is not defined'
'// Error: Unmutable is not defined'
'// Error: Unmutable is not defined'

Aliases: remove

deleteAll()

deleteAll(key) => (collection) => newCollection

Returns a new collection which excludes the provided keys.

Description from Immutable.js' docs.

'// Error: Unmutable is not defined'

Aliases: omit

pick()

pick(keys: string[]|number[]) => (collection) => newCollection

Returns a new collection which excludes all keys that aren't listed in keys.

'// Error: Unmutable is not defined'

insert()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

clear()

clear() => (collection) => newCollection

Returns a new collection containing no keys or values.

Description from Immutable.js' docs.

'// Error: Unmutable is not defined'
'// Error: Unmutable is not defined'

push()

push(...values: Array<any>) => (collection) => newCollection

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

Description from Immutable.js' docs.

'// Error: Unmutable is not defined'

pop()

pop() => (collection) => newCollection

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

Description from Immutable.js' docs.

'// Error: Unmutable is not defined'

unshift()

unshift(...values: Array<any>) => (collection) => newCollection

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

Description from Immutable.js' docs.

'// Error: Unmutable is not defined'

shift()

shift() => (collection) => newCollection

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

Description from Immutable.js' docs.

'// Error: Unmutable is not defined'

move()

move(fromIndex: number, toIndex: number) => (collection) => newCollection

Moves the element at fromIndex to the position of toIndex.

update()

update(key: string|number, notSetValue: any, updater: (value: any) => any) => (collection) => newCollection
update(key: string|number, updater: (value: any) => any) => (collection) => newCollection
update(updater: (collection: any) => any) => (collection) => newCollection

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

Description from Immutable.js' docs.

updateInto()

updateInto(key: string|number, updater: (collection) => newValue) => (collection) => newCollection

Passes collection to updater, and will set collection[key] to the result of the updater. In practise it works a bit like update(key, updater), but in this case updater receives collection instead of collection[key].

merge()

merge(...otherCollections: Array<Collection>) => (collection) => newCollection

Returns a new collection resulting from merging the provided otherCollections into this collection. In other words, this takes each entry of each otherCollection and sets it on this collection.

Description from Immutable.js' docs.

Aliases: concat

mergeWith()

mergeWith(
    merger: (oldValue: any, newValue: any, key: string) => value,
    ...otherCollections: Array<Collection>) => (collection) => newCollection
)

Like merge(), mergeWith() returns a new collection resulting from merging the provided otherCollections into this collection, but uses the merger function for dealing with conflicts.

Description from Immutable.js' docs.

mergeDeep()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

mergeDeepWith()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

defaults()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

setSize()

setSize(size: number) => (collection) => newCollection

Returns a new collection with size size. If size is less than this collection's size, the new collection will exclude values at the higher indices. If size is greater than this collection's size, the new collection will have undefined values for the newly available indices.

Description from Immutable.js' docs.

rename()

rename(oldKey: string|number, newKey: string|number) => (collection) => newCollection

Changes the key of oldKey to the key of newKey

swap()

swap(keyA: string|number, keyB: string|number) => (collection) => newCollection

Swaps the values at the given keys. Keys that don't exist are assumed to have a value of undefined.

rotate()

rotate(shift: number) => (collection) => newCollection

Rotates the elements in arrays and Lists around, according to the value of shift. A positive shift will move elements to the left, appending rotated elements to the end of the array, where as a negative shift will move elements to the right, prepending rotated elements to the start of the array.

unit()

unit(otherCollection) => (collection) => newCollection

Attempts to turn otherCollection into collections data type, and returns newCollection.

Deep persistent changes

setIn()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

deleteIn()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

updateIn()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

mergeIn()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

mergeDeepIn()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

Sequence algorithms

concat()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

map()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

flatMap()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

filter()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

zip()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

zipAll()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

zipWith()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

filterNot()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

reverse()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

sort()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

sortBy()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

groupBy()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

chunk()

chunk(size: number) => (collection) => newCollection

Returns an array of 'chunks'. This function splits collection up into chunks, where each chunk is of the same type as collection, and contains size number of values.

chunkBy()

chunkBy(predicate: Function) => (collection) => newCollection

Returns an array of 'chunks'. This function splits collection up into chunks, where the size of each chunk is determined by the predicate. It iterates over collection and calls predicate for each item on the collection. Whenever predicate returns true, a new chunk is started. It returns an array containing all the chunks that were created.

deal()

deal(groups: number) => (collection) => newCollection

Returns an array of 'chunks'. This function iterates over collection, dividing it into the number of groups specified by the groups argument. It works in a similar way to someone dealing out cards to a number of players, putting the first item in the first group, the second item in the second group etc. Once the last group is reached, the next item is put in the first group again, and the deal continues cyclically until no items are left.

keyBy()

keyBy(keyer: (value) => string) => (value) => {[key: string]: value} // Object

Iterates over collection and calls keyer on each item, and using the result as a key on the output object. TThe corresponding value of each key is the last element responsible for generating the key.

unique()

unique() => (collection) => newCollection

Filters collection so that any element with a duplicate value is filtered out. If the value is a collection it is compared deeply.

uniqueBy()

uniqueBy(getter: (collection) => any) => (collection) => newCollection

Filters collection according to the result of getter, so that any element with a duplicate result of getter is filtered out. If a collection is returned from getter, it is compared deeply.

Conversion to JavaScript types

toArray()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

toIndexed()

toIndexed() => (collection) => newCollection

Converts plain Javascript data types into arrays, and converts Immutable.js objects into Lists

toJS()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

toJSON()

toJSON() => (collection) => any

Turns the collection into plain Javascript if it is an Immutable.js data type. Internally if collection is a List then .toArray() is called, and if collection is a Map then toObject() is called.

Aliases: shallowToJS

toKeyed()

toKeyed() => (collection) => newCollection

Converts plain Javascript data types into objects, and converts Immutable.js objects into Maps.

toObject()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

Reading values

get()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

has()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

includes()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

first()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

last()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

Combination

interpose()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

splice()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

flatten()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

pivot()

pivot() => (collection) => newCollection

Pivots the collection. The keys at the first level of nesting are moved to the second level, and the keys of the second level are moved to the first.

Search for value

indexOf()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

lastIndexOf()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

findIndex()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

findLastIndex()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

find()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

findEntry()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

findLast()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

findLastEntry()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

findKey()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

findLastKey()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

keyOf()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

lastKeyOf()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

max()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

maxBy()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

min()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

minBy()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

Value equality

equals()

`equals(otherValue) => (value) => boolean`

Returns true if value and otherValue are deeply equal, or false otherwise.

notEquals()

notEquals(otherValue) => (value) => boolean

Returns true if value and otherValue are not deeply equal, or false otherwise.

strictEquals()

strictEquals(otherCollection: *) => (collection) => number

Checks if collection and otherCollection are strictly equal. This complements equals(), which checks for deep value equality.

shallowEquals()

shallowEquals(otherCollection: *) => (collection) => number

Checks if collection and otherCollection are shallowly equal, using strict equality.

Use `equals()` if you want to check deep equality.

hashCode()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

Reading deep values

getIn()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

hasIn()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

Iterators

keys()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

values()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

entries()

entriesReverse() => (collection) => Iterator

Works just like entries(), but iterates in the reverse order.

entriesReverse()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

Iterator to array

keyArray()

keyArray() => (collection) => Array<key>

Returns an array of keys on the value. Immutable.js has no function that does this, they have keys() which returns an iterator, and keySeq() which returns an Immutable.js Seq.

valueArray()

valueArray() => (collection) => Array<any>

Returns an array of values on the collection. Immutable.js has no function that does this, they have values() which returns an iterator, and valueSeq() which returns an Immutable.js Seq.

entryArray()

entryArray() => (collection) => Array<[key, value]>

Returns an array of entries (e.g. [key, value] tuples) of the value. Immutable.js has no function that does this, they have entries() which returns an iterator, and entrySeq() which returns an Immutable.js Seq.

Side effects

forEach()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

Creating subsets

slice()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

rest()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

butLast()

butLast() => (collection) => newCollection

Returns a new collection of the same type containing all entries except the last.

'// Error: Unmutable is not defined'

skip()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

skipLast()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

skipUntil()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

skipWhile()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

take()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

takeLast()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

takeUntil()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

takeWhile()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

Reducing a value

reduce()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

reduceRight()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

every()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

some()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

join()

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

isEmpty()

isEmpty() => (collection) => boolean

Returns true when the collection is empty, such as an empty object or an array with no elements.

isNotEmpty()

isNotEmpty() => (collection) => boolean

Returns true when the collection is not empty.

count()

count() => (collection) => number

Returns the number of keys on the collection.

Aliases: size

size()

size() => (collection) => number

Returns the number of keys on the collection. Immutable.js has this as a getter on their collections, Unmutable.js offers this as a function.

Aliases: count

startsWith()

startsWith(otherCollection) => (collection) => boolean

Returns true when the collection starts with otherCollection. The elements of otherCollection are compared deeply with those in collection.

'// Error: Unmutable is not defined'

endsWith()

endsWith(otherCollection) => (collection) => boolean

Returns true when the collection starts with otherCollection. The elements of otherCollection are compared deeply with those in collection.

'// Error: Unmutable is not defined'

Cloning

clone()

clone() => (collection) => newCollection

Returns a clone of collection if collection is an array or object, or returns the collection unchanged if given an Immutable.js Map or List. Immutable.js data types are inherently immutable so do not need to be explicitly cloned.

replaceEqual()

replaceEqual(otherCollection) => (collection) => newCollection

If otherCollection is deeply equal to collection, otherCollection is returned, or else collection is returned.

This can be useful if you have a data source that always recreates a data structure, such as JSON.parse(), but you want to avoid needlessly passing new instances of unchanged objects and arrays downstream.

'// Error: Unmutable is not defined'

replaceEqualDeep()

replaceEqualDeep(otherCollection) => (collection) => newCollection

If otherCollection is deeply equal to collection, otherCollection is returned. If not, each of collections children are compared against otherCollection, and if they are deeply equal then that part of otherCollection is inserted into the result. This process continues recursively down the data structure.

This can be useful if you have a data source that always recreates a data structure, such as JSON.parse(), but you want to avoid needlessly passing new instances of unchanged objects and arrays downstream.

'// Error: Unmutable is not defined'

Debugging

log()

log(message: string = '', type: string = 'log') => (value) => value

Returns an evaluator that passes the value through unchanged, but also calls console[type](message, value). Useful for debugging.

Utils

Composition

compose()

compose(...functions: Array<Function>) => (value) => newValue

Composes (combines) functions together from right to left. Returns a function that's ready to accept a value and run it through all the functions in the pipe.

composeWith()

composeWith(value, ...functions: Array<Function>) => (value) => newValue

Accepts an value as the first argument, and composes (combines) functions in the remaining arguments together from right to left.

`composeWith(value, ...functions) is equivalent to compose(...functions)(value)`

pipe()

pipe(...functions: Array<Function>) => (value) => newValue

Composes (combines) functions together from left to right. Returns a function that's ready to accept a value and run it through all the functions in the pipe.

pipeIf()

pipeIf(condition: (value) => boolean, ...functions: Array<Function>) => (value) => newValue

Like pipe(), but the first argument is a conditional function that is passed the value. If a truthy value is returned from the conditional function, all functions in the pipe are executed. If a falsey value is returned, then the remaining functions in the pipe are skipped.

pipeWith()

pipeWith(value, ...functions: Array<Function>) => (value) => newValue

Accepts an value as the first argument, and composes (combines) functions in the remaining arguments together from left to right.

`pipeWith(value, ...functions) is equivalent to pipe(...functions)(value)`

identity()

identity() => (value) => value

A function that passes values through with no change. Useful for readable code.

Predicates

isAssociative()

isAssociative(value: any) => boolean

Works like Immutable.js isAssociative() but also identifies plain Javascript arrays and objects as being associative.

isCollection()

isCollection(value: any) => boolean

Works like Immutable.js isCollection() but also identifies plain Javascript arrays and objects as being collections.

Immutable.js' definition of 'collection' does *not* include Immutable.js Records.

isImmutable()

isImmutable(value: any) => boolean

Returns true if value is an Immutable.js data type, or false otherwise.

isIndexed()

isIndexed(value: any) => boolean

Works like Immutable.js isIndexed() but also identifies plain Javascript arrays as being indexed.

isKeyed()

isKeyed(value: any) => boolean

Works like Immutable.js isKeyed() but also identifies plain Javascript objects as being keyed.

isObject()

isObject(value: any) => boolean

Tests if something extends from object and is not primitive, which includes arrays, functions, class instances and all Immutable.js types, and does not include undefined, null, string, number, and boolean.

Aliases: isValueObject

isOrdered()

isOrdered(value: any) => boolean

Works like Immutable.js isOrdered() but also identifies plain Javascript arrays as being ordered.

isPlainObject()

isPlainObject(value: any) => boolean

Tests if the value is a plain object according to is-plain-object.

isRecord()

isRecord(value: any) => boolean

No docs here yet! Try checking Immutable.js' docs, if they have a matching function name then Unmutable's function will work the same way.

isValueObject()

isValueObject(value: any) => boolean

An alias for isObject() to align with Immutable.js naming convention.

Aliases: isObject

isWriteable()

isWriteable(value: any) => boolean

Tests if a data type can be used with unmutable functions that write or modify data. Returns true for any Immutable.js types, array and plain objects.

Method creation

method()

A helper function that allows you to turn any method into a point-free function.

'// Error: Unexpected token import'

overload()

overload({[arity: string]: Function})

Simulates function overloading in Javascript. Pass it an object with functions as values. The objects keys should be strings of numbers that indicate how many arguments each function expects to receive.

'// Error: Unexpected token import'

Conditionals

doIf()

doIf(
    predicate: (value) => boolean,
    ifTrue: (value) => newValue,
    ifFalse: (value) => newValue = ii => ii
) => (value) => newValue

Passes the value to the predicate function. If the predicate returns true, the value is then passed through the ifTrue function and the result is returned. If the predicate returns false then the value is simply returned unchanged.

If the third argument ifFalse is provided, then the value will be passed through ifFalse when the predicate returns false.

Dataset generation

range()

range([start = 0], end, [step = 1])

Helper function to generate an array of sequential numbers. Simply a re-export of lodash.range

To be implemented

  • countBy - will return an object rather than Seq.keyed for plain objects and arrays
  • flip
  • interleave *
  • isSubset
  • isSuperset
  • mapKeys
  • mapEntries

Exceptions

The following functions cannot be implemented in Unmutable.js.

  • Symbol.iterator
  • asMutable
  • asImmutable
  • entrySeq
  • fromEntrySeq
  • keySeq
  • toList
  • toMap
  • toIndexedSeq
  • toKeyedSeq
  • toOrderedMap
  • toOrderedSet
  • toSet
  • toSeq
  • toSetSeq
  • toStack
  • valueSeq
  • wasAltered
  • withMutations