An all-you-can-eat buffet of high-performance, persistent, immutable, functional data structures. Collect them all!
Note: This library is an active work in progress. Some of the features and structures mentioned below are currently in progress, pending development, only partially-available, or flagged for cleanup/refactoring, prior to the first full 1.0 release. See the project board for information on current development status. That all said, the library is very much usable, even at this early stage.
- A robust suite of high-performance data structures for most use cases
- Full ES2015 module support so that your application bundle only need grow in size according to what you actually use
- Functional API, prioritising an order of parameters best suited for currying and composition
- API for deep operations on nested structures
- Deep and shallow conversion to and from native types, including arrays, objects, iterables, Maps and Sets
- Complete set of TypeScript definitions
- Extensive documentation and examples
- One package import to access everything, or isolated npm packages for each individual data structure
- Comprehensive unit test suite, consisting of hundreds of tests for every data structure
- Strong focus on a code style that emphasises high performance internally
- [ List ] A persistent list/vector structure based on a modified RRB Tree implementation.
- [ Map ] A persistent hash map, mapping keys to values. Implemented as a Clojure-style hash array mapped trie.
- [ Sorted Map ] A persistent sorted map backed by a red-black tree and a hash map with user-definable sort order.
- [ Set ] A persistent set, backed by a hash map.
- [ Sorted Set ] A persistent sorted set backed by a red-black tree and a hash map, with user-definable sort order.
- [ Red Black Tree ] A persistent red-black tree, providing a balanced binary search tree which maps keys to values.
See the road map for information on further development and plans for additional features and data structures.
# via NPM
npm install --save collectable
# or Yarn
yarn add collectableTypeScript type definitions are included by default.
API Reference: [ General | List | Map | Sorted Map | Set | Sorted Set | Red Black Tree | Others... ]
Individual data structures are pulled in automatically as dependencies of the main package. By having your project take a dependency on collectable itself, all data structures are made available implicitly as scoped imports, and operations on deeply-nested data structures are available via the main package.
For example, to use an immutable list:
import {fromArray, unwrap} from '@collectable/list';
const list = fromArray(['X', 'Y']);
const array = unwrap(list);To combine multiple data structures effectively, import universal methods from the main package and collection-specific methods from other relevant packages as needed:
import * as C from 'collectable';
import * as List from '@collectable/list';
import {curry2} from '@typed/list';
const input = {
foo: 'abc',
xyz: [3, [5, 6], 7, 9]
};
const map0 = C.from(input); // <{foo: 'abc', xyz: <[3, [5, 6], 7, 9]>}>
const map1 = C.updateIn(['xyz', 1, 0], n => 4, map0); // <{foo: 'abc', xyz: <[3, [4, 6], 7, 9]>}>
const map2 = C.setIn(['foo', 'bar'], x => 'baz', map1); // <{foo: <{bar: 'baz'}>, xyz: ...>
const map3 = C.updateIn(['xyz', 1], curry2(List.append)(42)); // <{..., xyz: <[3, [5, 6, 42], 7, 9]>}>Use a modern bundler such as Webpack 2 or Rollup in order to take advantage of tree shaking capabilities, giving you maximum flexbility to take the whole package as a dependency while excluding anything you don't use from the final build.
- Map implementation adapted from Tylor Steinberger's TypeScript conversion of Matt Bierner's HAMT implementation.
Want to help out? See the guide for contributors.