@bruyland/utilities v0.0.74

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

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