lightdash

A small TypeScript utility library to complement lodash.

Introduction

Lightdash is a utility library aiming to complement lodash, written in TypeScript.

Usage

Installation:

npm install lightdash

When using ES Modules:

import { groupMapBy } from "lightdash";

groupMapBy([1, 2, 3, 4, 5], (val) => val % 2);

When using CommonJS (e.g. Node):

const { groupMapBy } = require("lightdash");

groupMapBy([1, 2, 3, 4, 5], (val) => val % 2);

Contributing

Contributions are always welcome, no matter if you have a request, an idea, found a bug, or spotted a typo: Feel free to create a PR or open an issue!

Index

Array Functions

Lang Functions

Map Functions

getExistingElseThrow

Object Functions

String Functions

Array Functions

Const countMapBy

countMapBy<TValue, UKey>(array: List<TValue>, keyMapper: ListIterator<TValue, UKey>): Map<UKey, number>

- Defined in array/countMapBy.ts:18
Counts the values of an array into a map, with the key being based on a key mapper and the value being the occurrences of the key mapper result in the initial array.

since

12.0.0

example

countMapBy([1, 2, 4, 2, 4, 4], val => val) // => Map{1: 1, 2: 2, 4: 3}

Type parameters
- TValue
- UKey
Parameters
- array: List<TValue>
  
  Array to count.
- keyMapper: ListIterator<TValue, UKey>
  
  Function to use for key generation.
Returns Map<UKey, number>

Count map.

Const groupMapBy

groupMapBy<TValue, UKey>(array: List<TValue>, keyMapper: ListIterator<TValue, UKey>): Map<UKey, TValue[]>

- Defined in array/groupMapBy.ts:19
Groups the elements of an array into a map, with the key being based on a key mapper and the value being the values for the same key mapper result.

since

6.1.0

example

groupMapBy([1, 2, 3, 4, 5], val => val % 2) // => Map{0: [2, 4], 1: [1, 3, 5]}

Type parameters
- TValue
- UKey
Parameters
- array: List<TValue>
  
  Array to group.
- keyMapper: ListIterator<TValue, UKey>
  
  Function returning the key for the value.
Returns Map<UKey, TValue[]>

Grouped map.

Const groupMapReducingBy

groupMapReducingBy<TValue, UKey, VReduced>(array: List<TValue>, keyMapper: ListIterator<TValue, UKey>, initializer: ListIterator<TValue, VReduced>, reducer: (current: VReduced, value: TValue, index: number, collection: List<TValue>) => VReduced): Map<UKey, VReduced>

- Defined in array/groupMapReducingBy.ts:34
Groups the elements of an array into a map, with the key being based on a key mapper and the value being the values for the same key mapper result being reduced.

since

11.0.0

example

groupMapReducingBy( ["foo", "bar", "fizz", "buzz"], val => val.charAt(0), () => { return { count: 0, matches: [] }; }, (current, val) => { current.count++; current.matches.push(val); return current; } ) // => Map{"f": {count: 2, matches: ["foo", "fizz"]}, "b": {count: 2, matches: ["bar", "buzz"]}}

Type parameters
- TValue
- UKey
- VReduced
Parameters
- array: List<TValue>
  
  Array to group.
- keyMapper: ListIterator<TValue, UKey>
  
  Function returning the key for the value.
- initializer: ListIterator<TValue, VReduced>
  
  Function initializing a new reduction result object.
- reducer: (current: VReduced, value: TValue, index: number, collection: List<TValue>) => VReduced
  
  Consumer mutating the existing reduction result object with the new data.
  - - (current: VReduced, value: TValue, index: number, collection: List<TValue>): VReduced
    - Parameters
      - current: VReduced
      - value: TValue
      - index: number
      - collection: List<TValue>
      Returns VReduced
Returns Map<UKey, VReduced>

Grouped and reduced map.

Const insertAt

insertAt<TValue>(array: TValue[], index: number, ...values: TValue[]): TValue[]

- Defined in array/insertAt.ts:31
Inserts the value(s) at the given position. If the index is equal or higher than the array length, the value(s) will be appended. If the index is less than 0, the value(s) will be prepended.

Note that the input array is being mutated.

since

12.1.0

example

const a = ["foo", "fizz"]; insertAt(a, 1, "bar") // => ["foo", "bar", "fizz"]

const b = ["foo", "fizz"]; insertAt(b, 1, "bar", "bazz")) // => ["foo", "bar", "fizz", "bazz"]

const c = ["foo", "fizz"]; insertAt(c, 999, "bar")) // => ["foo", "fizz", "bar"]

const d = ["foo", "fizz"]; insertAt(d, -999, "bar")) // => ["bar", "foo", "fizz"]

Type parameters
- TValue
Parameters
- array: TValue[]
  
  Array to modify.
- index: number
  
  Index to insert at.
- Rest ...values: TValue[]
  
  Value(s) to insert.
