README

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 }

@koober/std

Usage no npm install needed!