@nkp/array-map

@nkp/array-map

ArrayMap holds key-array with arrays of the given value types.

Table of contents

• Installation
  • npm
  • yarn
  • Exports
• Usage
  • ArrayMap.Uniq
  • ArrayMap.arrayEntries
  • ArrayMap.arrayEntriesPolyfill
  • ArrayMap.mapEntries
  • ArrayMap.mapEntriesPolyfill
  • ArrayMap.calculateIndex
  • ArrayMap.at
  • ArrayMap.cloneEntries
  • ArrayMap.cloneMap
  • ArrayMap.groupBy
  • ArrayMap.fromMap
  • ArrayMap.fromMapRef
  • ArrayMap.fromTuples
  • ArrayMap.fromEntries
  • ArrayMap.fromEntriesByRef
  • ArrayMap.new
  • ArrayMap.prototype.size
  • ArrayMap.prototype.clone
  • ArrayMap.prototype.has
  • ArrayMap.prototype.hasAt
  • ArrayMap.prototype.get
  • ArrayMap.prototype.getAt
  • ArrayMap.prototype.set
  • ArrayMap.prototype.setAt
  • ArrayMap.prototype.delete
  • ArrayMap.prototype.clear
  • ArrayMap.prototype.vacuum
  • ArrayMap.prototype.length
  • ArrayMap.prototype.pop
  • ArrayMap.prototype.push
  • ArrayMap.prototype.concat
  • ArrayMap.prototype.reverseKeys
  • ArrayMap.prototype.reverseValues
  • ArrayMap.prototype.shift
  • ArrayMap.prototype.unshift
  • ArrayMap.prototype.indexOf
  • ArrayMap.prototype.lastIndexOf
  • ArrayMap.prototype.everyEntry
  • ArrayMap.prototype.everyTuple
  • ArrayMap.prototype.everyValue
  • ArrayMap.prototype.everyKey
  • ArrayMap.prototype.someEntry
  • ArrayMap.prototype.someTuple
  • ArrayMap.prototype.someValue
  • ArrayMap.prototype.someKey
  • ArrayMap.prototype.mapEntries
  • ArrayMap.prototype.mapTuples
  • ArrayMap.prototype.mapValues
  • ArrayMap.prototype.mapKeys
  • ArrayMap.prototype.filterEntries
  • ArrayMap.prototype.filterTuples
  • ArrayMap.prototype.filterValues
  • ArrayMap.prototype.filterKeys
  • ArrayMap.prototype.sortValues
  • ArrayMap.prototype.sortKeys
  • ArrayMap.prototype.entries
  • ArrayMap.prototype.tuples
  • ArrayMap.prototype.keys
  • ArrayMap.prototype.arrays
  • ArrayMap.prototype.values
  • ArrayMap.prototype.toEntries
  • ArrayMap.prototype.toTuples
  • ArrayMap.prototype.toKeys
  • ArrayMap.prototype.toArrays
  • ArrayMap.prototype.toValues
  • ArrayMap.prototype.toMap
  • ArrayMap.prototype.getMapRef

Installation

NPM

npm install @nkp/array-map

Yarn

yarn add @nkp/array-map

Exports

@nkp/array-map targets CommonJS and ES modules. To utilise ES modules consider using a bundler like webpack or rollup.

Usage

ArrayMap.Uniq

Returns a unique array clone of the given array.

// interface

function static uniq<T>(array: T[]): T[];

// usage

import { ArrayMap } from '@nkp/array-map';

// [1, 2, 3]
ArrayMap.uniq([1, 1, 2, 3]);

ArrayMap.getArrayEntries

Get an iterator for the array's entries.

Uses Array.prototype.entries if it exists.

Otherwise uses ArrayMap.getArrayEntriesPolyfill.

// interface 

function getArrayEntries<T>(array: T[]): IterableIterator<[number, T]>;

// usage

import { ArrayMap } from '@nkp/array-map';

// [[1, 'a'], [2, 'b'], [3, 'c']]
ArrayMap.getArrayEntries(['a', 'b', 'c']); 