Returns TValue[]

The mutated array.

Const pullFirst

pullFirst<TValue>(array: List<TValue>, value: TValue): List<TValue>

- Defined in array/pullFirst.ts:24
Removes the first occurrence of an element from an array. If the element does not exist in the array nothing is done.

Note that the input array is being mutated.

since

2.8.0

example

const a = ["foo", "bar", "fizz", "bar"]; removeItem(a, "bar") // => ["foo", "fizz", "bar"]

const b = ["foo", "bar", "fizz", "bar"]; removeItem(b, "bazz") // => ["foo", "bar", "fizz", "bar"]

Type parameters
- TValue
Parameters
- array: List<TValue>
  
  Array to modify.
- value: TValue
  
  The value to remove.
Returns List<TValue>

The mutated array.

Const step

step<TValue>(array: List<TValue>, stepSize: number): List<TValue>

- Defined in array/step.ts:16
Returns a new array with every n-th item from the input array.

since

1.0.0

example

step([1, 2, 3, 4, 5, 6], 2) // => [1, 3, 5]

Type parameters
- TValue
Parameters
- array: List<TValue>
  
  Array to use.
- stepSize: number
  
  Step to use.
Returns List<TValue>

Stepped collection.

Lang Functions

Const isBlank

isBlank(string: string): boolean

- Defined in lang/isBlank.ts:20
Checks if the string is blank (no non-space content).

since

11.0.0

example

isBlank("") // => true

isBlank(" ") // => true

isBlank(" foo ") // => false

Parameters
- string: string
  
  String to use.
Returns boolean

If the string is blank.

Const isPromise

isPromise(value: unknown): value is Promise<unknown>

- Defined in lang/isPromise.ts:15
Checks if a value is a promise.

since

3.0.0

example

isPromise(new Promise((resolve, reject) => resolve("foo"))); // => true

isPromise(() => "foo"); // => false

Parameters
- value: unknown
  
  Value to check.
Returns value is Promise<unknown>

If the value is a promise.

Const name

name(value: unknown): string | null

- Defined in lang/name.ts:31
Gets name of a value.

If the value is a function, its name is returned. If the value is a symbol, its key is returned. If the value is a string, it is returned as is. Otherwise null is returned.

since

10.2.0

example

name(class Foo{}) // => "Foo"

name(function bar(){}) // => "bar"

name(Symbol.for("abc")) // => "abc"

name("foo") // => "foo"

name(1) // => null

Parameters
- value: unknown
  
  Value to check.
Returns string | null

The name of the value.

Const requireNonNilElseThrow

requireNonNilElseThrow<T>(value: T | null | undefined, errorSupplier: () => Error): T

- Defined in lang/requireNonNilElseThrow.ts:17
Throws an exception if the value is nil, returns the value otherwise.

since

13.0.0

throws

Error if value is nil.

example

requireNonNilElseThrow("foo", () => new TypeError()) // => "foo"

requireNonNilElseThrow(null, () => new TypeError()) // => throws TypeError

Type parameters
- T
Parameters
- value: T | null | undefined
  
  Value to check.
- errorSupplier: () => Error
  
  Supplier for the error to be thrown.
  - - (): Error
    - Returns Error
Returns T

The value provided with guarantee to be non-nil.

Const toMap

toMap<TValue>(object: Dictionary<TValue> | NumericDictionary<TValue>): Map<string, TValue>

- Defined in lang/toMap.ts:15
Creates a map from an objects entries.

since

1.0.0

example

toMap({a: 1, b: 4, c: 5}) // => Map{"a": 1, "b": 4, "c": 5}

Type parameters
- TValue
Parameters
- object: Dictionary<TValue> | NumericDictionary<TValue>
  
  Object to use.
Returns Map<string, TValue>

Map created from the object.

Const toMapBy

toMapBy<TValue, UKey, VInitialValue>(object: Dictionary<VInitialValue> | NumericDictionary<VInitialValue>, keyMapper: (key: string, val: VInitialValue) => UKey, valueMapper: (key: string, value: VInitialValue) => TValue): Map<UKey, TValue>

- Defined in lang/toMapBy.ts:17
Creates a map from an objects entries.

since

13.0.0

example

toMap({a: 1, b: 4, c: 5}, key => { return { key }; }, value => value * 2) // => Map{{key: "a"}: 2, {key: "b"}: 8, {key: "a"}: 10}

Type parameters
- TValue
- UKey
- VInitialValue
Parameters
- object: Dictionary<VInitialValue> | NumericDictionary<VInitialValue>
  
  Object to use.
- keyMapper: (key: string, val: VInitialValue) => UKey
  
  Function mapping an object key to a map key.
  - - (key: string, val: VInitialValue): UKey
    - Parameters
      - key: string
      - val: VInitialValue
      Returns UKey
