JSDoc: Global

Methods

binMap(arr, keyFn)

Generate a Map that stores the keys of incoming values, as produced by ${keyFn}, and maps them to the full array of values that produced those keys.

For those familiar with SQL, this is functionally a "GROUP BY" query that groups values by combining them into arrays.

Parameters:

Name	Type	Description
`arr`	Iterable	The Iterable to map over.
`keyFn`		The function to generate keys with.

Source:

maps.js, line 316

canonizeByPick(_, pick)

Parameters:

Name	Type	Description
`_`		Example of what will be picked. If necessary, forcefully cast this to the type desired.
`pick`		An array of the key lookups to perform.

Source:

canon.js, line 199

Returns:

Canonizer that produces a canonical string by combining all specified key-value pairs together.

concatMap(…maps)

Combine Iterables of Map entries into a single Iterable, leaving keys unmerged.

Parameters:

Name	Type	Attributes	Description
`maps`		<repeatable>	The Map Iterables to merge

Source:

maps.js, line 49

Returns:

An Iterable consisting of all entries of the Iterables in the arguments, even those with duplicate keys.

consume(map, key)

Try to grab a value from a map, returning it wrapped in Some if present, and removing it from the map.

Parameters:

Name	Type	Description
`map`		The map to look up on
`key`		The key to look up

Source:

maps.js, line 616

Returns:

An fp-ts Option representing success on the lookup.

(generator) flatMakeEntries(arr, expandFn)

Convert an iterable of values into a sequence of Map entries, pairing each value with a series of keys as returned by ${expandFn}.

Where @{expandFn} returns no keys, the value will be ignored; where it returns multiple keys, an entry will be created for each key.

Parameters:

Name	Type	Description
`arr`	Iterable	The input iterable.
`expandFn`	function	The function that turns the input into a (possibly empty) list of entries.

Source:

maps.js, line 336

Returns:

An iterable of key-value tuples generated by appending together the output of expandFn when called on members of arr.

foldingGet(map, key, ifPresent, ifAbsent?)

Retrieve a value from the Map at the given key. If the value was retrieved, map it with ${ifPresent}; if not, return the result or calling ${ifAbsent}.

Parameters:

Name	Type	Description
`map`	Map	The map on which to perform the lookup.
`key`	T	The key to look up.
`ifPresent`	function	The function to call on the value and `key` if the value is present.
`ifAbsent?`	function	The function to call with `key` if the value is absent, by default a noop returning `undefined`.

Source:

maps.js, line 193

Returns:

the result of calling ifPresent on a value if that value is at key in map, the result of calling ifAbsent otherwise.

getOption(map, key)

Get an fp-ts Option representing the result of a map lookup.

Parameters:

Name	Type	Description
`map`		The map to search on
`key`		The key to look up

Source:

maps.js, line 599

Returns:

Some(value) if a value is present on the map at the key, None if not.

getOrElse(map, key, substitute)

Retrieve a value from the Map at the given key. If the key is not set, return an alternate value by calling ${substitute}.

Parameters:

Name	Type	Description
`map`	Map	The map on which to perform the lookup.
`key`	T	The key to look up.
`substitute`	function	The function to call on `key` if the value is not present.

Source:

maps.js, line 234

Returns:

the value at key in map if that value exists, the result of calling substitute otherwise.

getOrFail(map, key, error?)

Retrieve a value from the Map at the given key, throwing an error if the key was not set.

Parameters:

Name	Type	Description
`map`	Map	The map on which to perform the lookup.
`key`	T	The key to look up.
`error?`	string \| function	The error to generate if the key is not present. Can be a function taking the key as a parameter, or an explicit string.

Source:

maps.js, line 252

Throws:

The specified error if an error string or function is provided, a default error message if not.

Returns:

the value at key in map if that value exists, the result of calling substitute otherwise.

getOrFill(map, key, freshFn)

Retrieve a value from the Map at the given key. If the value does not exist, initialize a value at the specified key with freshFn, then return that value.

Parameters:

Name	Type	Description
`map`		The map on which to perform the lookup.
`key`		The key to look up.
`freshFn`		The function to call with the key to generate a fresh value.

Source:

maps.js, line 271

getOrVal(map, key, substitute)

Retrieve a value from the Map at the given key. If it is not present, return ${substitute} instead.

Parameters:

Name	Type	Description
`map`	Map	The map on which to perform the lookup.
`key`	T	The key to look up.
`substitute`	V	The value to return if the key is not present.

Source:

maps.js, line 175

Returns:

The value at the key in the map, or the substitute if that key is not present.

