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.
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
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