ArrayMap.getArrayEntriesPolyfill

Polyfill for Array.prototype.entries in-case Array.prototype.entries does not exist.

// interface

function getArrayEntriesPolyfill<T>(array: T[]): IterableIterator<[number, T]>;

// usage

import { ArrayMap } from '@nkp/array-map';

// [[1, 'a'], [2, 'b'], [3, 'c']]
ArrayMap.getArrayEntriesPolyfill(['a', 'b', 'c']); 

ArrayMap.getMapEntries

Get an iterator for the map's entries.

Uses Map.prototype.entries if it exists.

Otherwise uses ArrayMap.getMapEntriesPolyfill.

// interface

function getMapEntries<K, V>(map: Map<K, V>): IterableIterator<[K, V]>;

// usage

import { ArrayMap } from '@nkp/array-map';

// [[1, 'a'], [2, 'b'], [3, 'c']]
ArrayMap.getMapEntries(['a', 'b', 'c']); 

ArrayMap.getMapEntriesPolyfill

Polyfill for Map.prototype.entries in-case Map.prototype.entries does not exist.

// interface

function getMapEntriesPolyfill<T>(array: T[]): IterableIterator<[number, T]>;

// usage

import { ArrayMap } from '@nkp/array-map';

// [[1, 'a'], [2, 'b'], [3, 'c']]
ArrayMap.getMapEntriesPolyfill(['a', 'b', 'c']); 

ArrayMap.calculateIndex

Calculate the real index for a possibly negative index value.

// interface

function calculateIndex(length: number, index: number): number;

// example

import { ArrayMap } from '@nkp/array-map';

const array = [0, 1, 2];

// positive indexing
array[ArrayMap.calculateIndex(array.length, 0)] // 0
array[ArrayMap.calculateIndex(array.length, 1)] // 1
array[ArrayMap.calculateIndex(array.length, 2)] // 2

// negative indexing
array[ArrayMap.calculateIndex(array.length, -1)] // 2
array[ArrayMap.calculateIndex(array.length, -2)] // 1
array[ArrayMap.calculateIndex(array.length, -3)] // 0

ArrayMap.at

Get the element at the array's index.

Supports negative indexing.

// interface

function at<T>(array: T[], index: number): undefined | T;

// example

import { ArrayMap } from '@nkp/array-map';

const array = [0, 1, 2];

// positive indexing
ArrayMap.at(array, 0); // 0
ArrayMap.at(array, 1); // 1
ArrayMap.at(array, 2); // 2

// negative indexing
ArrayMap.at(array, -1); // 2
ArrayMap.at(array, -2); // 1
ArrayMap.at(array, -3); // 0

ArrayMap.cloneEntries

Clone an array of arrays whose first element is a key and second element is an array of values.

Clones the outer and inner arrays. Does not clone the inner array's elements.

// interface

function cloneEntries<K, V>(ref: [K, V[]][]): [K, V[]][];

// example

import { ArrayMap } from '@nkp/array-map';

// [['a', [1, 2, 3]], ['b', [2, 3]], ['c', [3]]]
const entries: [string, number[]][] = [
  ['a', [1, 2, 3],],
  ['b', [2, 3],],
  ['c', [3],],
];

// [['a', [1, 2, 3]], ['b', [2, 3]], ['c', [3]]]
const cloned = ArrayMap.cloneEntries(entries);

entries !== cloned        // true
entries[0] !== cloned[0]  // true
entries[1] !== cloned[1]  // true
entries[2] !== cloned[2]  // true

ArrayMap.cloneMap

Clone a map of arrays whose first element is a key and second element is an array of values.

Clones the outer and inner arrays. Does not clone the inner array's elements.

// interface

function cloneMap<K, V>(ref: Map<K, V[]>): Map<K, V[]>;

// example

import { ArrayMap } from '@nkp/array-map';

// Map([['a' => [1, 2, 3]], ['b' => [2, 3]], ['c' => [3]]])
const entries: Map<string, number[]> = new Map([
  ['a', [1, 2, 3],],
  ['b', [2, 3],],
  ['c', [3],],
]);

