Kerosene

yarn add @kablamo/kerosene

It's like lodash, but it's ours.

Available functions

Grouped by input data type

Array

contains

Returns true if all the values in subset are present in superset.

Otherwise, returns false

You can pass in an iteratee as the third argument, like in lodash.

product

Returns the cartesian product of the source arrays.

remove

Immutably removes all instances of needle from haystack.

Returns an empty array if haystack was empty.

Returns a new array that is referentially-not-equal to haystack even if needle is not in haystack

toggle

Immutably adds the target item to the target array if it's not already in there.

Otherwise, immutably removes that item from the array.

Datetime

SECOND

Milliseconds in one second (1,000).

MINUTE

Milliseconds in one minute (60,000).

HOUR

Milliseconds in one hour (3,600,000).

DAY

Milliseconds in one 24-hour day (86,400,000).

Month

A 0-indexed enum for the months of the Gregorian Calendar.

DayOfWeek

A 0-indexed enum for the days of the week, starting at Sunday.

getCalendarWeeks(month, startOfWeek)

Returns a 4-, 5-, or 6-tuple of calendar weeks (7-tuples of Dates) for the month of the Date provided (according to the timezone of the environment).

isAfterDate(date, dateToCompare)

Returns whether the day of date is after the day of dateToCompare.

isBeforeDate(date, dateToCompare)

Returns whether the day of date is before the day of dateToCompare.

isSameOrAfterDate(date, dateToCompare)

Returns whether the day of date is the same or after the day of dateToCompare.

isSameOrBeforeDate(date, dateToCompare)

Returns whether the day of date is the same or before the day of dateToCompare.

Error

catchAbortError(error)

Function that will re-throw any non-AbortError.

isAbortError(error)

Returns whether the provided error is an "AbortError" by name.

Fetch

isNetworkError(error)

Returns whether or not error is a fetch() Network Error, accounting for browser differences.

Can be used to detect when the network is not available, although may be falsely triggered by CORS.

transform(response)

Returns a Promise which transforms the body of a fetch() request according to content type header.

transformAndCheckStatus(response)

Returns a Promise which transforms the body of a fetch() request according to content type header and rejects if the status is not 2xx.

If the status is in the 4XX range, it will throw a ClientError.

If the status is in the 5XX range, it will throw a ServerError.

All other non-2XX statuses are thrown as an HttpError.

Function

timeout(delay, { signal? }?)

Returns a Promise which resolves after the specified delay in milliseconds.

waitForEventLoopToDrain

Returns a Promise which resolves after the current event loop drains.

Iterable

intersects(iterable1, iterable2)

Returns whether any elements are shared between iterable1 and iterable2.

isEquivalentSet(iterable1, iterable2)

Returns whether iterable1 is an equivalent set to iterable2.

Math

floor/round/ceil

Like the corresponding Math functions of the same name, but takes a second parameter precision which allows for more/less precise rounding.

For example, round(1505, 10) === 1510 (round to the nearest 10).

clamp(min, value, max)

Returns a value clamped between min and max.

Similar to the CSS clamp() function, this is resolved as Math.max(min, Math.min(value, max)).

divmod(dividend, divisor)

Returns a 2-tuple containing quotient and remainder for the integer division of dividend by divisor.

Similar to the Python divmod function.

isNegative

Returns whether or not the provided value is negative, considering positive and negative zero separately

toDegrees

Converts the value in radians to degrees.

toRadians

Converts the value in degrees to radians.

toSignificantFigures(value, figures)

Returns the provided value rounded to the number of significant figures provided.

Promise

Deferred<T>

Deferred is a class that allows a Promise to be created in advance of the code that will resolve/reject it. Deprecated in favour of Promise.withResolvers<T>().

mapSeries(items, iteratee)

Maps over items with a promise-returning iteratee in series.

String

caseInsensitiveEquals

Returns true if the two input strings are the same in all but casing.

Returns false otherwise.

elide

