Koober Standard Library (@koober/std)

Standard library

About the project

std is a library for typed functional programming in TypeScript. It focuses on strong typing, purity, simplicity and restricted set of functionalities. Advanced functional programming patterns, immutability should not be achieved if it degrades significantly type safety and simplicity.

| | Balance | | |-----------------------------: | :-----: | :-------------------------------| | Loose typing | □□□□□□■ | Strong typing | | Impure, Mutable | □□□□□■□ | Pure, Immutable | | Simple Functional Programming | □□■□□□□ | Advanced Functional Programming | | Lean | □□■□□□□ | Complete |

Installation

npm install @koober/std

Usage

Enforce STD to write better code

| VanillaJS | STD | Explanation | |--------------------------------|--------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | null, undefined | Option | Stop spending time choosing between undefined and null. Based on Microsoft standard, undefined (== Option.None) is preferred. | | throw new Error() | return Result.Error(new Error()) | Error throwing / Promise rejection is a mechanism that should only be used to stop the execution of a program. When a computation represents an expected failure (ex: parsing, data fetching), Result should be used. | | Promise | Task.Async | Task.Async is like a Promise but lazily evaluated. It has numerous advantages (composable, etc). See Article | | N/A | Time, Duration | Tagged types that makes the unit of time explicit (milliseconds). Some libraries could use seconds or minutes implicitly which is confusing | | setTimeout(fn, ms) | Task.andThen(Time.delay(ms), fn) | setTimeout is impure, create a task that will run after Time.delay. | | Date.now | Time.now | Date.now is impure, use Time.now that is a Task.Sync. | | console.debug | Console.debug | console.debug is impure, use Console.debug that is a Task.Sync. | | Math.random | Random.number | Math.random is impure, use Random.number that is a Task.Sync. | | UUID, ... | Task.Sync | More impure function, wrap them in a Task.Sync() | | N/A | Int | A tagged type that narrows number to only the safe integer values | | [].map, [].filter, ... | Array.map, Array.filter, ... | Array module contains all immutable operations on arrays. |

Example

import { Result, runTask, Console } from '@koober/std';

function parseNumber(expr: string) {
  const parsed = Number(expr);

  // - Return a immutable Result object
  // - Avoid throwing error because impure
  // - Avoid using NaN because the error case is implicit in the typing
  return Number.isNaN(parsed) ? Result.Ok(parsed) : Result.Error('NotANumber');
}

export function main() {
  const parsed = parseNumber('1.1'); // Result.Ok(1.1)
  const computed = Result.map(parsed, (amount) => amount + 2); // Result.Ok(3.1)

  // Lazy operation that will display in console the computed result when evaluated
  return Console.debug(computed);
}

// runTask is impure and should be put at the edge of the program
runTask(main()); // prints { _type: 'Result/Ok', value: 3.1 }

License

MIT © Julien Polo [email protected]