// Map([['a' => [1, 2, 3]], ['b' => [2, 3]], ['c' => [3]]])
const cloned = ArrayMap.cloneMap(entries);

entries !== cloned                    // true
entries.get('a') !== cloned.get('a')  // true
entries.get('b') !== cloned.get('b')  // true
entries.get('c') !== cloned.get('c')  // true

ArrayMap.groupBy

Create a new ArrayMap by grouping an array of values by a key or calculated value.

// interface
function groupBy<K extends keyof V, V>(array: V[], by: K): ArrayMap<V[K], V>;
function groupBy<K, V>(array: V[], by: (value: V) => K): ArrayMap<K, V>;

// example

import { ArrayMap } from '@nkp/array-map';

const objects = [
  { score: 1, name: 'Nick', },
  { score: 1, name: 'John', },
  { score: 2, name: 'James', },
  { score: 3, name: 'Oliver', },
  { score: 3, name: 'Rudolph', },
  { score: 4, name: 'Steve', },
  { score: 6, name: 'Irene', },
  { score: 6, name: 'Lisa', },
  { score: 7, name: 'Brian', },
  { score: 8, name: 'Furball', },
]

// ArrayMap([
//   1 => ['Nick', 'John'],
//   2 => ['James'],
//   3 => ['Oliver', Rudolph'],
//   4 => ['Steve'],
//   6 => ['Irene', 'Lisa'],
//   7 => ['Brian'],
//   8 => ['Furball'],
// ])
const group = ArrayMap.groupBy(objects, 'score');

// ArrayMap([
//   0 => ['Nick', 'John'],
//   2 => ['James', 'Oliver', 'Rudolph'],
//   4 => ['Steve'],
//   6 => ['Irene', 'Lisa', 'Brian'],
//   8 => ['Furball'],
// ])
const buckets = ArrayMap.groupBy(objects, (score) => score - (score % 2));

ArrayMap.fromMap

Create a new ArrayMap from a Map of arrays.

Clones the map and its array values.

// interface

function fromMap<K, V>(map: Map<K, V[]>): ArrayMap<K, V>;

// example

import { ArrayMap } from '@nkp/array-map';

const map = Map<number, string[]>([
  [0, ['Nick', 'John'],],
  [2, ['James', 'Oliver', 'Rudolph'],],
  [4, ['Steve'],],
  [6, ['Irene', 'Lisa', 'Brian'],],
  [8, ['Furball'],],
  [10, [],],
]);

const group: ArrayGroup<number, string[]> = ArrayMap.fromMap(map);

ArrayMap.fromMapRef

Create a new ArrayMap from a Map of arrays.

References the given map and its array values.

// interface

function fromMapByRef<K, V>(map: Map<K, V[]>): ArrayMap<K, V>;

// example

import { ArrayMap } from '@nkp/array-map';

const map = Map<number, string[]>([
  [0, ['Nick', 'John'],],
  [2, ['James', 'Oliver', 'Rudolph'],],
  [4, ['Steve'],],
  [6, ['Irene', 'Lisa', 'Brian'],],
  [8, ['Furball'],],
  [10, [],],
]);

const group: ArrayGroup<number, string[]> = ArrayMap.fromMapByRef(map);

ArrayMap.fromTuples

Create an ArrayMap from an array of key value arrays.

Groups together like keys and concatenates values.

// interface

function fromTuples<K, V>(array: [K, V][]): ArrayMap<K, V>;

// example

import { ArrayMap } from '@nkp/array-map';

const tuples: [string, number] = [['a', 1], ['a', 2], ['b', 3]];
//  ArrayMap(
//    'a' => [1, 2],
//    'b' => [3],
//  )
const group: ArrayMap<string, number> = ArrayMap.fromTuples(tuples);

ArrayMap.fromEntries

Create an ArrayMap from an array key-value-arrays.

Groups together like keys and concatenates their values.

Clones the array values in the process.

// interface

function fromEntries<K, V>(entries: [K, V[]][]): ArrayMap<K, V>;

// example

