@bruyland/utilities

Medisch Labo Bruyland Utility library

Origin

Some parts of this library have been copied from the - no longer maintained - radash library, the typing resolution of the radash functions has been greatly improved while the functionality has mostly remained the same.

Documentation

Use the radash documentation for these functions

Function	Group	Description
tryit	async	try an async function without forking the control flow
unique	array	Given a list of items returns a new list with only unique items
boil	array	Go through a list of items, starting with the first item, and comparing with the second. Keep the one you want then compare that to the next item in the list with the same.
select	array	performs a filter and a mapper inside of a reduce
max	array	gets the greatest value from a list
min	array	gets the smallest value from a list
range	array	creates a generator that will produce an iteration through a range of numbers
list	array	creates a list of given start, end, value, and step parameters
mapKeys	object	map over all the keys of an object to return a new object with altered property names
mapValues	object	returns a new object with all the values mapped through the toValue function
mapEntries	object	combines mapKeys and mapValues in one pass
clone	object	creates a shallow copy
get	object	get a value from a nested object using the JSON path
set	object	sets a value on an object using a JSON path
crush	object	flattens a deep object to a single demension, converting the keys to JSON path notation
construct	object	the opposite of crush
listify	object	returns an array with an item for each entry in the object
pick	object	given an object and a list of keys in the object, returns a new object with only the given keys
omit	object	omits a list of properties from an object
isSymbol	type
isArray	type
isObject	type
isPrimitive	type	Checks if the given value is primitive
isFunction	type
isString	type
isInt	type
isFloat	type
isNumber	type
isDate	type
isPromise	type
isEmpty	type
isEqual	type
toFloat	number
toint	number

non-radash functions

try helpers

type Left<E = Error> = [E, undefined]
type Right<T = any> = [undefined, T]
type Either<E = Error, T = any> = Left<E> | Right<T>
type Task<E = Error, T = any> = Promise<[E, undefined] | [undefined, Awaited<T>]>
type TaskOrEither<E = Error, T = any> = T extends Promise<any> ? Task<E, T> : Either<E, T>

const isLeft = <E = Error, T = any>(either: Either<E, T>): boolean =>
  isArray(either) && either[0] !== undefined
const isRight = <E = Error, T = any>(either: Either<E, T>): boolean =>
  isArray(either) && either[0] === undefined
const left = <E = Error>(either: Either<any, E>): E => either[0] as E
const right = <T = any>(either: Either<Error, T>): T => either[1] as T

handle

delegates handling of errors to a handler function

// signature
const result = handle<T,E>(
  fn: (...args: Args) => T,
  handler: (error: E) => void,
)

// use
const errorHandler = (error) => {
  // do whatever stuff you have to do for handling the error
}
handle(errorHandler, () => {
  //... do stuff that may or may not throw
  // where different errors can all be handled 
  // with the same error handler
})(...args)
// or
const result = handle(errorHandler, (...args) => {
  // some code that generates a result
  // the function will return undefined
  // if an error was throw and handled
})

Works both with sync ans async functions

diff

Calculates the differences between two object with equal types.

diff returns an object with a change field and a differences field. change can be add, update, delete or none. The differences field will contain an object detailing the differences between the first and the second parameter.

example

const old = { species: 'cat', name: 'Eline', age: 10, weight: 4.5 }
const _new = { species: 'cat', name: 'Eline', age: 11, weight: 4.2 }

const d1 = diff(old, _new)
/*{
  change: 'update',
  differences: { old: { age: 10 }, new: { age: 11 } }
}*/

const d2 = diff(undefined, _new, { reportOnAdd: ['name', 'age'] })
/*
{ change: 'add', differences: { name: 'Eline', age: 11 } }
*/

const d3 = diff(undefined, _new, { reportOnAdd: ['name', 'species'] })
/* 
{ change: 'add', differences: { name: 'Eline', species: 'cat' } }
*/

The layout of the third parameter (options) is

interface DiffOptions<T> {
  ignoreOnUpdate?: (keyof T)[]
  reportOnAdd?: (keyof T)[]
  reportOnDelete?: (keyof T)[]
  aName?: string
  bName?: string
}

• ignoreOnUpdate: the difference of the fields with these name will not be included in the differences object
• ignoreOnUpdate: only these fields will be reported when an add operation was detected. All fields will be reported when ignoreOnUpdate is []
• reportOnDelete: only these fields will be reported when an delete operation was detected. All fields will be reported when ignoreOnUpdate is []
• aName and bName: names for the objects in the differences object. By default, a is named 'old' and b is named 'new'

update

Chainable object updater that reports the changes made to the object.

update will return the same differences object like the diff function. The differenc being that update mutates the origional object in place. The same options can be used to control the reporting.

example

const updates = old.update({ age: 9, weight: 4.1 }, { alwaysReport: ['name'], ignoreOnUpdate: ['weight'] })
/*
{ old: { age: 10, name: 'Eline' }, new: { age: 9 } }
*/

The updates object can be passed from one call to another, new content will be added to this object with every call.

Library template

created acording to https://dev.to/0xkoji/create-a-npm-package-template-with-typescript-and-tsup-328n