⚠ THIS PROJECT IS STILL IN DEVELOPMENT. WHILE IT'S DESIGNED AS A LIBRARY IT IS NOT RELEASED YET AND THERE'S NO GUARANTEE THAT IT WILL BE IN THE FUTURE. ALSO, IMPLEMENTATION STYLE AND DETAILS MAY STILL CHANGE.

collections-commons

Extensions, data structures, and utilities built on top of them, for your every-day needs.

Installation

npm install collections-commons

Some classes extend Map, which requires the browser to support es6 features.

What's in this library?

This library main goal is to provide a toolbox for your every-day needs. As such it provides a lot of different extensions to the data structures you already know and use like Maps and Arrays. Beyond that, there a few custom data structures like Queue or Bag, and also utilities like lazy or lateInit that built on top of these structures.

It is strongly recommended to enable strict TypeScript rules, especially null checks. For example getOrElse, getOrDefault, and getOrThrow will make your life easier by explicitly handling missing keys in Maps, instead of (not) doing undefined checks.

Highlights

The following categories should give you a sense of what the library has to offer:

• Map factories like associateWith and groupBy
• Get from Map extensions like getOrDefault
• Lazy behaviours
• Common data structures like Bag, Queue, or LateInit

Usage

import { getOrThrow, getInBounds } from 'collections-commons';

const map = new Map<number, string>();
const value: string = getOrThrow(map, 5); // throws because map has no value for 5

const array = ['0', '1', '2'];
const item: string = getInBounds(array, 5); // throws because index 5 is out of bounds

Namespacing

If you prefer, you can create namespaces by using the import * as identifier syntax, which is still tree-shakable by all modern bundlers.

import * as Extensions from 'collections-commons/extensions';

// values are arrays, so this is considered a multi-value Map (no need for extra classes)
const map = new Map<string, number[]>([
  ['a', [0, 1, 2]],
  ['b', []],
]);
Extensions.addAll(map, 'a', [3, 4]); // addAll is an extension for multi-value Maps
Extensions.setAll(map, [ // setAll works for any Map
  ['b', [5, 6]],
  ['c', [7, 8]],
]);
expect(map.get('a')).toEqual([0, 1, 2, 3, 4]);
expect(map.get('b')).toEqual([5, 6]);
expect(map.get('c')).toEqual([7, 8]);