# @apoyo/std

> Typescript utility library

Latest version **0.1.0** (published 2023-02-03) · MIT license · 0 weekly downloads

## Install

```sh
npm install @apoyo/std
pnpm add @apoyo/std
yarn add @apoyo/std
bun add @apoyo/std
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.0 |
| Published | 2023-02-03 |
| First published | 2021-02-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 170.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 11 |
| Author | Sascha Braun |
| Maintainers | sascha245 |
| Keywords | utils, functional, fp, pipable, typescript |

## Links

- npm: https://www.npmjs.com/package/@apoyo/std
- Repository: https://github.com/neoxia/apoyo
- Homepage: https://github.com/neoxia/apoyo/tree/master/packages/std
- npm.io page: https://npm.io/package/@apoyo/std

## Alternatives

- [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads
- [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads
- [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads
- [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads
- [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K weekly downloads

## Recent versions

- 0.1.0 (latest) — 2023-02-03
- 0.0.15 — 2022-07-05
- 0.0.14 — 2022-06-27
- 0.0.13 — 2022-06-25
- 0.0.12 — 2022-01-09
- 0.0.11 — 2021-10-23
- 0.0.10 — 2021-09-17
- 0.0.9 — 2021-09-03
- 0.0.8 — 2021-07-12
- 0.0.7 — 2021-06-04
- 0.0.6 — 2021-05-28
- 0.0.5 — 2021-05-09
- 0.0.4 — 2021-05-02
- 0.0.3 — 2021-04-27
- 0.0.2 — 2021-03-07
- … 1 more at https://npm.io/package/@apoyo/std/versions

## README

# Apoyo - Std

[![npm version](https://badgen.net/npm/v/@apoyo/std)](https://www.npmjs.com/package/@apoyo/std)
[![build size](https://badgen.net/bundlephobia/min/@apoyo/std)](https://bundlephobia.com/result?p=@apoyo/std)
[![three shaking](https://badgen.net/bundlephobia/tree-shaking/@apoyo/std)](https://bundlephobia.com/result?p=@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 <s>copied</s> **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:

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

- Execute `Promise`s in sequence or concurrently:

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

- Accumulate results without throwing:

```ts

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

---
_Source: https://npm.io/package/@apoyo/std · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