- valueMapper: (key: string, value: VInitialValue) => TValue
  
  Function mapping an object value to a map value.
  - - (key: string, value: VInitialValue): TValue
    - Parameters
      - key: string
      - value: VInitialValue
      Returns TValue
Returns Map<UKey, TValue>

Map created from the object.

Map Functions

Const getExistingElseThrow

getExistingElseThrow<TKey, UValue>(map: Map<TKey, UValue>, key: TKey): UValue

- Defined in map/getExistingElseThrow.ts:17
Gets the value of a map entry by its key, throwing if the map does not contain the key.

since

13.0.0

throws

TypeError if map does not contain key.

example

getExistingElseThrow(new Map([["key", 1]]), "key") // => 1

getExistingElseThrow(new Map([["key", 1]]), "foo") // => throws TypeError

Type parameters
- TKey
- UValue
Parameters
- map: Map<TKey, UValue>
  
  Map to check against.
- key: TKey
  
  Key to get the value for.
Returns UValue

The corresponding value.

Object Functions

Const deepFreeze

deepFreeze(object: object): void

- Defined in object/deepFreeze.ts:17
Recursively freezes objects, useful for constant objects.

This function mutates the input value and calls Object.freeze() recursively on all sub-objects.

since

12.0.0

example

const a = {a: {b: 2}, b: [1, {foo: "foo"}], c: 2};

deepFreeze(a) // => object and all sub-objects are frozen.

Parameters
- object: object
  
  Object to recursively freeze.
Returns void

Const deepSeal

deepSeal(object: object): void

- Defined in object/deepSeal.ts:17
Recursively seals objects, useful for constant objects.

This function mutates the input value and calls Object.seal() recursively on all sub-objects.

since

12.0.0

example

const a = {a: {b: 2}, b: [1, {foo: "foo"}], c: 2};

deepSeal(a) // => object and all sub-objects are sealed.

Parameters
- object: object
  
  Object to recursively seal.
Returns void

String Functions

Const pascalCase

pascalCase(string: string): string

- Defined in string/pascalCase.ts:17
Creates a PascalCase string from a string.

since

6.2.0

example

pascalCase("fooBar") // => "FooBar"

pascalCase("fizz-buzz_bazz") // => "FizzBuzzBazz"

Parameters
- string: string
  
  String to use.
Returns string

PascalCase string of the input string.

Const removeEnd

removeEnd(string: string, removeValue: string): string

- Defined in string/removeEnd.ts:19
Removes a value from the end of a string. If the string does not end with the value, nothing is done.

since

13.0.0

example

removeEnd("FooBar", "Bar") // => "Foo"

removeEnd("FooBar", "Foo") // => "FooBar"

removeEnd("FooBar", "Buzz") // => "FooBar"

Parameters
- string: string
  
  String to check.
- removeValue: string
  
  Value to remove.
Returns string

String with the value removed from the end.

Const removeStart

removeStart(string: string, removeValue: string): string

- Defined in string/removeStart.ts:19
Removes a value from the start of a string. If the string does not start with the value, nothing is done.

since

13.0.0

example

removeStart("FooBar", "Foo") // => "Bar"

removeStart("FooBar", "Bar") // => "FooBar"

removeStart("FooBar", "Buzz") // => "FooBar"

Parameters
- string: string
  
  String to check.
- removeValue: string
  
  Value to remove.
Returns string

String with the value removed from the start.

Generated using TypeDoc

lightdash

Introduction

Usage

Contributing

Index

Array Functions

Lang Functions

Map Functions

Object Functions

String Functions

Array Functions

Const countMapBy

Type parameters

TValue

UKey

Parameters

array: List<TValue>

keyMapper: ListIterator<TValue, UKey>

Returns Map<UKey, number>

Const groupMapBy

Type parameters

TValue

UKey

Parameters

array: List<TValue>

keyMapper: ListIterator<TValue, UKey>

Returns Map<UKey, TValue[]>

Const groupMapReducingBy

Type parameters

TValue

UKey

VReduced

Parameters

array: List<TValue>

keyMapper: ListIterator<TValue, UKey>

initializer: ListIterator<TValue, VReduced>

reducer: (current: VReduced, value: TValue, index: number, collection: List<TValue>) => VReduced

Parameters

current: VReduced

value: TValue

index: number

collection: List<TValue>

Returns VReduced

Returns Map<UKey, VReduced>

Const insertAt

Type parameters

TValue

Parameters

array: TValue[]

index: number

Rest ...values: TValue[]

Returns TValue[]

Const pullFirst

Type parameters

TValue

Parameters

array: List<TValue>

value: TValue

Returns List<TValue>

Const step

Type parameters

TValue

Parameters

array: List<TValue>

stepSize: number

Returns List<TValue>

Lang Functions

Const isBlank

Parameters

string: string

Returns boolean

Const isPromise

Parameters

value: unknown

Returns value is Promise<unknown>

Const name

Parameters

value: unknown

Returns string | null

Const requireNonNilElseThrow