invertBinMap(map) → {Map}

Convert a map from keys to arrays of values (i.e., of the form Map<K, T[]>) to a map of values from arrays of keys (i.e., of the form Map<T, K[]>).

Parameters:

Name	Type	Description
`map`	Iterable	An Iterable representing a Map of entries where the values are arrays.

Source:

maps.js, line 536

Returns:

A Map containing, for each member value that appears in any of the arrays, an entry where the key is the value in the array and the value is a list of all the keys in the input Map that included it.

Type: Map

Example

const peopleToFlavours = new Map([
  ["Alex", ["vanilla"]],
  ["Desdemona", ["banana", "chocolate"],
  ["Henrietta", ["vanilla", "chocolate", "cherry"]
]);

const flavoursToPeople = new Map([
  ["vanilla", ["Alex", "Henrietta"]],
  ["banana", ["Desdemona"]],
  ["chocolate", ["Desdemona", "Henrietta"]],
  ["cherry", ["Henrietta"]]
]);

assert(deepEquals(
  Array.from(flavoursToPeople),
  Array.from(invertBinMap(peopleToFlavours))
));

invertMap(iterable)

Reverse a stream of entries so that entries of the form [key, value] are now in the form [value, key].

Any key collisions must be handled in later steps, or they will be reconciled automatically by later entries overriding earlier ones.

Parameters:

Name	Type	Description
`iterable`	Iterable	An iterable representing the entries of a Map from key to value.

Source:

maps.js, line 97

Returns:

An iterable representing the entries of a Map from value to key.

jsonCanonize(lookup)

Canonize using JSON.stringify().

Parameters:

Name	Type	Description
`lookup`	K	The key to canonize.

Source:

canon.js, line 60

Returns:

A stringified version of the lookup.

JsonCanonMap(entries?)

Create a CanonMap that canonizes using JSON.stringify.

Parameters:

Name	Type	Description
`entries?`		The entries with which to initialize the map. By default, creates an empty map.

Source:

canon.js, line 183

(generator) keyBy(arr, keyFn)

Produce an Iterable from a list of values and a function to produce a key for each value.

Does not check collisions; these can be handled at a later step.

Parameters:

Name	Type	Description
`arr`		The values to map.
`keyFn`		The function to generate keys.

Source:

maps.js, line 299

Returns:

An Iterable representing key-value pairs where the keys are generated by calling keyFn on the values.

keysOf(iterable)

Get an Iterable containing the keys of a Map or Map-like Iterable.

Parameters:

Name	Type	Description
`iterable`	Iterable	An iterable representing the entries of a Map from key to value.

Source:

maps.js, line 131

Returns:

An iterable representing the keys of the map.

makeEntries(arr, mapFn)

Convert an iterable of values into a list of Map entries with a mapping function.

Parameters:

Name	Type	Description
`arr`	Iterable	The input iterable.
`mapFn`	function	The function that turns inputs into entries.

Source:

maps.js, line 286

Returns:

An iterable of key-value tuples generated by the output of mapFn when called on members of arr.

mapCollect(iterable, reconcileFn?)

Convert an Iterable of Map entries into a brand new map. When called on a map, the result will be a new Map with the same entries as the previous one. If two values map to the same key and the reconcileFn argument is provided, it will be called to combine the colliding values to set the final value; otherwise, the last value to arrive at that key will overwrite the rest.

Parameters:

Name Type Description

Name	Type	Description
`iterable`	Iterable	The entries to add.
`reconcileFn?`	Reconciler	A function specifying what value to set when two keys map to the same value. If provided, this is called whether there is a collision or not, so it also serves as a mapper. Called with: The value previously set at this key, or `undefined` if no value was set; The new value arriving from the Iterable; The key where the output will be entered.

iterable

Iterable

The entries to add.

reconcileFn?

Reconciler

A function specifying what value to set when two keys map to the same value. If provided, this is called whether there is a collision or not, so it also serves as a mapper. Called with:

The value previously set at this key, or undefined if no value was set;
The new value arriving from the Iterable;
The key where the output will be entered.

Source:

maps.js, line 68

Returns:

The newly created Map.

mapCollectBumping(mapEnumeration, bumper, seed) → {Object}

Pipe the entries of a Map iterable into a Map, resolving key collisions by setting the incoming entry to a new key determined by bumper. If the new key collides too, keep calling bumper until it either resolves to a unique key or returns undefined to signal failure.

Parameters:

Name	Type	Description
`mapEnumeration`	Iterable	An entry stream with duplicate keys.
`bumper`	BumperFn	A function to be called each time a key would overwrite a key that has already been set in `seed`.
`seed`	Map	The Map to insert values into.

Source:

maps.js, line 680

Returns:

The finalized Map.

Type: Object

mapCollectInto(iterable, seed, reconcileFn?)

Insert the entries in the iterable into the provided map. If two values map to the same key and the reconcileFn argument is provided, it will be called to combine the colliding values to set the final value; otherwise, the last value to arrive at that key will overwrite the rest.

Parameters:

Name Type Description

Name	Type	Description
`iterable`	Iterable	The entries to add.
`seed`	Map	The Map to add them to.
`reconcileFn?`	Reconciler	A function specifying what value to set when two keys map to the same value. If provided, this is called whether there is a collision or not, so it also serves as a mapper. Called with: The value previously set at this key, or `undefined` if no value was set; The new value arriving from the Iterable; The key where the output will be entered.

iterable

Iterable

The entries to add.

seed

Map

The Map to add them to.

reconcileFn?

Reconciler

A function specifying what value to set when two keys map to the same value. If provided, this is called whether there is a collision or not, so it also serves as a mapper. Called with:

The value previously set at this key, or undefined if no value was set;
The new value arriving from the Iterable;
The key where the output will be entered.

Source:

maps.js, line 21

Returns:

The updated Map.

mapCollectIntoBumping(mapEnumeration, bumper, seed) → {Object}

Pipe the entries of a Map iterable into a Map, resolving key collisions by setting the incoming entry to a new key determined by bumper. If the new key collides too, keeps calling bumper until it either resolves to a unique key or returns undefined to signal failure.

Parameters:

Name	Type	Description
`mapEnumeration`	Iterable	An entry stream with duplicate keys.
`bumper`	BumperFn	A function to be called each time a key would overwrite a key that has already been set in `seed`.
`seed`	Map	The Map to insert values into.

Source:

maps.js, line 697

Returns:

The finalized Map.

Type: Object

mapKeys(iterable, fn)

Given a Map-like Iterable, produce an entry set for a new Map where each key has been mapped to a new key by calling ${keyMapper}.

Any key collisions must be handled in later steps, or they will be reconciled automatically by later entries overriding earlier ones.

Parameters:

Name	Type	Description
`iterable`	Iterable	An iterable representing the entries of a Map from key to value.
`fn`	function	A function mapping the keys of the Map to a transformed key.

Source:

maps.js, line 121

Returns:

An iterable representing the entries of a map from the transformed key to value.

mapToDictionary(map, stringifier?)

Convert a Map into a dictionary.

Parameters:

Name	Type	Description
`map`	Iterable	An iterable of Map entries.
`stringifier?`	function	A function to convert a Map key into a string key that is suitable for use in a dictionary. If excluded, `mapToDictionary` will use the default String constructor.

Source:

maps.js, line 583

Returns:

The new dictionary object.

mapValues(iterable, mapper)

Given a Map-like Iterable, produce an entry set for a new Map where each key has been mapped to a new key by calling ${mapper}.

Parameters:

Name	Type	Description
`iterable`	Iterable	An iterable representing the entries of a Map from key to value.
`mapper`	function	A function mapping the values of the Map to a transformed value.

Source:

maps.js, line 108

Returns:

An iterable representing the entries of a map from key to the transformed value.

naiveCanonize(lookup, maxDepth?)

A fallible Canonizer for mapping objects to primitive versions to allow comparison by value. Most primitives are mapped to themselves. Strings are mapped to "String: " + themselves to avoid collisions with the stringifications of other entities. Arrays and objects are mapped to a stringification that digs into objects to a level defined by maxDepth, or 2 if maxDepth is not provided. Dates are mapped to "Date: " plus their numeric value as milliseconds from epoch.

Parameters:

Name	Type	Description
`lookup`	K	The key to canonize.
`maxDepth?`	number	The maximum number of levels to descend into nested objects and arrays when stringifying.

Source:

canon.js, line 17

Returns:

A canonized version of the lookup. Not necessarily a string but guaranteed to be a primitive.

partitionCollect(iterable, keyFn, guaranteeKeys?)

Generate keys for each item in an Iterable. Sort the items into bins based on the key they generated.

If guaranteeKeys is supplied, bins with these keys are guaranteed to exist in the result even if no items generated that key.

Parameters:

Name	Type	Description
`iterable`		The input items.
`keyFn`		A function to generate keys.
`guaranteeKeys?`		A list of keys that must exist in the output.

Source:

maps.js, line 84

reconcileAdd(mapFn) → {Reconciler}

Generate a Reconciler that either adds a numeric input value to a colliding numeric value, or maps the input value to a number before doing so.

Parameters:

Name	Type	Description
`mapFn`	function	A function that maps incoming values to numbers so they can be reconciled by adding.

Source:

maps.js, line 380

Returns:

A summing Reconciler.

Type: Reconciler

reconcileAddToSet() → {Reconciler}

Generate a reconciler for collecting Sets on a map.

Source:

maps.js, line 502

Returns:

A Reconciler that adds the value to a Set or initializes a Set with that member if not.

Type: Reconciler

reconcileAppend(mapFn?) → {Reconciler}

Generate a Reconciler that pushes input values onto an array of previously colliding values, optionally transforming them first with a mapper.

Parameters:

Name	Type	Description
`mapFn?`	function	A function to call on the inputs.

Source:

maps.js, line 348

Returns:

A Reconciler that combines input values into an Array.

Type: Reconciler

reconcileConcat(mapFn?) → {Reconciler}

Generate a Reconciler that concatenates input values together when they collide, optionally transforming them first with a mapper.

Parameters:

Name	Type	Description
`mapFn?`	function	A function to call on the inputs. Regardless of the input type, the output must be an Iterable so it can be concatenated into the Map.

Source:

maps.js, line 415

Returns:

A Reconciler that concatenates input values together.

Type: Reconciler

reconcileCount() → {Reconciler}

Generate a Reconciler that bumps up a count on each collision, ultimately yielding the total number of entries that collided on a key.

Source:

maps.js, line 397

Returns:

A Reconciler that counts entries that has the same key.

Type: Reconciler

reconcileDefault() → {Reconciler}

Generate a reconciler that simulates the default behaviour of setting Maps, overwriting any value that was already at the key on set.

Source:

maps.js, line 476

Returns:

A Reconciler that always returns the incomingValue.

Type: Reconciler

reconcileEntryInto(map, key, value, reconciler)

Set a value on Map, using a Reconciler to merge the incoming value with any existing value.

This simulates the behaviour of merging a value in MapCollect, but for a single value instead of an Iterable.

WARNING: This includes the behaviour that, if the Reconciler returns undefined, the entry at the Map will be deleted.

Parameters:

Name	Type	Description
`map`		The Map to set the key-value pair on.
`key`		The key to set.
`value`		The value to reconcile with any possible colliding value in Map.
`reconciler`		The reconciler function.

Source:

maps.js, line 215

Returns:

The value ultimately set.

reconcileFirst() → {Reconciler}

Generate a reconciler that reverses the default behaviour of setting Maps: instead of overwriting what's already at a key, the set operation is ignored if a value is already present at that key.

Source:

maps.js, line 486

Returns:

A Reconciler that returns the collidingValue if it is defined, the incomingValue otherwise.

Type: Reconciler

reconcileFold(mapper, reducer)

Generate a Reconciler by specifying a function to run by default, and a second function to run if a value already exists in the Map at the specified key.

Parameters:

Name	Type	Description
`mapper`		A function that takes an incoming value and returns the value to set.
`reducer`		A function that takes the colliding value and an incoming value and returns the value to set.

Source:

maps.js, line 438

Returns:

A Reconciler that calls mapper if a collidingValue exists (even if it is undefined!), calls reducer otherwise.

reconcileInit(reducer, initial)

Generate a Reconciler by specifying a function to generate the initial value if none exists, and a second function to run to merge the incoming value with either the preexisting value or the initial value depending on the case.

Parameters:

Name	Type	Description
`reducer`		A function that merges a colliding value and an incoming value.
`initial`		A function that generates the first colliding value for when a colliding value does not exist.

Source:

maps.js, line 461

Returns:

A Reconciler that calls mapper if a collidingValue exists (even if it is undefined!), calls reducer otherwise.

rekeyBinMap(map, keyBy) → {Map}

Convert a map from keys to arrays of values (i.e., of the form Map<K, T[]>) to a map of different keys to arrays of values (i.e. of the form Map<K2, T[]>) with a re-keying function that takes the value and its current key.

This is most useful when a collection of objects has been grouped by one of its properties and, after operating on it, you need to group it by a different one of its properties.

Parameters:

Name	Type	Description
`map`	Iterable	An Iterable representing a Map of entries where the values are arrays.
`keyBy`	function	The function used to generate a new key for each member element of each bin. First argument: the value in the bin Second argument: the key of the bin

Source:

maps.js, line 570

Returns:

A Map containing, for each member value that appears in any of the arrays, an entry where the key is the value in the array and the value is a list of all the keys in the input Map that included it.

Type: Map

Example

const peopleToFlavours = new Map([
  ["Alex", [{name: "Alex", flavour: "vanilla"}]],
  ["Desdemona", [{name: "Desdemona", flavour: "banana"}, {name: "Desdemona", flavour: "chocolate"}]],
  ["Alexa", [{name: "Alexa", flavour: "vanilla"}, {name: "Alexa", flavour: "chocolate"}, {name: "Alexa", flavour: "cherry"}]]
]);

const flavoursToPeople = new Map([
  ["vanilla", [{name: "Alex", flavour: "vanilla"}, {name: "Alexa", flavour: "vanilla"}]],
  ["banana", [{name: "Desdemona", flavour: "banana"}]],
  ["chocolate", [{name: "Desdemona", flavour: "chocolate"}, {name: "Alexa", flavour: "chocolate"}]],
  ["cherry", [{name: "Alexa", flavour: "cherry"}]]
]);

should.deepEqual(
  Array.from(flavoursToPeople),
  Array.from(rekeyBinMap(peopleToFlavours, val => val.flavour))
);

resolutionFailureMessage(collidingKey, priorBumps) → {string}

Function that a caller of bumpDuplicateKeys() can use to produce a generic error message when a key collision cannot be resolved.

Parameters:

Name	Type	Description
`collidingKey`		The key that could not be resolved.
`priorBumps`		The number of attempts made before the bumper gave up.

Source:

maps.js, line 731

Returns:

A message describing the error

Type: string

selectMap(iterable, filterFn)

Filter out key-value pairs from a Map or Map-like Iterable.

Parameters:

Name	Type	Description
`iterable`	Iterable	An iterable representing the entries of a Map.
`filterFn`	function	A function that returns true if the entry is to be included, false otherwise.

Source:

maps.js, line 163

Returns:

An iterable representing the entries of a Map without all those entries for which filterFn returned false.

streamCollect(stream, reconcileFn)

Generate a new map from the ReadableStream of entries using an optional Reconciler.

Parameters:

Name	Type	Description
`stream`	ReadableStream	The input stream.
`reconcileFn`	Reconciler	Function to call to resolve collisions.

Source:

streams.js, line 38

Returns:

A promise of the generated map, to be returned when the ReadableStream closes.

(async) streamCollectInto(stream, seed, reconcileFn)

Insert the entries of a ReadableStream into seed with an optional Reconciler.

Parameters:

Name	Type	Description
`stream`	ReadableStream	The input stream.
`seed`	Map	The Map to update with the contents of `stream`.
`reconcileFn`	Reconciler	Function to call to resolve collisions.

Source:

streams.js, line 14

Returns:

A promise of the updated map, to be returned when the ReadableStream closes.

uniformMap(iterable, of)

Create a Map-like Iterable from an Iterable of keys where each key maps to the same value.

Parameters:

Name	Type	Description
`iterable`	Iterable	An iterable representing the keys of a Map.
`of`	T	The fixed value to set all keys to.

Source:

maps.js, line 152

Returns:

An Iterable representing the entries of a Map from the keys each to the same fixed value.

valuesOf(iterable)

Get an Iterable containing the values of a Map or Map-like Iterable.

Parameters:

Name	Type	Description
`iterable`	Iterable	An iterable representing the entries of a Map from key to value.

Source:

maps.js, line 141

Returns:

An iterable representing the values of the map.

(generator) zipMapsIntersection(map1, map2) → {Iterable}

Combine two Maps into a stream of entries of the form [commonKeyType, [valueInFirstMap, valueInSecondMap]]. If a key is in one Map but not the other, that key will not be represented in the output. To include them, use zipMapsUnion.

Parameters:

Name	Type	Description
`map1`
`map2`

Source:

maps.js, line 636

Returns:

An iterable of the form Map<commonKeyType, [valueInFirstMap, valueInSecondMap]> containing all keys that map1 and map2 have in common.

Type: Iterable

(generator) zipMapsUnion(map1, map2) → {Iterable}

Combine two Maps into a stream of entries of the form [commonKeyType, [valueInFirstMap | undefined], [valueInSecondMap | undefined]]. If a key is in one Map but not the other, the output tuple will contain undefined in place of the missing value. To exclude them instead, use zipMapsIntersection.

Parameters:

Name	Type	Description
`map1`
`map2`

Source:

maps.js, line 658

Returns:

An iterable of the form Map<commonKeyType, [valueInFirstMap | undefined, valueInSecondMap | undefined]> containing all keys that exist in either map1 or map2.

Type: Iterable