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 Array
s and Record
s, 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
Promise
s 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...