import { ArrayMap } from '@nkp/array-map';

const entries: [string, number[]] = [['a', [1, 2]], ['a', [3]], ['b', 4]];

//  ArrayMap(
//    'a' => [1, 2, 3],
//    'b' => [4],
//  )
const group: ArrayMap<string, number> = ArrayMap.fromEntries(entries);

ArrayMap.fromEntriesByRef

Create an ArrayMap from an array key-value-arrays.

Groups together like keys and concatenates their values.

Keeps reference to the original array values.

// interface

function fromEntriesByRef<K, V>(entries: [K, V[]][]): ArrayMap<K, V>;

// example

import { ArrayMap } from '@nkp/array-map';

const entries: [string, number[]] = [['a', [1, 2]], ['a', [3]], ['b', 4]];

//  ArrayMap(
//    'a' => [1, 2, 3],
//    'b' => [4],
//  )
const group: ArrayMap<string, number> = ArrayMap.fromEntries(entries);

ArrayMap.new

// interface

// example

ArrayMap.prototype.size

// interface

// example

ArrayMap.prototype.clone

// interface

// example

ArrayMap.prototype.has

// interface

// example

ArrayMap.prototype.hasAt

// interface

// example

ArrayMap.prototype.get

// interface

// example

ArrayMap.prototype.getAt

// interface

// example

ArrayMap.prototype.set

// interface

// example

ArrayMap.prototype.setAt

// interface

// example

ArrayMap.prototype.delete

// interface

// example

ArrayMap.prototype.clear

// interface

// example

ArrayMap.prototype.vacuum

// interface

// example

ArrayMap.prototype.length

// interface

// example

ArrayMap.prototype.pop

// interface

// example

ArrayMap.prototype.push

// interface

// example

ArrayMap.prototype.concat

// interface

// example

ArrayMap.prototype.reverseKeys

// interface

// example

ArrayMap.prototype.reverseValues

// interface

// example

ArrayMap.prototype.shift

// interface

// example

ArrayMap.prototype.unshift

// interface

// example

ArrayMap.prototype.indexOf

// interface

// example

ArrayMap.prototype.lastIndexOf

// interface

// example

ArrayMap.prototype.everyEntry

// interface

// example

ArrayMap.prototype.everyTuple

// interface

// example

ArrayMap.prototype.everyValue

// interface

// example

ArrayMap.prototype.everyKey

// interface

// example

ArrayMap.prototype.someEntry

// interface

// example

ArrayMap.prototype.someTuple

// interface

// example

ArrayMap.prototype.someValue

// interface

// example

ArrayMap.prototype.someKey

// interface

// example

ArrayMap.prototype.mapEntries

// interface

// example

ArrayMap.prototype.mapTuples

// interface

// example

ArrayMap.prototype.mapValues

// interface

// example

ArrayMap.prototype.mapKeys

// interface

// example

ArrayMap.prototype.filterEntries

// interface

// example

ArrayMap.prototype.filterTuples

// interface

// example

ArrayMap.prototype.filterValues

// interface

// example

ArrayMap.prototype.filterKeys

// interface

// example

ArrayMap.prototype.sortValues

// interface

// example

ArrayMap.prototype.sortKeys

// interface

// example

ArrayMap.prototype.entries

// interface

// example

ArrayMap.prototype.tuples

// interface

// example

ArrayMap.prototype.keys

// interface

// example

ArrayMap.prototype.arrays

// interface

// example

ArrayMap.prototype.values

// interface

// example

ArrayMap.prototype.toEntries

// interface

// example

ArrayMap.prototype.toTuples

// interface

// example

ArrayMap.prototype.toKeys

// interface

// example

ArrayMap.prototype.toArrays

// interface

// example

ArrayMap.prototype.toValues

// interface

// example

ArrayMap.prototype.toMap

// interface

// example

ArrayMap.prototype.getMapRef

// interface

// example

Publishing

To a release a new version:

• Update the version number in package.json
• Push the new version to the master branch on GitHub
• Create a new release on GitHub for the latest version

This will trigger a GitHub action that tests and publishes the npm package.