std

Apoyo - Std

Warning: This package is still in development and features may still change, be renamed or removed.

However, we would appreciate any feedback you have on how to improve this library:

• Which features are missing?
• Which features are hard to understand or unnecessary?
• Which features need to be improved?

Installation

npm install @apoyo/std

Motivation

Today, there exists a huge variety of utility libraries in the JS ecosystem: underscore, lodash, ramda, etc...

While these libraries may be great, they don't fit my needs and are missing a lot of utilities I require in my day by day work.

Pipeable: underscore or lodash utilities are not pipeable, which means combining multiple operations requires a lot of temporary variables, which harms the code quality.

Typescript: None of the above tools have been written specifically for Typescript, which means some functions are hard to type or don't play nicely with Typescript at all.

Three-shaking: The above libraries don't have great out-of-the-box Tree-shaking capabilities.

Content: These libraries mainly cover utilities for Arrays and Records, whis means you will have to install other packages to cover missing utilities:

• A package for custom errors / improved error handling.
• A package for Promise utilities, to execute for example Promises in concurrence / in sequence
• A package to accumulate Results without throwing
• Etc...

Goal

This library has a few main goal:

• Avoid dependency hells, by not having to install a multitude of utility packages required to do common tasks.

• Avoid any naming conflicts by putting all utilities related to a data-structure in their respective "barrel" export.

• Ease of usage: While large, the library should be easy to read and learn.

Modules

• Arr containing Array utilities
• Dict containing Record utilities
• Str containing String utilities
• Err containing Error utilities
• Prom containig Promise utilities
• Task containing lazy Promises utilities (type Task<A> = () => Promise<A>)
• Result which can represent the failure or success of an operation (type Result<A,E> = Ok<A> | Ko<E>)

Honorable mentions

fp-ts:

This library has been heavily inspired by fp-ts, and has re-implemented a lot of useful concepts (Results, Tasks, Option, Ord, pipe, etc...)

However, fp-ts is unfortunaly too complicated to use and doesn't always integrate well with existing code. As such, while this library may have a few similarities, @apoyo/std has been heavily simplified for easier usage.

v-error: The Err module has been heavily inspired by the way you chain errors with v-error. However, we didn't need the "printf" style messages formatting and decided to rather use "mustache" styled messages.

pupa: The Str module a small template function based on this package.

escape-goat: The Str module also re-integrates the small htmlEscape and htmlUnescape functions, which have been copied inspired by this package.

p-limit: This library is known for it's capabilities to execute at maximum X promises at once. The Task module implements it's own concurrence and sequence functions, allowing you to achieve the same without this dependency.

enum-for: We re-used the 3 mentionned lines in our Enum module

Examples

• Chaining errors:

const users = await pipe(
  findUsers(),
  Prom.mapError(Err.chain('findUsers failed'))
)

• Execute Promises in sequence or concurrently:

await pipe(
  tasks,
  Task.concurrent(4),
  Task.run
)

• Accumulate results without throwing:

const operation = (value) => {
  if (value < 0) {
    throw new Error('number should be positive')
  }
  return value
}

const [ok, ko] = pipe(
  [1,-2,3],
  Arr.map(Result.tryCatchFn(operation)),
  Arr.separate
)

expect(ok).toEqual([1,3])
expect(ko).toEqual([-2])

• And more...