lightdash

A lightweight TypeScript utility library to complement lodash.

Introduction

Lightdash is an extensive object of utility functions to complement lodash written in TypeScript, designed to be lightweight and modern.

Docs

Versions

>= v11.x

An utility library built on top of lodash, complementing it.

v10.x

A standalone utility library to replace lodash.

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 (Node):

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

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

Updating

v10.x -> v11.x

Breaking:

Made the library complement lodash rather than replace it. All duplicate methods have been removed.

v9.x -> v10.x

Breaking:

changed entry iteration from key,val,index,object to val,key,object
removed isArray and strFromCamelCase (use Array.isArray and strFromPascalCase instead)
removed "immediate" param for fn* methods

v8.x -> v9.x

Breaking:

Merged arrRemoveItem and arrRemoveItemFirst
Removed isArguments and isNull
Removed numSum, numMedian and numAverage
Removed fnCurry
Removed hasPath

Contributing

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

Index

Array Functions

Enum Functions

Is Functions

Lang Functions

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:17
Counts the values of an array in a map, using the return value of the function as key.

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:17
Collects the values of an array in a map as array values, using the return value of the function as key.

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 to use for grouping.
Returns Map<UKey, TValue[]>

Grouped map.

Const groupMapReducingBy

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

- Defined in array/groupMapReducingBy.ts:31
Collects elements in an array into a an array of merged elements.

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
- VMerged
Parameters
- array: List<TValue>
  
  Array to group.
- keyMapper: ListIterator<TValue, UKey>
  
  Function returning the key for the value.
- initializer: ListIterator<TValue, VMerged>
  
  Function initializing a new mergable object.
- reducer: (current: VMerged, value: TValue, index: number, collection: List<TValue>) => VMerged
  
  Consumer mutating the existing object with the new data.
  - - (current: VMerged, value: TValue, index: number, collection: List<TValue>): VMerged
    - Parameters
      - current: VMerged
      - value: TValue
      - index: number
      - collection: List<TValue>
      Returns VMerged
Returns Map<UKey, VMerged>

Grouped and merged map.

Const insertAt

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

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

Note: the input array is being mutated.

since

12.1.0

example

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

Type parameters
- TValue
- UKey
Parameters
- array: TValue[]
  
  Array to insertAt to.
- index: number
  
  Index to start inserting.
- Rest ...values: TValue[]
  
  Value(s) to insertAt.
Returns TValue[]

Collection.

Const pullFirst

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

- Defined in array/pullFirst.ts:18
Removes the first occurrence of an element from an array.

Note: the input array is being mutated.

since

2.8.0

example

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

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

The mutated collection.

Const step

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

- Defined in array/step.ts:15
Returns a new collection 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.

Enum Functions

Const findByKey

findByKey<TEnum>(targetEnum: Record<string, unknown>, targetKey: string): TEnum | null

- Defined in enum/findByKey.ts:27
Retrieves the corresponding enum item for a key; This can be useful for mapping external data to properly typed data. NOTE: due to the way enums work in TypeScript, a handful of quirks apply:
- const enums cannot be used due to being inlined during compilation.
since

13.0.0

example

enum MyStringEnum { FOO = "Foo", BAR = "Bar", } findByKey(MyStringEnum, "FOO"); // => MyStringEnum.FOO

enum MyStringEnum { FOO = "Foo", BAR = "Bar", } findByKey(MyStringEnum, "FIZZ"); // => null
Type parameters
- TEnum
Parameters
- targetEnum: Record<string, unknown>
  
  Enum to get an item of.
- targetKey: string
  
  Item key to search.
Returns TEnum | null

Enum item or null if none matched

Const findByValue

findByValue<TEnum>(targetEnum: Record<string, TEnum[any]>, targetValue: TEnum[any]): TEnum | null

- Defined in enum/findByValue.ts:32
Retrieves the corresponding enum item for a value; This can be useful for mapping external data to properly typed data. NOTE: due to the way enums work in TypeScript, a handful of quirks apply:
- Do not use enums where the same value is used for multiple items! Either value will be found, however the typing that is returned cannot be guaranteed.
- const enums cannot be used due to being inlined during compilation.
since

13.0.0

throws

TypeError if not all values in enum are unique.

example

enum MyStringEnum { FOO = "Foo", BAR = "Bar", } findByValue(MyStringEnum, "Foo"); // => MyStringEnum.FOO

enum MyStringEnum { FOO = "Foo", BAR = "Bar", } findByValue(MyStringEnum, "Fizz"); // => null
Type parameters
- TEnum
Parameters
- targetEnum: Record<string, TEnum[any]>
  
  Enum to get an item of.
- targetValue: TEnum[any]
  
  Item value to search.
Returns TEnum | null

Enum item or null if none matched

Is Functions

Const isBlank

isBlank(string: string): boolean

- Defined in is/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 file is blank.

Const isPromise

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

- Defined in is/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.

Lang Functions

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:14
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:16
Creates a map from an objects entries, mapping the keys and values.

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 keys.
  - - (key: string, val: VInitialValue): UKey
    - Parameters
      - key: string
      - val: VInitialValue
      Returns UKey
- valueMapper: (key: string, value: VInitialValue) => TValue
  
  Function mapping values.
  - - (key: string, value: VInitialValue): TValue
    - Parameters
      - key: string
      - value: VInitialValue
      Returns TValue
Returns Map<UKey, TValue>

Map created from the object.

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 distance

distance(string1: string, string2: string): number

- Defined in string/distance.ts:19
Returns the levenshtein string distance of two strings.

since

6.3.0

example

distance("Kitten", "Sitting") // => 3

distance("String", "Stribng") // => 1

distance("foo", "foo") // => 0

Parameters
- string1: string
  
  First string to compare.
- string2: string
  
  Second string to compare.
Returns number

Distance between the two strings.

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("foo_bar") // => "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.

Const similar

similar(string: string, array: List<string>, returnFull?: boolean): List<string> | Map<number, List<string>>

- Defined in string/similar.ts:27
Returns strings similar to the input based its levenshtein distance to the values in the list given.

since

6.3.0

example

similar("Fob", ["Foo", "Bar"]) // => ["Foo"]

similar("cmmit", ["init", "commit", "push"]) // => ["commit"]

similar("Kitten", ["Sitten", "Sitting", "Bitten"]) // => ["Sitten", "Bitten"]

similar("cmmit", ["init", "commit", "push"], true) // => Map<number, string[]>{1: ["commit"], 3: ["init"], 5: ["push"]}

Parameters
- string: string
  
  String to check.
- array: List<string>
  
  Array of values to compare the string to.
- Default value returnFull: boolean = false
  
  If the full map should be returned, rather than just the closest matches.
Returns List<string> | Map<number, List<string>>

Array of the closest matches, or the map if returnFull is true.

Generated using TypeDoc

lightdash

Introduction

Versions

>= v11.x

v10.x

Usage

Updating

v10.x -> v11.x

v9.x -> v10.x

v8.x -> v9.x

Contributing

Index

Array Functions

Enum Functions

Is Functions

Lang 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

VMerged

Parameters

array: List<TValue>

keyMapper: ListIterator<TValue, UKey>

initializer: ListIterator<TValue, VMerged>

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

Parameters

current: VMerged

value: TValue

index: number

collection: List<TValue>

Returns VMerged

Returns Map<UKey, VMerged>

Const insertAt

Type parameters

TValue

UKey

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>

Enum Functions

Const findByKey

Type parameters

TEnum

Parameters