Immutable Collections

Zero dependency library for immutable collections in typescript.

Features

• An immutable hash-based map with fast constant time operations (as long as there are no collisions).
• An immutable balanced binary tree with guaranteed log n operations.
• Two equivalent APIs:
  • A class-based API with classes for HashMap and OrderedMap.
  • A function API with better tree-shaking and bundle size for the hash array mapped trie and balanced tree.
• Efficient bulk operations for modifying many keys at once in a single change.
• Support for shallow comparision to determine if a data structure actually changed.
• An iterable wrapper for lazy data manipulation.

Install

Install with npm/yarn/pnpm from the npm registry.

Use

To use the class-based API, import from the @seedtactics/immutable-collections module directly. See the comparison docs to decide between a HashMap or an OrderedMap.

import { HashMap, OrderedMap } from "@seedtactics/immutable-collections";

For smaller bundler size but slightly less ergonomic to use, import the hamt or tree submodules. See the bundle size docs for full details comparing the two APIs. You should only use either the class based API or the function API; they export equivalent functionality.

import * as HAMT from "@seedtactics/immutable-collections/hamt";
import * as tree from "@seedtactics/immutable-collections/tree";

Lists

This library does not implement an immutable list. The funkia/list library already contains a high-quality immutable list which can be used in conjunction with the immutable maps in this library. An alternative is to use an OrderedMap as a kind of sequence by using a number key. This works well for sorted lists by using the sort as the key. Then, whenever you iterate the values in the OrderedMap, the values will be in ascending order of keys. The OrderedMap also has functions to view, modify, or pop the entry with the largest or smallest key, allowing list operations at the ends of the list.