collectable

High performance immutable data structures. Functional interfaces, TypeScript definitions, ES2015 modules as standard.

Collectable.js: Immutable Data Structures

An all-you-can-eat buffet of high-performance, persistent, immutable, functional data structures. Collect them all!

Build Status NPM version Gitter

Note: This library is an active work in progress. Some of the features and structures mentioned below are currently in development, or only partially-available, prior to the first full 1.0 release. See the project board for information on current development status.

Features

  • 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
  • Optional pre-curried variant of every API function
  • Optional immutable class wrappers for those who prefer a class-based approach at the cost of tree-shaking benefits
  • 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

Data Structures

Secondary Structures

These structures are less common in application code and usually used as building blocks for other algorithms and data structures:

  • [ Red Black Tree ] A persistent red-black tree, providing a balanced binary search tree which maps keys to values.
  • [ Cuckoo Filter ] A persistent cuckoo filter, used for efficient determination of probable set membership.

See the road map for information on further development and plans for additional features and data structures.

Installation

# via NPM
npm install --save collectable

# or Yarn
yarn add collectable

TypeScript type definitions are included by default.

Usage

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);

Pre-curried versions of functions for a given data structure are available by appending /curried to the import path, like so:

import {fromArray, append} from '@collectable/list/curried';

const two = fromArray(['X', 'Y']); // => [X, Y]
const addZ = append('Z');
const three = addZ(two); // => [X, Y, Z]

To combine multiple data structures effectively, import universal methods from the main package and collection-specific methods from other relevant packages as needed:

import {from, updateIn, setIn} from 'collectable';
import {append} from '@collectable/list/curried';

const input = {
  foo: 'abc',
  xyz: [3, [5, 6], 7, 9]
};
const map0 = from(input); // <{foo: 'abc', xyz: <[3, [5, 6], 7, 9]>}>
const map1 = updateIn(['xyz', 1, 0], n => 4, map0); // <{foo: 'abc', xyz: <[3, [4, 6], 7, 9]>}>
const map2 = setIn(['foo', 'bar'], x => 'baz', map1); // <{foo: <{bar: 'baz'}>, xyz: ...>
const map3 = updateIn(['xyz', 1], 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.

Contributor Credits (Deliberate or Unwitting)

Want to help out? See the guide for contributors.

Related Repositories

collectable

collectable

High performance immutable data structures. Functional interfaces, TypeScript definitions, ES2015 modules as standard. ...

ets_map

ets_map

An Elixir package that provides a Map-like interface (Map/Access/Enumerable/Collectable) backed by an ETS table ...

collectable

collectable

Make PORO models work with collection_check_boxes ...