@sandstreamdev/std
v0.15.0
Published
Modern library of statically-typed modular functions for daily use in JavaScript and TypeScript projects.
Downloads
33
Readme
std
Installation
npm install @sandstreamdev/std
Documentation
array
any
Checks if the given array is present and it is not empty (contains at least one element).
Type signature
<T>(xs?: T[]) => boolean
Examples
any([]);
// ⇒ false
any([1, 2, 3]);
// ⇒ true
Questions
- How to check if an array is empty?
- How to check if an array is empty or null or undefined?
- How to check if an array is empty or not?
- How to check if an array is empty or doesn't exist?
are
Checks if the given arguments are all Arrays
.
Type signature
<T>(...xs: T[]) => boolean
Examples
are([2, 3]);
// ⇒ true
are([1, 2, 3], []);
// ⇒ true
are([1, 2, 3], 8, [1, 3], "test");
// ⇒ false
Questions
- How to check if all the given values are arrays?
chunk
Splits the given array into an array of chunks of up to the given length.
Type signature
(count: number) => <T>(xs: T[]) => T[] | T[][]
Examples
chunk(2)(['a', 'b', 'c', 'd']);
// ⇒ [['a', 'b'], ['c', 'd']]
chunk(3)(['a', 'b', 'c', 'd']);
// ⇒ [['a', 'b', 'c'], ['d']]
Questions
- How to split an array into chunks?
- How to split an array into chunks of the same size?
difference
Computes a set difference between the two given arrays.
Type signature
<T>(xs: T[], ys: T[]) => T[]
Examples
difference([1, 2, 3, 4, 5, 6], [2, 4]);
// ⇒ [1, 3, 5, 6]
Questions
- How to find elements which are present in the first array and not in the second?
differs
Checks if two arrays are not equal.
Type signature
<T>(xs?: T[], ys?: T[]) => boolean
Examples
differs([1, 2, 3], [1, 2]);
// ⇒ true
differs([1, 2, 3], [1, 2, 3]);
// ⇒ false
Questions
- How to check if two arrays differ?
- How to check if two arrays are not equal?
- How to check if two arrays are equal or not?
duplicates
Lists all the duplicated values in the given array.
Type signature
<T>(xs: T[]) => T[]
Examples
duplicates([1, 2, 3, 4, 3, 4, 3, 6]);
// ⇒ [3, 4, 3]
Questions
- How to find duplicates in an array?
empty
Empty array.
Type signature
unknown[]
Examples
empty;
// ⇒ []
Questions
- How to get an empty array?
exact
Takes exactly the given count of elements.
Type signature
(count: number) => <T>(xs: T[]) => T[]
Examples
exact(5)([1, 2, 3]);
// ⇒ [1, 2, 3, undefined, undefined]
exact(2)([1, 2, 3]);
// ⇒ [1, 2]
Questions
- How to get exactly N elements out of an array?
except
Filters out the given value.
Type signature
<T>(y: T) => (xs: T[]) => T[]
Examples
except(2)([1, 2, 3, 4, 5]);
// ⇒ [1, 3, 4, 5]
except(2)([1, 2, 2, 4, 2]);
// ⇒ [1, 4]
Questions
- How to get all the values of an array except the given one?
filterInPlace
Filters the given array with the given predicate just like Array.filter but does it in-place thus mutates the original array.
Type signature
<T>(f: (value: T, index: number, context: T[]) => boolean) => (xs: T[]) => T[]
Examples
const xs = [1, 2, 3, 4, 5, 6, 7];
const odd = x => x % 2 === 1;
const ys = filterInPlace(odd)(xs);
ys === xs;
// ⇒ true
ys;
// ⇒ [1, 3, 5, 7]
Questions
- How to filter an array in place?
find
Finds an element by a predicate function within the given array, otherwise, it returns the given fallback value or undefined when fallback is not present.
Type signature
<T>(predicate: (value: T, index: number, context: T[]) => boolean, fallback?: T) => (xs: T[]) => T
Examples
find(x => x > 2)([1, 2, 3, 5, 7]);
// ⇒ 3
find(x => x > 2)([1, 2, -3, -5, -7]);
// ⇒ undefined
Questions
- How to find an element of an array by a given predicate?
first
Returns the first element or undefined when there are no elements in the given array.
Type signature
<T>([x]: T[]) => T | undefined
Examples
first([1, 2, 3]);
// ⇒ 1
first([]);
// ⇒ undefined
Questions
- How to get the first element of an array?
flatMap
Maps and flattens the result.
Type signature
<T, TResult>(f: (value: T, index: number, context: T[]) => TResult[]) => (xs: T[]) => TResult[]
Examples
flatMap(text => [...text])(["test", "123"]);
// ⇒ ["t", "e", "s", "t", "1", "2", "3"]
Questions
- How to flat map an array?
- How to map and then flatten an array?
flatten
Flattens the nested arrays by a single level.
Type signature
<T>(xs: T[]) => T[]
Examples
flatten([1, [2, 3], 4, [5, 6]]);
// ⇒ [1, 2, 3, 4, 5, 6]
flatten([1, [2, [3, 6]], 4, [5, 6]]);
// ⇒ [1, 2, [3, 6], 4, 5, 6]
Questions
- How to flatten an array?
insert
Inserts the given item to the array at a specific index.
Type signature
(index: number) => <T>(item: T) => ([...xs]: T[]) => T[]
Examples
insert(0)('d')(['a', 'b', 'c']);
// ⇒ ['d', 'a', 'b', 'c']
insert(1)('d')(['a', 'b', 'c']);
// ⇒ ['a', 'd', 'b', 'c']
Questions
- How to insert an element to an array at a given position?
intersection
Finds common elements between both arrays.
Type signature
<T>(xs: T[], ys: T[]) => T[]
Examples
intersection([1, 2, 3, 4, 5], [5, 5, 3, 2]);
// ⇒ [2, 3, 5]
Questions
- How to find common elements present in both arrays?
is
Checks if the given argument is an array.
Type signature
(value?: unknown) => boolean
Examples
is([1, 2, 3]);
// ⇒ true
is({ a: 5 });
// ⇒ false
Questions
- How to check if a value is an array?
last
Returns the last element or undefined when there are no elements in the given array.
Type signature
<T>(xs: T[]) => T | undefined
Examples
last([1, 2, 3]);
// ⇒ 3
last([]);
// ⇒ undefined
Questions
- How to get the last element of an array?
length
Returns the number of elements in the given array.
Type signature
<T>(xs: T[]) => number
Examples
length([true, 1]);
// ⇒ 2
length([1, 2, 3]);
// ⇒ 3
length([]);
// ⇒ 0
Questions
- How to check an array's length?
- How to compute an array's length?
- How to check the size of an array?
- How to check the number of elements in an array?
lengthDiffers
Checks if lengths of the given arrays differ.
Type signature
<T1, T2>(a: T1[], b: T2[]) => boolean
Examples
lengthDiffers([1, 2, 3], [1, 2]);
// ⇒ true
lengthDiffers([6, 7], [1, 2]);
// ⇒ false
Questions
- How to check if array lengths differ?
- How to check if the given arrays have different lengths?
map
Maps the given array with the given functions.
Type signature
<T>(...fs: ((x: T) => T)[]) => (xs: T[]) => T[]
Examples
map(x => x * x)([1, 2, 3]);
// ⇒ [1, 4, 9]
map(x => x * x, x => x + 1)([1, 2, 3]);
// ⇒ [2, 5, 10]
Questions
- How to map an array?
midpoint
Returns the middle element or the right one when the number of elements is even.
Type signature
<T>(xs: T[]) => T | undefined
Examples
midpoint([1, 2, 3, 4, 5]);
// ⇒ 3
midpoint([1, 2, 3, 4]);
// ⇒ 3
Questions
- How to get the element in the middle of an array?
- How to get the middle element of an array?
minMax
Computes minimum and maximum values of the given array in a single run.
Type signature
(xs: number[]) => number[]
Examples
minMax([10, 5, 3, -5, -4, 23, 32, 8, 1, 0]);
// ⇒ [-5, 32]
minMax([1]);
// ⇒ [1, 1]
minMax([]);
// ⇒ [undefined, undefined]
Questions
- How to find the minimum and maximum values of an array?
- How to get the min/max element of an array?
multiple
Checks if the given array contains more than one element.
Type signature
<T>(xs: T[]) => boolean
Examples
multiple([1, 2, 3]);
// ⇒ true
multiple([1, 2]);
// ⇒ true
multiple([1]);
// ⇒ false
multiple([]);
// ⇒ false
Questions
- How to check if an array contains multiple elements?
- How to check whether multiple values exist within an array?
none
Checks if the given array is empty.
Type signature
<T>(xs?: T[]) => boolean
Examples
none([]);
// ⇒ true
none([1, 2, 3]);
// ⇒ false
Questions
- How to check if an array is empty?
partition
Partitions the given array to the ones that pass the given predicate function and the ones that do not. By convention of the Haskell's Data.Either, values that pass the predicate are placed at the right.
Type signature
<T>(predicate: (x: T) => boolean) => (xs: T[]) => readonly [T[], T[]]
Examples
partition(x => x % 2 === 1)([1, 2, 3, 4, 5]);
// ⇒ [[2, 4], [1, 3, 5]])
Questions
- How to partition an array based on a condition?
- How to divide an array by a filter function?
pop
Returns the given array without the last element.
Type signature
<T>(xs: T[]) => T[]
Examples
pop([1, 2, 3, 4]); // ⇒ [1, 2, 3]
pop([]); // ⇒ []
Questions
- How to get an array without the last element?
- How to remove the last element from an array?
range
Generates an array of numbers from 0 to n - 1.
Type signature
(n: number) => number[]
Examples
range(3);
// ⇒ [0, 1, 2]
Questions
- How to create an array of all integers from 0 to N exclusive?
removeAt
Removes an element at the given index from the given array.
Type signature
(index: number) => <T>(xs: T[]) => T[]
Examples
removeAt(3)([1, 2, 3, 4, 5, 6])
// ⇒ [1, 2, 3, 5, 6]
Questions
- How to remove an item from an array at a particular index?
repeat
Repeats the given element by the given count of times.
Type signature
(count: number) => <T>(value: T) => T[]
Examples
repeat(3)("test");
// ⇒ ["test", "test", "test"]
Questions
- How to repeat a value N times?
reverse
Reverses the given array without mutating it (in contrast to Array.reverse).
Type signature
<T>(xs: T[]) => T[]
Examples
reverse([1, 2, 3, 4, 5]);
// ⇒ [5, 4, 3, 2, 1]
Questions
- How to reverse an array without mutating it?
reverseIf
Reverses the given array when enabled.
Type signature
(enabled: boolean) => <T>(xs: T[]) => T[]
Examples
reverseIf(true)([1, 2, 3, 4, 5]);
// ⇒ [5, 4, 3, 2, 1]
reverseIf(false)([1, 2, 3, 4, 5]);
// ⇒ [1, 2, 3, 4, 5]
Questions
- How to reverse an array without mutating it only when a condition is satisfied?
second
Returns the second element or undefined when there are less than two elements in the given array.
Type signature
<T>(xs: T[]) => T | undefined
Examples
second([1, 2, 3, 4, 5]);
// ⇒ 2
second([1]);
// ⇒ undefined
second([]);
// ⇒ undefined
Questions
- How to get the second element of an array?
secondToLast
Returns the second to last element or undefined when there are less than two elements in the given array.
Type signature
<T>(xs: T[]) => T | undefined
Examples
secondToLast([1, 2, 3, 4, 5]);
// ⇒ 4
secondToLast([1]);
// ⇒ undefined
secondToLast([]);
// ⇒ undefined
Questions
- How to get the second to last element of an array?
shift
Shifts the given array to the left and circulates the elements back by modulo of the array's length.
Type signature
(count: number) => <T>(xs: T[]) => T[]
Examples
shift(1)([1, 2, 3, 4, 5]);
// ⇒ [2, 3, 4, 5, 1]
shift(2)([1, 2, 3, 4, 5]);
// ⇒ [3, 4, 5, 1, 2]
shift(3)([1, 2, 3, 4, 5]);
// ⇒ [4, 5, 1, 2, 3]
Questions
- How to shift an array?
shuffle
Shuffles the given array in random order with Math.random as the default.
Type signature
<T>(xs: T[], random?: () => number) => T[]
Examples
let i = 0;
const random = () =>
[
0.013606630487694282,
0.21052486239086554,
0.28299838254636556,
0.696161009199874,
0.32165320593537117
][i++];
shuffle([1, 2, 3, 4, 5], random); // => [3, 5, 4, 2, 1]
Questions
- How to shuffle an array?
shuffleInPlace
Shuffles the given array in-place in random order with Math.random as the default.
Type signature
<T>(xs: T[], random?: () => number) => T[]
Examples
let i = 0;
const random = () =>
[
0.013606630487694282,
0.21052486239086554,
0.28299838254636556,
0.696161009199874,
0.32165320593537117
][i++];
shuffleInPlace([1, 2, 3, 4, 5], random); // => [3, 5, 4, 2, 1]
Questions
- How to shuffle an array in place?
single
Checks if the given array contains exactly one element.
Type signature
<T>(xs: T[]) => boolean
Examples
single([1]);
// ⇒ true
single([1, 2, 3]);
// ⇒ false
single([]);
// ⇒ false
Questions
- How to check if an array contains only one element?
skip
Skips the given count of elements from the given array.
Type signature
(count: number) => <T>(xs: T[]) => T[]
Examples
skip(2)([1, 2, 3, 4, 5]);
// ⇒ [3, 4, 5]
Questions
- How to skip the first few elements of an array?
slidingWindow
Returns a new array composed of tuples of the given sliding window length of consecutive elements.
Type signature
(count: number) => <T>(xs: T[]) => T[][]
Examples
slidingWindow(2)([1, 2, 3, 4]);
// ⇒ [[1, 2], [2, 3], [3, 4]]
slidingWindow(3)([1, 2, 3, 4, 5]);
// ⇒ [[1, 2, 3], [2, 3, 4], [3, 4, 5]]
slidingWindow(1)([1, 2, 3, 4, 5, 6]);
// ⇒ [[1], [2], [3], [4], [5], [6]]
Questions
- How to iterate an array pairwise?
sort
Sorts the given array without mutating it.
Type signature
<T>(f?: (a: T, b: T) => number) => (xs: T[]) => T[]
Examples
sort((a, b) => a - b)([13, 79, 20, 69, 44, 67, 18, 95, 26, 55]);
// ⇒ [13, 18, 20, 26, 44, 55, 67, 69, 79, 95]
Questions
- How to sort an array without mutating it?
sum
Sums the given array of numbers.
Type signature
(xs: number[]) => number
Examples
sum([1, 2, 3, 4, 5]);
// ⇒ 15
Questions
- How to sum elements of an array?
take
Takes up to a given count of elements.
Type signature
(count: number) => <T>(xs: T[]) => T[]
Examples
take(2)([1, 2, 3, 4, 5]);
// ⇒ [1, 2]
take(10)([1, 2, 3, 4, 5]);
// ⇒ [1, 2, 3, 4, 5]
Questions
- How to get the first N number of elements from an array?
unique
Returns unique elements of the given array.
Type signature
<T>(xs: T[]) => T[]
Examples
unique([1, 2, 3, 4, 3, 4, 3, 6]);
// ⇒ [1, 2, 3, 4, 6]
Questions
- How to find all unique values in an array?
uniqueBy
Filters out duplicated values based on the result of the given key selector.
Type signature
<T, TResult>(f: (x: T) => TResult) => (xs: T[]) => T[]
Examples
uniqueBy(({ id }) => id)([
{ id: 1, value: 'a' },
{ id: 2, value: 'b' },
{ id: 1, value: 'c' }
])
// ⇒ [{ id: 1, value: 'c' }, { id: 2, value: 'b' }]
Questions
- How to find all unique values in an array by some predicate?
zip
Zips the given arrays together into pairs.
Type signature
(xs: unknown[], ys: unknown[]) => [unknown, unknown][]
Examples
zip([1, 2, 3], [4, 5, 6]);
// ⇒ [[1, 4],[2, 5],[3, 6]]
Questions
- How to zip two arrays?
zipN
Zips the given arrays together into pairs.
Type signature
<T>(...xs: T[][]) => T[][]
Examples
zipN([1, 2, 3], [4, 5, 6]);
// ⇒ [[1, 4], [2, 5], [3, 6]]
zipN([1, 2, 3], [4, 5, 6], [7, 8, 9]);
// ⇒ [[1, 4, 7], [2, 5, 8], [3, 6, 9]]
zipN([1, 2], [4, 5, 6], [7, 8, 9]);
// ⇒ [[1, 4, 7],[2, 5, 8]]
Questions
- How to zip multiple arrays?
zipWith
Zips the given arrays together with the given function.
Type signature
<T1, T2>(f?: (x: T1, y: T2) => [T1, T2]) => (xs: T1[], ys: T2[]) => [T1, T2][]
Examples
zipWith((x, y) => x * x + y)([1, 2, 3], [4, 5, 6]);
// ⇒ [5, 9, 15]
Questions
- How to zip two arrays with a given function?
async
debounce
Makes the function run after the given period of not being called. Useful to delay input submission for auto-complete etc.
Type signature
(f: F, wait: number) => (...args: unknown[]) => void
Examples
const f = () => console.log("Test");
const debounced = debounce(f, 2000);
debounced();
setTimeout(debounced, 1000);
setTimeout(debounced, 3000);
Questions
- How to make function fire after some time not being called?
- How to debounce input events?
- How to debounce a function?
delay
When awaited, delays the execution by the given number of milliseconds.
Type signature
(duration: number) => Promise<unknown>
Examples
delay(2000)(() => console.log("Test"));
Questions
- How to delay a function?
- What is the JavaScript version of sleep()?
sequence
Runs the given tasks in a sequence.
Type signature
<T>(tasks: Task<T>[]) => Promise<Awaited<T>[]>
Examples
const f = () => new Promise(resolve => setTimeout(resolve, 1000));
const g = () => new Promise(resolve => setTimeout(resolve, 2000));
sequence([f, g]).then(() => console.log("Done"));
Questions
- How to run async tasks sequentially?
date
clamp
Clamps the given date to the given date range.
Type signature
(min: Date, max: Date) => (date: Date) => Date
Examples
const date = new Date("2019-06-15T13:54:33.232Z");
const min = new Date("2019-02-23T13:54:33.232Z");
const max = new Date("2019-03-13T13:54:33.232Z");
clamp(min, max)(date);
// => new Date("2019-03-13T13:54:33.232Z")
Questions
- How to clamp a date to the desired date range?
- How to enforce a date to be in a given date range?
clone
Clones the given Date object.
Type signature
(date: Date) => Date
Examples
const date = new new Date("2019-04-24T13:54:33.232Z");
const cloned = clone(date);
cloned !== date && cloned.valueOf() === date.valueOf();
// ⇒ true
Questions
- How to clone a Date object?
dateDiff
Computes a signed difference between two Date objects as milliseconds.
Type signature
(a: Date, b: Date) => number
Examples
dateDiff(new Date("2017-01-01T13:00:00.000Z"), new Date("2017-01-01T12:00:00.000Z"));
// ⇒ 3600000
Questions
- How to compute Date difference?
dateInRange
Checks if the given date is between the given date range (inclusive).
Type signature
(from: Date, to: Date) => (date: Date) => boolean
Examples
dateInRange(new Date("2018-06-10T12:00:00.000Z"), new Date("2018-06-20T12:00:00.000Z"))(new Date("2018-06-15T12:00:00.000Z"));
// ⇒ true
Questions
- How to check if a date is within a given date range?
dayRange
Returns a local day range at a particular Date.
Type signature
(date: Date) => Date[]
Examples
const date = new Date("2018-12-31T13:54:33.232Z");
dayRange(date);
// ⇒ [startOfDay(date), endOfDay(date)]
Questions
- How to find a date range of a given day?
daysInMonths
Returns an array of days in a particular months. Number of days in February varies if it is a leap year or not.
Type signature
(leapYear: boolean) => [number, number, number, number, number, number, number, number, number, number, number, number]
Examples
daysInMonths(false);
// ⇒ [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31]
daysInMonths(true);
// ⇒ [31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31]
Questions
- How to find out how many days are in a particular month?
- How to find out how many days there are in a leap year?
daysInYear
Calculates the number of days in a particular year. Varies by the leap year.
Type signature
(year: number) => 366 | 365
Examples
daysInYear(2019);
// ⇒ 365
daysInYear(2020);
// ⇒ 366
Questions
- How many days are in a particular year?
- How many days are in a leap year?
- How many days are in a common year?
displayTime
Displays padded time string.
Type signature
(source: [number, number, number], showSeconds: boolean) => string
Examples
displayTime([5, 12, 16], false);
// ⇒ 05:12
displayTime([5, 12, 16], true);
// ⇒ 05:12:16
Questions
- How to display padded time?
endOfDay
Returns a local Date of an end of the day at a particular Date.
Type signature
(date: Date) => Date
Examples
endOfDay(new Date("2018-12-31T13:54:33.232Z"));
// ⇒ new Date(new Date("2019-01-01T00:00:00.000Z").valueOf() + new Date("2018-12-31T13:54:33.232Z").getTimezoneOffset() * 60 * 1000)
Questions
- How to find a date of an end of a given day?
formatDate
Formats a given date as a simple YYYY-MM-DD string.
Type signature
(date: Date) => string
Examples
formatDate(new Date("2019-02-24T01:12:34"));
// ⇒ "2019-02-24"
Questions
- How to render a date in a YYYY-MM-DD format?
formatDateTime
Formats a given date as a simple YYYY-MM-DD HH:MM(:SS) string.
Type signature
(sourceDate: Date, showSeconds?: boolean) => string
Examples
formatDateTime(new Date("2019-02-24T01:12:34"));
// ⇒ "2019-02-24 01:12"
formatDateTime(new Date("2019-02-24T01:12:34"), true);
// ⇒ "2019-02-24 01:12:34"
Questions
- How to render a date in a YYYY-MM-DD HH:MM format?
- How to render a date in a YYYY-MM-DD HH:MM:SS format?
formatDuration
Formats a duration in milliseconds to a padded time string.
Type signature
(duration: number, showSeconds?: boolean) => string
Examples
formatDuration(26100000);
// ⇒ 07:15
formatDuration(26136000, true);
// ⇒ 07:15:36
Questions
- How to render a formatted duration?
formatTime
Formats a given date as a simple HH:MM(:SS) string.
Type signature
(date: Date, showSeconds?: boolean) => string
Examples
formatTime(new Date("2019-02-24T01:12:34"));
// ⇒ "01:12"
formatTime(new Date("2019-02-24T01:12:34"), true);
// ⇒ "01:12:34"
Questions
- How to render a date in a HH:MM format?
- How to render a date in a HH:MM:SS format?
fromDays
Converts the given day count to milliseconds.
Type signature
(days: number) => number
Examples
fromDays(1);
// ⇒ 86400000
Questions
- How to find how many milliseconds are in a given number of days?
fromHours
Converts the given hour count to milliseconds.
Type signature
(hours: number) => number
Examples
fromHours(1);
// ⇒ 3600000
Questions
- How to find how many milliseconds are in a given number of hours?
fromMinutes
Converts the given minute count to milliseconds.
Type signature
(minutes: number) => number
Examples
fromMinutes(1);
// ⇒ 60000
Questions
- How to find how many milliseconds are in a given number of minutes?
fromSeconds
Converts the given second count to milliseconds.
Type signature
(seconds: number) => number
Examples
fromSeconds(1);
// ⇒ 1000
Questions
- How to find how many milliseconds are in a given number of seconds?
joinDateTime
Joins a date-time pair into a date-time string.
Type signature
(date: string, time: string) => string
Examples
joinDateTime("2019-01-15", "13:54:33.232Z");
// ⇒ "2019-01-15T13:54:33.232Z"
Questions
- How to join date and time to get ISO-compliant date-time string?
leapYear
Detects if a given year is a leap year.
Type signature
(year: number) => boolean
Examples
leapYear(2020);
// ⇒ true
leapYear(2019);
// ⇒ false
Questions
- How to find if the given year is a leap year?
parseHourMinutePair
Parses HH:MM string into hours and minutes.
Type signature
(text?: string) => [number, number]
Examples
parseHourMinutePair("12:34");
// ⇒ [12, 34]
Questions
- How to parse time string into hours and minutes?
splitDateTime
Splits a date-time string into a date-time pair.
Type signature
(dateTimeString: string) => [string, string]
Examples
splitDateTime("2019-01-15T13:54:33.232Z");
// ⇒ ["2019-01-15", "13:54:33.232Z"]
Questions
- How to split ISO-compliant date-time string into a date and time pair?
startOfDay
Returns a local Date of a start of the day at a particular Date.
Type signature
(date: Date) => Date
Examples
endOfDay(new Date("2019-01-01T13:54:33.232Z"));
// ⇒ new Date(new Date("2019-01-01T00:00:00.000Z").valueOf() + new Date("2019-01-01T13:54:33.232Z").getTimezoneOffset() * 60 * 1000)
Questions
- How to find a date of the start of a given day?
subtractDays
Subtracts the given number of days from the given Date object.
Type signature
(sourceDate: Date, numberOfDays: number) => Date
Examples
subtractDays(new Date("2019-01-15T13:54:33.232Z"), 1);
// ⇒ new Date("2019-01-14T13:54:33.232Z")
Questions
- How to subtract days from a given date?
toDate
Extracts padded YYYY-MM-DD date string out of the given date object.
Type signature
(date: Date) => string
Examples
toDate(new Date("2019-01-15T12:00:00.000Z"));
// ⇒ "2019-01-15"
Questions
- How to get only the date from a Date object?
toDates
Converts the given array of values into Dates using the Date constructor.
Type signature
(xs: (string | number | Date)[]) => Date[]
Examples
toDates(["2019-01-15T13:54:33.232Z", new Date("2019-01-15T13:54:33.232Z").valueOf(), new Date("2019-01-15T13:54:33.232Z")]);
// ⇒ [new Date("2019-01-15T13:54:33.232Z"), new Date("2019-01-15T13:54:33.232Z"), new Date("2019-01-15T13:54:33.232Z")]
Questions
- How to convert an array of string and timestamps into an array of Date objects?
toDays
Converts milliseconds into days.
Type signature
(milliseconds: number) => number
Examples
toDays(86400000);
// ⇒ 1
Questions
- How to convert milliseconds into days?
toHours
Converts milliseconds into hours.
Type signature
(milliseconds: number) => number
Examples
toHours(3600000);
// ⇒ 1
Questions
- How to convert milliseconds into hours?
toISO
Returns an ISO-compliant date-time string.
Type signature
(x: Date) => string
Examples
toISO(new Date("2019-04-24T13:54:33.232Z"));
// ⇒ "2019-04-24T13:54:33.232Z"
Questions
- How to convert Date object to ISO-compliant date string?
toMinutes
Converts milliseconds into minutes.
Type signature
(milliseconds: number) => number
Examples
toMinutes(60000);
// ⇒ 1
Questions
- How to convert milliseconds into minutes?
toSeconds
Converts milliseconds into seconds.
Type signature
(milliseconds: number) => number
Examples
toSeconds(1000);
// ⇒ 1
Questions
- How to convert milliseconds into seconds?
valid
Checks if the given date is present and it is valid.
Type signature
(date?: unknown) => boolean
Examples
valid(new Date("2020-01-31T09:52:31.618Z"));
// ⇒ true
valid(new Date("2020-01-42:52:31.618Z"));
// ⇒ false
valid(new Date("test"));
// ⇒ false
valid(undefined);
// ⇒ false
Questions
- How to check if a Date is valid or not?
debug
assert
Asserts given conditions.
Type signature
(condition: boolean, callbackOrMessage?: (() => void) | string) => void;
export declare const throws: (f: () => void) => unknown | undefined;
export declare const assertNumber: (x?: unknown) => void;
export declare const assertInteger: (x?: unknown) => void;
export declare const assertByte: (x?: unknown) => void;
export declare const assertNormal: (x?: unknown) => void;
export declare const assertString: (x?: unknown, message?: string) => void;
export declare const assertIsDefined: (x?: unknown, message?: string) => void;
export default assert
Examples
assert(true === false);
// ⇒ TypeError("Assertion failed!")
Questions
- How to assert a condition?
- How to throw when a condition is not satisfied?
diff
Computes a deep difference between the two values (primitives, objects, arrays, etc.).
Type signature
(obj1?: unknown, obj2?: unknown) => DiffResult;
export default diff
Examples
diff({ a: 1 }, { a: 2 });
// ⇒ { a: { data: [1, 2], type: '~' }}
Questions
- How to compute a diff?
- How to compute a deep diff?
- How to compute a diff between two objects?
- How to compute a diff between two arrays?
encoding
base64url
decode
Decodes the given Base64URL back into a string.
Type signature
(text: string, context?: DecodeContext) => string
Examples
decode("PDw_Pz8-Pg");
// ⇒ "<<???>>"
Questions
- How to decode Base64URL?
decodeBytes
Decodes the given Base64URL back into a byte array.
Type signature
(text: string, context?: DecodeContext) => number[]
Examples
decodeBytes("w4Jnw6vCp20-bBsQfA");
// ⇒ [0xc2, 0x67, 0xeb, 0xa7, 0x6d, 0x3e, 0x6c, 0x1b, 0x10, 0x7c]
Questions
- How to decode Base64URL into a byte array?
encode
Encodes the given string into Base64URL.
Type signature
(text: string, context?: EncodeContext) => string
Examples
encode("<<???>>");
// ⇒ "PDw_Pz8-Pg"
Questions
- How to encode a string as Base64URL?
encodeBytes
Encodes the given bytes into Base64URL.
Type signature
(bytes: number[], context?: EncodeContext) => string
Examples
encodeBytes([0xc2, 0x67, 0xeb, 0xa7, 0x6d, 0x3e, 0x6c, 0x1b, 0x10, 0x7c]);
// ⇒ "w4Jnw6vCp20-bBsQfA"
Questions
- How to encode bytes as Base64URL?
fromBase64
Converts Base64 string into Base64URL one.
Type signature
(base64: string) => string
Examples
fromBase64("PDw/Pz8+Pg==");
// ⇒ "PDw_Pz8-Pg"
Questions
- How to convert Base64 to Base64URL?
toBase64
Converts Base64URL string into Base64 one.
Type signature
(base64Url: string) => string
Examples
toBase64("PDw_Pz8-Pg");
// ⇒ "PDw/Pz8+Pg=="
Questions
- How to convert Base64URL to Base64?
byteString
from
Converts a string to a byte array.
Type signature
(byteString: string) => number[]
Examples
from("PQR");
// ⇒ [80, 81, 82]
Questions
- How to convert a string into a byte array?
to
Coverts a byte array into a string.
Type signature
(bytes: number[]) => string
Examples
to([0x50, 0x51, 0x52]);
// ⇒ "PQR"
Questions
- How to convert a byte array to string?
file
validName
Checks if the given string is a valid Windows file name.
Type signature
(name: string) => boolean
Examples
validName("my:file.png");
// ⇒ false
validName("file.txt");
// ⇒ true
validName("../file.txt");
// ⇒ false
validName("COM1");
// ⇒ false
Questions
- How to find valid Windows file name?
- How to check if a given string is a legal/valid file name under Windows?
function
compose
Composes multiple functions into a higher-order one. Goes right to left.
Type signature
<T, TResult>(...fs: ((x: T) => T)[]) => (x: T) => T
Examples
compose(x => x * x, x => x + 1)(3);
// ⇒ 16
Questions
- How to compose functions?
constant
Returns the given constant no matter the input.
Type signature
<T>(x: T) => () => T
Examples
constant(3)("anything");
// ⇒ 3
Questions
- How to create a function that always returns the same value despite given arguments?
identity
Always return the given value.
Type signature
<T>(x: T) => T
Examples
identity(5);
// ⇒ 5
identity("test");
// ⇒ "test"
Questions
- How to use the identity function?
- Where and why is identity function useful?
memoize
Memoizes the function result so it is not computed for the same parameters. Uses deep equality.
Type signature
<TResult>(f: (...xs: unknown[]) => TResult) => (...args: unknown[]) => TResult
Examples
const f = x => { console.log(x); return x + 1; };
const memoized = memoize(f);
memoized(5);
memoized(5);
memoized(5);
memoized(3);
Questions
- How to memoize a function?
memoizeShallow
Memoizes the function result so it is not computed for the same parameters. Uses shallow equality.
Type signature
<TResult>(f: (...xs: unknown[]) => TResult) => (...args: unknown[]) => TResult
Examples
const f = ({ x }) => { console.log(x); return x + 1; };
const memoized = memoizeShallow(f);
memoized({ x: 5 });
memoized({ x: 5 });
memoized({ x: 5 });
memoized({ x: 3 });
Questions
- How to memoize a function with shallow equality?
memoizeWith
Memoizes the function result so it is not computed for the same parameters. Uses the given equality function.
Type signature
<T>(equals: (x: T[], y: T[]) => boolean) => <TResult>(f: (...xs: T[]) => TResult) => (...args: T[]) => TResult
Examples
const f = ({ x }) => { console.log(x); return x + 1; };
const memoized = memoizeWith((a, b) => a.x === b.x)(f);
memoized({ x: 5 });
memoized({ x: 5 });
memoized({ x: 5 });
memoized({ x: 3 });
Questions
- How to memoize a function with a custom equality function?
noOp
It does exactly nothing.
Type signature
() => void
Examples
noOp("anything");
// ⇒ undefined
Questions
- How to create a function that does nothing?
not
Inverts the given function result.
Type signature
(f: (...xs: unknown[]) => unknown) => (...args: unknown[]) => boolean
Examples
not(x > 10)(15);
// ⇒ true
Questions
- How to invert a boolean function?
pipe
Pipes an input through given functions.
Type signature
<T>(...fs: ((x: T) => T)[]) => (x: T) => T
Examples
pipe(x => x * x, x => x + 1)(3);
// ⇒ 10
Questions
- How to pipe an argument through a function?
when
Runs the given function only when the condition is met.
Type signature
(predicate: (...xs: unknown[]) => boolean) => (action: (...xs: unknown[]) => unknown) => (...args: unknown[]) => unknown
Examples
when(x => x > 0)(x => console.log(x))(5);
when(x => x > 0)(x => console.log(x))(-3);
Questions
- How to run a function only when a condition is satisfied?
whenTrue
Runs the given function only when the condition is exactly true.
Type signature
(action: (...xs: unknown[]) => unknown) => (...args: unknown[]) => unknown
Examples
whenTrue(x => console.log(x))(false);
when(x => x > 0)(x => console.log(x))(true);
Questions
- How to run a function only if its argument is true?
- How to execute function only if a variable is true?
is
array
Checks if the given argument is an array.
Type signature
(x?: unknown) => boolean
Examples
array([1, 2, 3]);
// ⇒ true
array({ a: 1 });
// ⇒ false
Questions
- How to check if a given value is an array?
boolean
Checks if the given value is a boolean.
Type signature
(x?: unknown) => x is boolean
Examples
boolean(false); // ⇒ true
boolean(1); // ⇒ false
Questions
- How to check if a given value is a boolean?
byte
Checks if the given value is a byte.
Type signature
(x?: unknown) => boolean
Examples
byte(128);
// ⇒ true
byte(325);
// ⇒ false
byte(65.5);
// ⇒ false
Questions
- How to check if a given value is a byte?
- How to check if a given number is a byte?
date
Checks if the given value is a Date object.
Type signature
(x?: unknown) => boolean
Examples
date(new Date());
// ⇒ true
date(123);
// ⇒ false
Questions
- How to check if a given value is a Date object?
defined
Checks if the given value is defined.
Type signature
(x?: unknown) => boolean
Examples
defined(undefined);
// ⇒ false
defined(null);
// ⇒ true
defined(0);
// ⇒ true
defined({ a: 1 });
// ⇒ true
Questions
- How to check if a given value is defined?
- How to check if a given value is not undefined?
function
Checks if the given value is a function.
Type signature
(x?: unknown) => x is Function
Examples
_function(x => x + 5);
// ⇒ true
Questions
- How to check if a given value is a function?
integer
Checks if the given value is an integer.
Type signature
(x?: unknown) => boolean
Examples
integer(5);
// ⇒ true
integer(32.5);
// ⇒ false
Questions
- How to check if a given value is an integer?
- How to check if a given number is an integer?
nonNullable
Checks and asserts the given value is not null or undefined.
Type signature
<T>(val: T) => val is NonNullable<T>
Examples
nonNullable(null);
// ⇒ false
nonNullable(undefined);
// ⇒ false
nonNullable(false);
// ⇒ true
nonNullable({ a: 1 });
// ⇒ true
Questions
- How to check if a given value is non-nullable?
- How to check if a given value is not null?
- How to check if a given value is not undefined?
normal
Checks if the given value is a number in a normal range [0, 1].
Type signature
(x?: unknown) => boolean
Examples
normal(0.75);
// ⇒ true
normal(-1);
// ⇒ false
normal(2.5);
// ⇒ false
Questions
- How to check if a given value is in 0 to 1 inclusive range?
number
Checks if the given value is a number.
Type signature
(x?: unknown) => boolean
Examples
number(0 / 0);
// ⇒ false
number(15.6);
// ⇒ true
Questions
- How to check if a given value is a valid number?
- How to check if a given value is not NaN?
- How to check if a given value is finite?
object
Checks if the given value is an object.
Type signature
(x?: unknown) => boolean
Examples
object({ a: 1, b: 2 });
// ⇒ true
object([1, 2, 3]);
// ⇒ false
Questions
- How to check if a given value is an object?
string
Checks if the given value is a string.
Type signature
(x?: unknown) => x is string
Examples
string("Test");
// ⇒ true
string(['T', 'e', 's', 't']);
// ⇒ false
Questions
- How to check if a given value is a string?
math
add
Adds two values.
Type signature
(a: number, b: number) => number
Examples
add(3, 5);
// ⇒ 8
Questions
- How to add two values?
average
Calculates the average of the given array of numbers.
Type signature
(xs?: number[]) => number
Examples
average([2, 4, 15]);
// ⇒ 7
Questions
- How to compute the average of an array?
ceilToNearestPowerOfTwo
Finds the nearest power of two greater or equal to the given value.
Type signature
(x: number) => number
Examples
ceilToNearestPowerOfTwo(345);
// ⇒ 512
Questions
- How to get the nearest power of two greater or equal to the given value?
clamp
Clamps the given value to the given range.
Type signature
(min: number, max: number) => ((x: number) => number)
Examples
clamp(0, 10)(5);
// ⇒ 5
clamp(0, 10)(-5);
// ⇒ 0
clamp(0, 10)(15);
// ⇒ 10
Questions
- How to clamp value to the desired range?
- How to enforce a value to be in a given range?
clampNormal
Clamps the given value to the [0, 1] range.
Type signature
(x: number) => number
Examples
clampNormal(0.5);
// ⇒ 0.5
clampNormal(-0.5);
// ⇒ 0
clampNormal(1.5);
// ⇒ 1
Questions
- How to clamp value to be in 0 to 1 inclusive range?
- How to clamp value to be in the normal range?
clampPercentage
Clamps the given value to the [0, 100] range.
Type signature
(x: number) => number
Examples
clampPercentage(50);
// ⇒ 50
clampPercentage(-50);
// ⇒ 0
clampPercentage(150);
// ⇒ 100
Questions
- How to enforce a percentage be between 0% and 100%?
delta
Calculates the absolute distance between given values.
Type signature
(a: number, b: number) => number
Examples
delta(-3, 5);
// ⇒ 8
Questions
- How to calculate an absolute distance between two numbers?
inRectangleRange
Checks if the given value is in the rectangular range of [0, width] and [0, height]
Type signature
(width: number, height: number) => ((x: number, y: number) => boolean)
Examples
inRectangleRange(50, 100)(25, 50);
// ⇒ true
inRectangleRange(50, 100)(-25, 50);
// ⇒ false
Questions
- How to check if a point is inside a rectangle defined by width and height?
lerp
Linearly interpolates two given values by the normal value of their distance.
Type signature
(t: number) => ((a: number, b: number) => number)
Examples
lerp(0.5)(0, 10);
// ⇒ 5
lerp(0)(0, 10);
// ⇒ 0
lerp(1)(0, 10);
// ⇒ 10
Questions
- How to linearly interpolate between two values?
- How to interpolate two numbers?
maximumBy
Calculates the maximum by a given selector.
Type signature
(f: (x: number) => number) => ((xs: number[]) => number)
Examples
maximumBy(({ age }) => age)([{ age: 13 }, { age: 20 }, { age: 7 }, { age: 18 }]);
// ⇒ { age: 20 }
Questions
- How to find a maximum element by a given function?
median
Calculates the median of the values. If there is an even number of items, the average of the middle ones is returned.
Type signature
(xs?: number[]) => number | undefined
Examples
median([-5, 3, 2, 29, 43]);
// ⇒ 3
Questions
- How to compute a median of an array?
minMax
Calculates the minimum and maximum value of the two given values.
Type signature
([a, b]: [number, number]) => [number, number]
Examples
minMax([5, 3]);
// ⇒ [3, 5]
minMax([3, 5]);
// ⇒ [3, 5]
Questions
- How to get ordered values where the lower is the first and the higher is the second?
sameSign
Checks if all the given values have the same sign.
Type signature
(xs: number[]) => boolean
Examples
sameSign([-1, -2, -3]);
// ⇒ true
sameSign([1, 2, -3]);
// ⇒ false
Questions
- How to check if all values have the same sign?
sign
Calculates the sign of the value and returns -1 for negative values, 1 for positive values and 0 for zeros.
Type signature
(x: number) => number
Examples
sign(3);
// ⇒ 1
sign(-5);
// ⇒ 5
sign(0);
// ⇒ 0
sign(-0);
// ⇒ 0
Questions
- How to get a sign of a number?
standardDeviation
Calculates the standard deviation of the given array of numbers.
Type signature
(xs: number[], origin?: number) => number
Examples
standardDeviation([96, 81, 68, 79, 23, 13, 13, 59, 44, 86]);
// ⇒ (2 * Math.sqrt(10922 / 5)) / 3
Questions
- How to compute a standard deviation of an array?
subtract
Subtracts two values.
Type signature
(a: number, b: number) => number
Examples
subtract(3, 5);
// ⇒ -2
Questions
- How to subtract two numbers?
object
any
Checks if the given object is present and it is not empty (contains at least one entry).
Type signature
<T>(xs?: GenericObject<T>) => boolean
Examples
any({ a: 1, b: 2, c: 3 });
// ⇒ true
any({ });
// ⇒ false
any(null);
// ⇒ false
any(undefined);
// ⇒ false
Questions
- How to check if an object is not empty?
- How to check if an object contains some values?
- How to check if an object is not null or undefined?