README.md

Immutable Records, Vectors, Maps and Sets for ECMAScript

Immutability and referential transparency has many known benefits and ability for optimization. Several modern JavaScript libraries take advantage of this, and many more functional compile-to-JS languages.

This is based upon the Value Types proposal (Typed Objects / Explainer).

All these types provide value equality for both == and ===.

Record

Records are a new value type that represents the value type analogy of an immutable object.

const xy = #{ x: 1, y: 2 }; // frozen value type
const xyz = #{ ...xy, z: 3 }; // functional extension

Immutable Vector

ImmutableVector is a new value type that represents the value type analogy of an immutable array, without holes. It cannot be sparse.

const xy = #[ x, y ]; // frozen value type
const xyz = #[ ...xy, z ]; // functional extension

Immutable Map

ImmutableMap is an immutable version of Map. Any mutable operation returns a new ImmutableMap instead of mutating the existing reference.

const a = ImmutableMap([['x', 1], ['y', 2]]);
const b = a.set('y', 3);
a.get('y'); // 2
b.get('y'); // 3

Immutable Set

ImmutableSet is an immutable version of Set. Any mutable operation returns a new ImmutableSet instead of mutating the existing reference.

const a = ImmutableSet([1, 2]);
const b = a.add(3);
a.size; // 2
b.size; // 3

Status of this Proposal

This was presented to TC39 in 2015 but the value of having it in the engine is still unproven and this is a large implementation burden for VMs. It effectively doubles the existing data structures. Therefore, we need to gather more arguments for why it needs to be included in the language and how it would be used.

Known Issues

See why this matters.