@koober/std

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 [e-mail]

Changelog

1.0.0-rc.54 (2021-09-01)

Features

• std: add throwError function (5cbc2d4)