https://github.com/janmalch/collections-commons
Extensions, data structures, and utilities built on top of them, for your every-day needs.
https://github.com/janmalch/collections-commons
collections javascript library typescript utils
Last synced: about 1 month ago
JSON representation
Extensions, data structures, and utilities built on top of them, for your every-day needs.
- Host: GitHub
- URL: https://github.com/janmalch/collections-commons
- Owner: JanMalch
- Created: 2021-12-22T09:49:46.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-03-16T09:30:03.000Z (about 1 year ago)
- Last Synced: 2024-03-16T11:06:34.678Z (about 1 year ago)
- Topics: collections, javascript, library, typescript, utils
- Language: TypeScript
- Homepage: https://janmalch.github.io/collections-commons/
- Size: 3.06 MB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
**⚠ 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 
[][npm-url]
[][docs-url]
[][bundlephobia-url]
[][build-url]
[][codecov-url]
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.
[](https://caniuse.com/es6)
## 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`](https://janmalch.github.io/collections-commons/modules/extensions_map.html#:~:text=Functions%20-%20Get)
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](https://janmalch.github.io/collections-commons/modules/extensions_iterable.html#:~:text=Functions%20%2D%20Lookup)
like [`associateWith`](https://janmalch.github.io/collections-commons/functions/extensions_iterable.associateWith.html) and
[`groupBy`](https://janmalch.github.io/collections-commons/functions/extensions_iterable.groupBy.html)
- [Get from Map extensions](https://janmalch.github.io/collections-commons/modules/extensions_map.html#:~:text=Functions%20-%20Get) like `getOrDefault`
- [Lazy behaviours](https://janmalch.github.io/collections-commons/modules/lazy.html)
- [Common data structures](https://janmalch.github.io/collections-commons/modules/data_structures.html) like Bag, Queue, or `LateInit`
## Usage
```typescript
import { getOrThrow, getInBounds } from 'collections-commons';
const map = new Map();
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.
```typescript
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([
['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]);
```
[docs-url]: https://janmalch.github.io/collections-commons/
[npm-url]: https://www.npmjs.com/package/collections-commons
[build-url]: https://github.com/JanMalch/collections-commons/actions?query=workflow%3ABuild
[codecov-url]: https://codecov.io/gh/JanMalch/collections-commons
[bundlephobia-url]: https://bundlephobia.com/result?p=collections-commons
[map-mdn-url]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map