Chop the input string off at maxLength if it is too long.

Defaults to adding a ... if chopped, you can pass in any string to change what the chopped string gets elided with.

The chopped string will not be longer than maxLength, even with the custom elider-string.

getRandomString

It's a good-enough random string for non-cryptographic purposes.

Always 32 characters long.

isOnlyWhitespace

Returns true if the input string contains nothing other than whitespace.

This includes newlines.

Returns false otherwise

parseSearch(search)

Deprecated in favour of URLSearchParams.

See https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams or https://nodejs.org/api/url.html#url_class_urlsearchparams for documentation.

removeLineBreaks

Replaces all newlines in the input string with single spaces.

Returns the original string if no newlines were present.

replaceAll

Replace all instances of needle in haystack with newNeedle

toTitleCase

Converts a provided input to title case according to a list of lowercaseWords (default provided) which remain lowercase, unless they occur at the beginning or end.

TITLE_CASE_LOWERCASE_WORDS

The default list of lowercaseWords is exported as such.

Types

AngleDegrees

Marked type for an angle that should be specified in degrees

AngleRadians

Marked type for an angle that should be specified in radians

AnyConstructor

Alias for any constructor function

AnyFunction

Alias for any function

BrandType<T, Brand>

Brands type T with the provided Brand

MarkType<T, Brand>

Marks type T with the provided Brand. Differs from BrandType in that the branding is optional.

OpaqueType<T, Brand>

Brands type T as an opaque type (no runtime effect). To use as T, consumers must explicitly unwrap the value.

Underlying<T>

For a branded type T, provides the underlying type

brandT<BrandType>(underlying)

Returns the value underlying branded according to the type parameter

opaqueT<OpaqueType>(underlying)

Returns the value underlying as the OpaqueType specified as the type parameter

underlyingT<Branding>(branded)

Unwraps the branded type to return the underlying value

DeepMutable<T>

Recursively traverses T to make all properties mutable

DeepNonNullable<T>

Recursively traverses T to make all properties Required and NonNullable.

DeepPartial<T>

Recursively traverses T to make all properties optional.

ElementType<TCollection>

Infers the element type T from T[], Set<T>, Map<any, T>, or { [key: string]: T }.

Entries<T>

Infers the union of all object entry tuples for type T.

DistributiveOmit<T, K>

Like Omit<T, K>, but distributes across all members of a union.

DistributivePick<T, K>

Like Pick<T, K>, but distributes across all members of a union.

InferrableTupleOf<T>

Utility type which allows a generic constraint to be inferred as a tuple of T instead of an array of T. Deprecated in favour of const type parameters.

IsUnknownOrAny<T>

Utility type which returns a boolean type for whether T is unknown or any

isRecord<T>

Custom type predicate which checks whether a type is assignable to Record<PropertyKey, unknown>. If the type T of obj is known (not unknown or any), then the type will be narrowed.

KeysOfUnion<T>

Like keyof T, but distributes across all members of unions to include all keys (including those not shared by all members).

KeysWhere<T, TValue>

Creates a union of all keys of T where T[key] has type TValue.

MergedUnion<T>

From a union type T, allows properties which are not shared by all members to be undefined.

Mutable<T>

Removes the readonly modifier from all properties in T.

Overloads<T>

From an overloaded function T, infer each overload as a tuple element.

OverloadedParameters<T>

For an overloaded function T, infer the union of parameters for all overloads.

OverloadedReturnType<T>

For an overloaded function T, infer the union of return types for all overloads.

OverloadedReturnTypeWhen<T, P>

For an overloaded function T, infer the return type for the specific overload when parameters match P.

PickBy<T, TValue>

Creates a new type from T including only keys where the value is assignable to type TValue.

RequireAtLeastOne<T>

Creates a new type from T where at least one key is required and all others are optional.

RequiredKeys

Utility type which acts like keyof T, but only includes required keys

RequireKeys<T, K>

Creates a new type from T where keys K are marked as required