diff --git a/.gitignore b/.gitignore index 9413660..e476f78 100644 --- a/.gitignore +++ b/.gitignore @@ -19,3 +19,4 @@ interface/* *.js *.js.map .cursorrules +site/* diff --git a/README.md b/README.md index 2230347..5829867 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,8 @@ KudoJS is a small utility library with a collection of popular Algebraic Data Types and Helper functions to help you write code in a functional programming style in Javascript. +[KudoJS Documentation](https://ritesh404.github.io/kudojs/) + ### Installation Install and save KudoJS as a dependency in your current project diff --git a/docs/README.md b/docs/README.md index 807c9a6..4e2c31d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,29 +1,34 @@ -# KudoJS Docs +# KudoJS Documentation +KudoJS is a small utility library with a collection of popular Algebraic Data Types and Helper functions to help you write code in a functional programming style in Javascript. -* See [Helper Functions](helper-functions.md) for documentation on all the methods in the kudoJS.* namespace. +## Overview +- [Helper Functions](helper-functions.md) - Documentation for all utility functions in the `kudoJS.*` namespace +- [ADT Documentation](#kudojs-algebraic-data-types) - Detailed documentation for each ADT implementation -### KudoJS Algebraic Data Types +### Algebraic Data Types (ADTs) -ADTs under the kudoJS.* namespace. All of the data types are compatible with the [Fantasy Land Specifications](https://github.com/fantasyland/). For the full documentation of each data type refer to the following: +ADTs under the kudoJS.\* namespace. All of the data types are compatible with the [Fantasy Land Specifications](https://github.com/fantasyland/) -* [`kudoJS.Pair`](pair.md) -* [`kudoJS.Maybe`](maybe.md) -* [`kudoJS.Either`](either.md) -* [`kudoJS.Task`](task.md) -* [`kudoJS.Reader`](reader.md) -* [`kudoJS.State`](state.md) +- [`kudoJS.Identity`](identity.md) - Type for handling pure values +- [`kudoJS.Pair`](pair.md) - Tuple type for handling two values +- [`kudoJS.Maybe`](maybe.md) - Type for handling nullable values safely +- [`kudoJS.Either`](either.md) - Type for handling branching and error cases +- [`kudoJS.Task`](task.md) - Type for handling asynchronous computations +- [`kudoJS.Reader`](reader.md) - Type for handling dependency injection +- [`kudoJS.State`](state.md) - Type for handling stateful computations -### Summary +## ADT Reference -| ADT | Constructors | Static Methods | Instance Methods | -| ------------- |:-------------:|:-----------------:| ----:| -| `kudoJS.Pair` | `Pair`, `of` || `equals`, `concat`, `fst`, `snd`, `ap`, `getValue`, `map`, `bimap`, `chain`, `swap`, `toString` | -| `kudoJS.Maybe` | `of`, `Just`, `Nothing`, `zero`, `fromNullable`, `withDefault` | `catMaybes`, `isNothing`, `isJust` | `equals`, `ap`, `alt`, `map`, `chain`, `toString`, `getValue`, `isNothing`, `isJust` | -| `kudoJS.Either` | `of`, `Left`, `Right`, `fromNullable`, `withDefault` | `try`, `isLeft`, `isRight` | `equals`, `ap`, `getValue`, `map`, `bimap`, `chain`, `swap`, `toString`, `isLeft`, `isRight` | -| `kudoJS.Task` | `Task`, `of`, `rejected` | | `fork`, `concat`, `ap`, `getValue`, `map`, `chain`, `toPromise`, `toString`| -| `kudoJS.Reader` | `Reader`, `of`, `ask` | | `runWith`, `ap`, `getValue`, `map`, `chain`, `toString`| -| `kudoJS.State` | `State`, `of`, `get`, `put` | | `runWith`, `execWith`, `evalWith`, `ap`, `getValue`, `map`, `chain`, `toString`| +| ADT | Constructors | Static Methods | Instance Methods | +| ---------- | :------------------------------------------------------------: | :--------------------------------: | ----------------------------------------------------------------------------------------------: | +| `Identity` | `Identity`, `of` | | `equals`, `concat`,`ap`, `getValue`, `map`,`chain`, `toString` | +| `Pair` | `Pair`, `of` | | `equals`, `concat`, `fst`, `snd`, `ap`, `getValue`, `map`, `bimap`, `chain`, `swap`, `toString` | +| `Maybe` | `of`, `Just`, `Nothing`, `zero`, `fromNullable`, `withDefault` | `catMaybes`, `isNothing`, `isJust` | `equals`, `ap`, `alt`, `map`, `chain`, `toString`, `getValue`, `isNothing`, `isJust` | +| `Either` | `of`, `Left`, `Right`, `fromNullable`, `withDefault` | `try`, `isLeft`, `isRight` | `equals`, `ap`, `getValue`, `map`, `bimap`, `chain`, `swap`, `toString`, `isLeft`, `isRight` | +| `Task` | `Task`, `of`, `rejected` | | `fork`, `concat`, `ap`, `getValue`, `map`, `chain`, `toPromise`, `toString` | +| `Reader` | `Reader`, `of`, `ask` | | `runWith`, `ap`, `getValue`, `map`, `chain`, `toString` | +| `State` | `State`, `of`, `get`, `put` | | `runWith`, `execWith`, `evalWith`, `ap`, `getValue`, `map`, `chain`, `toString` | ---- \ No newline at end of file +--- diff --git a/docs/either.md b/docs/either.md index 7e48023..dcfa61f 100644 --- a/docs/either.md +++ b/docs/either.md @@ -1,187 +1,204 @@ ## Either -Either is a monad and can be used as a generic structure for a type with two possibilities, a Left a or a Right b. It represents the logical disjunction between `a` and `b` -A common use of this structure is to handle things like error handling and things that may fail and when you want to provide additional information on the failure. It is used to represent a value which is either correct or an error. As a convention the Left constructor is used to hold an error value and the Right constructor is used to hold a correct value. This sort of a structure forces handling of failures to be explicit, and avoids the problems associated with throwing exceptions. +`Either` is a monad and can be used as a generic structure for a type with two possibilities: a **Left a** or a **Right b**. It represents the logical disjunction between `a` and `b`. -**Implements:** [BiFunctor](https://github.com/fantasyland/fantasy-land#bifunctor), [Monad](https://github.com/fantasyland/fantasy-land#monad), [Setoid](https://github.com/fantasyland/fantasy-land#setoid) +A common use of this structure is to handle error cases and situations where a computation might fail, while also providing additional information about the failure. It is used to represent a value that is either correct or an error. By convention, the **Left** constructor is used to hold an error value, and the **Right** constructor is used to hold a correct value. This structure forces explicit handling of failures and avoids the problems associated with throwing exceptions. -* [Either](#Either) - * [.of](#Either.of) - * [.Right](#Either.Right) - * [.Left](#Either.Left) - * [.fromNullable](#Either.fromNullable) - * [.withDefault](#Either.withDefault) - * [.swap()](#Either.swap) - * [.try(f)](#Either.try) - * [.bimap(e, fl, fr)](#Either.bimap) - * [.isLeft()](#Either.isLeft) - * [.isRight()](#Either.isRight) - * [.equals(n)](#Either.equals) - * [.map(f)](#Either.map) - * [.bimap(fl, fr)](#Either.bimap) - * [.chain(f)](#Either.chain) - * [.swap()](#Either.swap) - * [.isLeft(e)](#Either.isLeft) - * [.isRight(e)](#Either.isRight) - * [.ap(j)](#Either.ap) - * [.getValue()](#Either.getValue) +**Implements:** [BiFunctor](https://github.com/fantasyland/fantasy-land#bifunctor), [Monad](https://github.com/fantasyland/fantasy-land#monad), [Setoid](https://github.com/fantasyland/fantasy-land#setoid) +- [Either](#either) + - [Either.of(v)](#eitherofv) + - [Either.Right(v)](#eitherrightv) + - [Either.Left(v)](#eitherleftv) + - [Either.fromNullable(v)](#eitherfromnullablev) + - [Either.withDefault(def, v)](#eitherwithdefaultdef-v) + - [Either.swap()](#eitherswap) + - [Either.try(f)](#eithertryf) + - [Either.bimap(e, fl, fr)](#eitherbimape-fl-fr) + - [Either.isLeft(e)](#eitherislefte) + - [Either.isRight(e)](#eitherisrighte) + - [Either.equals(n)](#eitherequalsn) + - [Either.map(f)](#eithermapf) + - [Either.bimap(fl, fr)](#eitherbimapfl-fr) + - [Either.chain(f)](#eitherchainf) + - [Either.swap()](#eitherswap-1) + - [Either.isLeft()](#eitherisleft) + - [Either.isRight()](#eitherisright) + - [Either.ap(j)](#eitherapj) + - [Either.getValue()](#eithergetvalue) ### Either.of(v) -Creates a Right Either +Creates a **Right** `Either`. -| Param | Type | Description | -| --- | --- | --- | -| v | any | Value | +| Param | Type | Description | +| ----- | ---------------- | ----------- | +| v | any | Value | ### Either.Right(v) -Creates a Right Either +Creates a **Right** `Either`. -| Param | Type | Description | -| --- | --- | --- | -| v | any | Value | +| Param | Type | Description | +| ----- | ---------------- | ----------- | +| v | any | Value | ### Either.Left(v) -Creates a Left Either +Creates a **Left** `Either`. -| Param | Type | Description | -| --- | --- | --- | -| v | any | Value | +| Param | Type | Description | +| ----- | ---------------- | ----------- | +| v | any | Value | ### Either.fromNullable(v) -Creates a Right if the value is not null or undefined else creates a Left +Creates a **Right** if the value is not `null` or `undefined`; otherwise, creates a **Left**. -| Param | Type | Description | -| --- | --- | --- | -| v | any | Value | +| Param | Type | Description | +| ----- | ---------------- | ----------- | +| v | any | Value | ### Either.withDefault(def, v) -Creates a Right if the value v is not null or undefined else creates a Right with the default value def +Creates a **Right** if the value `v` is not `null` or `undefined`; otherwise, creates a **Right** with the default value `def`. -| Param | Type | Description | -| --- | --- | --- | -| def | any | Value | -| v | any | Value | +| Param | Type | Description | +| ----- | ---------------- | ------------- | +| def | any | Default value | +| v | any | Value | ### Either.swap() -Swap the Left and Right elements of the current Either + +Swaps the **Left** and **Right** elements of the current `Either`. ### Either.try(f) -* Executes the passed function that may throw and converts it to an Either type. -| Param | Type | Description | -| --- | --- | --- | -| f | function | A function that may throw an error | +Executes the passed function that may throw and converts it to an `Either` type. + +| Param | Type | Description | +| ----- | --------------------- | ---------------------------------- | +| f | function | A function that may throw an error | ### Either.bimap(e, fl, fr) -A static method that applies fl to the Left element or fr to the Right element of the current Either -| Param | Type | Description | -| --- | --- | --- | -| e | any | Either type | -| fl | function | Function to be applied on the Left element | -| fr | function | Function to be applied on the Right element | +A static method that applies `fl` to the **Left** element or `fr` to the **Right** element of the current `Either`. + +| Param | Type | Description | +| ----- | --------------------- | ----------------------------------------------- | +| e | any | `Either` type | +| fl | function | Function to be applied on the **Left** element | +| fr | function | Function to be applied on the **Right** element | ### Either.isLeft(e) -A static method that returns true if the passed Either is a Left - Param | Type | Description | -| --- | --- | --- | -| e | any | Either type | +A static method that returns `true` if the passed `Either` is a **Left**. + +| Param | Type | Description | +| ----- | ---------------- | ------------- | +| e | any | `Either` type | ### Either.isRight(e) -A static method that returns true if the passed Either is a Right - Param | Type | Description | -| --- | --- | --- | -| e | any | Either type | +A static method that returns `true` if the passed `Either` is a **Right**. + +| Param | Type | Description | +| ----- | ---------------- | ------------- | +| e | any | `Either` type | ### Either.equals(n) -Returns true if the current and the passed element are of Either type with the same value -| Param | Type | Description | -| --- | --- | --- | -| n | any | Any Value of Type Setoid | +Returns `true` if the current and the passed element are of `Either` type with the same value. + +| Param | Type | Description | +| ----- | ---------------- | -------------------------- | +| n | any | Any value of type `Setoid` | ### Either.map(f) -Applies the passed function to the value of the current Either if it is a Just -| Param | Type | Description | -| --- | --- | --- | -| f | function | Function | +Applies the passed function to the value of the current `Either` if it is a **Right**. + +| Param | Type | Description | +| ----- | --------------------- | ----------- | +| f | function | Function | ### Either.bimap(fl, fr) -Apply fl to the Left element or fr to the Right element of the current Either -| Param | Type | Description | -| --- | --- | --- | -| fl | function | Function to be applied on the Left element | -| fr | function | Function to be applied on the Right element | +Applies `fl` to the **Left** element or `fr` to the **Right** element of the current `Either`. + +| Param | Type | Description | +| ----- | --------------------- | ----------------------------------------------- | +| fl | function | Function to be applied on the **Left** element | +| fr | function | Function to be applied on the **Right** element | ### Either.chain(f) -An instance method that can chain together many computations that return a Either type -| Param | Type | Description | -| --- | --- | --- | -| f | function | Function that returns another Either | +An instance method that can chain together many computations that return an `Either` type. + +| Param | Type | Description | +| ----- | --------------------- | -------------------------------------- | +| f | function | Function that returns another `Either` | ### Either.swap() -Swap the Left and Right elements of the current Either + +Swaps the **Left** and **Right** elements of the current `Either`. + ### Either.isLeft() -An instance method that returns true if the current Either is a Left + +An instance method that returns `true` if the current `Either` is a **Left**. + ### Either.isRight() -An instance method that returns true if the current Either is a Right + +An instance method that returns `true` if the current `Either` is a **Right**. + ### Either.ap(j) -Applies the function inside the passed Either to the current Either if it is a Right -| Param | Type | Description | -| --- | --- | --- | -| j | any | Either with a function | +Applies the function inside the passed `Either` to the current `Either` if it is a **Right**. + +| Param | Type | Description | +| ----- | ---------------- | ------------------------ | +| j | any | `Either` with a function | ### Either.getValue() -Get the value within the Either \ No newline at end of file + +Gets the value inside the `Either`. diff --git a/docs/helper-functions.md b/docs/helper-functions.md index 09a6aa3..1062c30 100644 --- a/docs/helper-functions.md +++ b/docs/helper-functions.md @@ -1,170 +1,172 @@ # KudoJS Helper Functions -These are the functions under the `kudoJS.*` namespace + +These are the functions under the `kudoJS.*` namespace: - [KudoJS Helper Functions](#kudojs-helper-functions) - - [`kudoJS.id`](#kudojsid) - - [`kudoJS.once`](#kudojsonce) - - [`kudoJS.curry`](#kudojscurry) - - [`kudoJS.ocurry`](#kudojsocurry) - - [`kudoJS.compose`](#kudojscompose) - - [`kudoJS.constant`](#kudojsconstant) - - [`kudoJS.fmap`](#kudojsfmap) - - [`kudoJS.assoc`](#kudojsassoc) - - [`kudoJS.bimap`](#kudojsbimap) - - [`kudoJS.chain`](#kudojschain) - - [`kudoJS.caseOf`](#kudojscaseof) - - [`kudoJS.liftAn`](#kudojsliftan) - - [`kudoJS.liftA2`](#kudojslifta2) - - [`kudoJS.liftA3`](#kudojslifta3) - - [`kudoJS.liftA4`](#kudojslifta4) - - [`kudoJS.liftA5`](#kudojslifta5) - - [`kudoJS.when`](#kudojswhen) - - [`kudoJS.prop`](#kudojsprop) - - [`kudoJS.pick`](#kudojspick) - - [`kudoJS.eitherToMaybe`](#kudojseithertomaybe) - - [`kudoJS.maybeToEither`](#kudojsmaybetoeither) - ----- + - [`kudoJS.id`](#kudojsid) + - [`kudoJS.once`](#kudojsonce) + - [`kudoJS.curry`](#kudojscurry) + - [`kudoJS.ocurry`](#kudojsocurry) + - [`kudoJS.compose`](#kudojscompose) + - [`kudoJS.constant`](#kudojsconstant) + - [`kudoJS.fmap`](#kudojsfmap) + - [`kudoJS.assoc`](#kudojsassoc) + - [`kudoJS.bimap`](#kudojsbimap) + - [`kudoJS.chain`](#kudojschain) + - [`kudoJS.caseOf`](#kudojscaseof) + - [`kudoJS.liftAn`](#kudojsliftan) + - [`kudoJS.liftA2`](#kudojslifta2) + - [`kudoJS.liftA3`](#kudojslifta3) + - [`kudoJS.liftA4`](#kudojslifta4) + - [`kudoJS.liftA5`](#kudojslifta5) + - [`kudoJS.when`](#kudojswhen) + - [`kudoJS.prop`](#kudojsprop) + - [`kudoJS.pick`](#kudojspick) + - [`kudoJS.eitherToMaybe`](#kudojseithertomaybe) + - [`kudoJS.maybeToEither`](#kudojsmaybetoeither) + +--- + ### `kudoJS.id` -Identity function. Returns the value given to it + +The identity function. It returns the value given to it. `id(x: any): any` -| Param | Type | Description | -| --- | --- | --- | -| x | \* | Any | +| Param | Type | Description | +| ----- | --------------- | ----------- | +| x | \* | Any | + +--- ----- ### `kudoJS.once` -Returns a function that when called fires the passed function only once -`once(f: Function): Function` +Returns a function that, when called, fires the passed function only once. -| Param | Type | Description | -| --- | --- | --- | -| f | function | Function to be called once | +`once(f: Function): Function` +| Param | Type | Description | +| ----- | --------------------- | -------------------------- | +| f | function | Function to be called once | ----- +--- ### `kudoJS.curry` -Returns a curried equivalent of the provided function +Returns a curried equivalent of the provided function. `curry(fn: Function): Function` -| Param | Type | Description | -| --- | --- | --- | -| fn | function | Function to be curried | +| Param | Type | Description | +| ----- | --------------------- | ---------------------- | +| fn | function | Function to be curried | ----- +--- ### `kudoJS.ocurry` -Returns a curried equivalent of the provided function which will accept named arguments in any order -`ocurry(fn: Function, args: Array): Function` +Returns a curried equivalent of the provided function, which will accept named arguments in any order. -| Param | Type | Description | -| --- | --- | --- | -| fn | function | Function to be curried and that which accepts a single named argument object | -| args | Array.<string> | Array of key names of the function named argument object | +`ocurry(fn: Function, args: Array): Function` +| Param | Type | Description | +| ----- | --------------------------------- | ------------------------------------------------------------------ | +| fn | function | Function to be curried that accepts a single named argument object | +| args | Array.<string> | Array of key names of the function's named argument object | ----- +--- ### `kudoJS.compose` -Performs right-to-left function composition +Performs right-to-left function composition. `compose(...fns: Function): Function` +| Param | Type | Description | +| ------ | --------------------- | -------------------- | +| ...fns | function | Functions to compose | -| Param | Type | Description | -| --- | --- | --- | -| ...fns | function | functions to compose | +--- - ----- ### `kudoJS.constant` -Takes any value and gives back a function that will return that same value no matter what you pass it + +Takes any value and returns a function that will return the same value, no matter what you pass to it. `constant(x: any): any` -| Param | Type | Description | -| --- | --- | --- | -| x | \* | Any | +| Param | Type | Description | +| ----- | --------------- | ----------- | +| x | \* | Any | ----- +--- ### `kudoJS.fmap` -Takes a function and a functor, applies the function to each of the functor's values, and returns a functor +Takes a function and a functor, applies the function to each of the functor's values, and returns a functor. `fmap(fn: (a: A) => B, f: Functor): Functor` -| Param | Type | Description | -| --- | --- | --- | -| fn | function | function to be mapped | -| f | Functor | Functor | - ----- +| Param | Type | Description | +| ----- | --------------------- | --------------------- | +| fn | function | Function to be mapped | +| f | Functor | Functor | +--- ### `kudoJS.assoc` -Associates a value to the specified key in the object. This returns a clone of the original object +Associates a value with the specified key in the object and returns a clone of the original object. `assoc(key: string, value: A, o: {[k:string]: A}): {[k:string]: A}` +| Param | Type | Description | +| ----- | ------------------- | -------------------------------------------------------------- | +| key | string | Key | +| value | any | Value to be assigned to the key in the object | +| o | Object | Object to which the value needs to be assigned against the key | -| Param | Type | Description | -| --- | --- | --- | -| key | string | Key | -| value | function | Value to be assigned to key in object | -| o | Object | Object to which value needs to be assigned against the Key | - ----- +--- ### `kudoJS.bimap` -Maps both sides of the disjunction +Maps both sides of the disjunction. `bimap(f1: (a: A) => C, f2: (b: B) => D, b: BiFunctor): BiFunctor` +| Param | Type | Description | +| ----- | ---------------------- | ----------------------------------------------------------- | +| f1 | function | Function to be applied on the left side of the disjunction | +| f2 | function | Function to be applied on the right side of the disjunction | +| b | BiFunctor | BiFunctor | -| Param | Type | Description | -| --- | --- | --- | -| f1 | function | function to be mapped on the left of the disjunction | -| f2 | function | function to be mapped on the right of the disjunction | -| b | BiFunctor | BiFunctor | - ----- +--- ### `kudoJS.chain` -Chain together in many computations of the same type +Chains together many computations of the same type. `chain(f: (a: A) => Monad, m: Monad): Monad` -| Param | Type | Description | -| --- | --- | --- | -| fn | function | function that returns a Monad | -| m | Monad | Monad | +| Param | Type | Description | +| ----- | --------------------- | ----------------------------- | +| f | function | Function that returns a Monad | +| m | Monad | Monad | ----- +--- ### `kudoJS.caseOf` -Conditional behaviour based on the structure of algebraic data types +Conditional behavior based on the structure of algebraic data types. `caseOf(o: Object, p: ADT): any` -| Param | Type | Description | -| --- | --- | --- | -| o | Object | An Object with key as ADT constructor name and value as function expression| -| p | PatternMatch | An ADT that supports pattern matching | +| Param | Type | Description | +| ----- | ------------------------- | ----------------------------------------------------------------------------------- | +| o | Object | An object with key as the ADT constructor name and value as the function expression | +| p | PatternMatch | An ADT that supports pattern matching | **Example:** + ``` import {caseOf, Maybe} from "fp-kudojs"; @@ -176,140 +178,145 @@ const k1 = caseOf({ }, j1); //k1 = 2; ``` ----- + +--- ### `kudoJS.liftAn` -combine n separate wrapped values into one with a given function. +Combines `n` separate wrapped values into one with a given function. `liftAn(f: (a: A ...an: A) => B, ar: Array>): Apply` -| Param | Type | Description | -| --- | --- | --- | -| a | function | Function with n arguments to be lifted | -| ar | Apply | Array of wrapped values(Apply). The values of which will be passed as arguments to the function `a` | +| Param | Type | Description | +| ----- | --------------------- | ------------------------------------------------------------------------------------------------ | +| f | function | Function with `n` arguments to be lifted | +| ar | Apply | Array of wrapped values (`Apply`). The values will be passed as arguments to the function `f` | ----- +--- ### `kudoJS.liftA2` -combine 2 separate wrapped values into one with a given function. +Combines 2 separate wrapped values into one with a given function. `liftA2(f: (a1: A, a2: A) => B, ar1: Apply, ar2: Apply): Apply` -| Param | Type | Description | -| --- | --- | --- | -| f | function | Function to be lifted | -| a1 | Apply | Wrapped value(Apply) | -| a2 | Apply | Wrapped value(Apply) | +| Param | Type | Description | +| ----- | --------------------- | --------------------- | +| f | function | Function to be lifted | +| ar1 | Apply | Wrapped value (Apply) | +| ar2 | Apply | Wrapped value (Apply) | ----- +--- ### `kudoJS.liftA3` -combine 3 separate wrapped values into one with a given function. +Combines 3 separate wrapped values into one with a given function. `liftA3(f: (a1: A, a2: A, a3: A) => B, ar1: Apply, ar2: Apply, ar3: Apply): Apply` -| Param | Type | Description | -| --- | --- | --- | -| f | function | Function to be lifted | -| a1 | Apply | Wrapped value(Apply) | -| a2 | Apply | Wrapped value(Apply) | -| a3 | Apply | Wrapped value(Apply) | +| Param | Type | Description | +| ----- | --------------------- | --------------------- | +| f | function | Function to be lifted | +| ar1 | Apply | Wrapped value (Apply) | +| ar2 | Apply | Wrapped value (Apply) | +| ar3 | Apply | Wrapped value (Apply) | ----- +--- ### `kudoJS.liftA4` -combine 4 separate wrapped values into one with a given function. +Combines 4 separate wrapped values into one with a given function. `liftA4(f: (a1: A, a2: A, a3: A, a4: A) => B, ar1: Apply, ar2: Apply, ar3: Apply, ar4: Apply): Apply` -| Param | Type | Description | -| --- | --- | --- | -| f | function | Function to be lifted | -| a1 | Apply | Wrapped value(Apply) | -| a2 | Apply | Wrapped value(Apply) | -| a3 | Apply | Wrapped value(Apply) | -| a4 | Apply | Wrapped value(Apply) | +| Param | Type | Description | +| ----- | --------------------- | --------------------- | +| f | function | Function to be lifted | +| ar1 | Apply | Wrapped value (Apply) | +| ar2 | Apply | Wrapped value (Apply) | +| ar3 | Apply | Wrapped value (Apply) | +| ar4 | Apply | Wrapped value (Apply) | ----- +--- ### `kudoJS.liftA5` -combine 5 separate wrapped values into one with a given function. +Combines 5 separate wrapped values into one with a given function. `liftA5(f: (a1: A, a2: A, a3: A, a4: A, a5: A) => B, ar1: Apply, ar2: Apply, ar3: Apply, ar4: Apply, ar5: Apply): Apply` -| Param | Type | Description | -| --- | --- | --- | -| f | function | Function to be lifted | -| a1 | Apply | Wrapped value(Apply) | -| a2 | Apply | Wrapped value(Apply) | -| a3 | Apply | Wrapped value(Apply) | -| a4 | Apply | Wrapped value(Apply) | -| a5 | Apply | Wrapped value(Apply) | +| Param | Type | Description | +| ----- | --------------------- | --------------------- | +| f | function | Function to be lifted | +| ar1 | Apply | Wrapped value (Apply) | +| ar2 | Apply | Wrapped value (Apply) | +| ar3 | Apply | Wrapped value (Apply) | +| ar4 | Apply | Wrapped value (Apply) | +| ar5 | Apply | Wrapped value (Apply) | ----- +--- ### `kudoJS.when` -Returns a function for which it takes one argument and passes it to the given predicate function. If the predicate is satisfied, f is run with the same argument. If the predicate is not satisfied, the argument is returned as is. + +Returns a function that takes one argument and passes it to the given predicate function. If the predicate is satisfied, `f` is run with the same argument. If the predicate is not satisfied, the argument is returned as is. `when(p: Function, f: Function): Function` -| Param | Type | Description | -| --- | --- | --- | -| p | function | Predicate function that should return true or false based on the argument passed | -| f | function | Function to be executed with the given argument when predicate is satisfied | +| Param | Type | Description | +| ----- | --------------------- | ------------------------------------------------------------------------------- | +| p | function | Predicate function that returns `true` or `false` based on the argument passed | +| f | function | Function to be executed with the given argument when the predicate is satisfied | ----- +--- ### `kudoJS.prop` -Returns a Maybe Just if value exists for the given key else returns a Nothing -`prop( key: string | number, o: { [k: string]: A; [k: number]: A }): Maybe` +Returns a **Maybe Just** if a value exists for the given key; otherwise, returns a **Nothing**. -| Param | Type | Description | -| --- | --- | --- | -| key | string | number | Key | -| o | Object | Key Value Object | +`prop(key: string | number, o: { [k: string]: A; [k: number]: A }): Maybe` ----- +| Param | Type | Description | +| ----- | ------------------- | ---------------- | --- | +| key | string | number | Key | +| o | Object | Key-Value Object | +--- ### `kudoJS.pick` -Returns a Maybe Just containing the object with just the keys if values exists for the given keys else returns a Nothing -`pick( keys: Array, o: { [k: string]: A}): Maybe<{[k:string]: A}>` +Returns a **Maybe Just** containing the object with only the specified keys if values exist for the given keys; otherwise, returns a **Nothing**. + +`pick(keys: Array, o: { [k: string]: A }): Maybe<{[k: string]: A}>` -| Param | Type | Description | -| --- | --- | --- | -| keys | Array | Keys | -| o | Object | Key Value Object | +| Param | Type | Description | +| ----- | -------------------------- | ---------------- | +| keys | Array | Keys | +| o | Object | Key-Value Object | ----- +--- ### `kudoJS.eitherToMaybe` -Converts an Either type to a Maybe Type -`eitherToMaybe(e: Either): Maybe` +Converts an **Either** type to a **Maybe** type. -| Param | Type | Description | -| --- | --- | --- | -| m | Maybe | Maybe type | +`eitherToMaybe(e: Either): Maybe` ----- +| Param | Type | Description | +| ----- | ------------------- | ----------- | +| e | Either | Either type | + +--- ### `kudoJS.maybeToEither` -Converts a Maybe type to an Either Type -`maybeToEither(m: Maybe): Either` +Converts a **Maybe** type to an **Either** type. + +`maybeToEither(m: Maybe): Either` -| Param | Type | Description | -| --- | --- | --- | -| m | Maybe | Maybe type | +| Param | Type | Description | +| ----- | ------------------ | ----------- | +| m | Maybe | Maybe type | ----- +--- -TODO: Add more documentation and examples +TODO: Add more documentation and examples diff --git a/docs/identity.md b/docs/identity.md index 450d09d..808d0c9 100644 --- a/docs/identity.md +++ b/docs/identity.md @@ -1,16 +1,16 @@ - # Identity -A Identity is another way of storing two values in a single value. Elements of a Identity do not need to be of the same type -**Implements:** [Monad](https://github.com/fantasyland/fantasy-land#monad), [Semigroup](https://github.com/fantasyland/fantasy-land#semigroup), [Setoid](https://github.com/fantasyland/fantasy-land#setoid) +An Identity is a wrapper for a value that cannot be changed. It is useful for handling pure values. + +**Implements:** [Monad](https://github.com/fantasyland/fantasy-land#monad), [Semigroup](https://github.com/fantasyland/fantasy-land#semigroup), [Setoid](https://github.com/fantasyland/fantasy-land#setoid) - [Identity](#identity) - [Identity(v)](#identityv) - [Identity.of(v)](#identityofv) - [Identity.equals(j)](#identityequalsj) - - [Identity.concat( p)](#identityconcat-p) + - [Identity.concat(p)](#identityconcatp) - [Identity.getValue()](#identitygetvalue) - [Identity.map(f)](#identitymapf) - [Identity.chain(f)](#identitychainf) @@ -20,75 +20,77 @@ A Identity is another way of storing two values in a single value. Elements of a ### Identity(v) -Identity constructor +The Identity constructor. -| Param | Type | Description | -| --- | --- | --- | -| v | any | Value to be wrapped by identity. This cannot be undefined | +| Param | Type | Description | +| ----- | ---------------- | ---------------------------------------------------------------- | +| v | any | The value to be wrapped by Identity. This cannot be `undefined`. | ### Identity.of(v) -Identity constructor +Identity constructor. -| Param | Type | Description | -| --- | --- | --- | -| v | any | Value to be wrapped by identity. This cannot be undefined | +| Param | Type | Description | +| ----- | ---------------- | ---------------------------------------------------------------- | +| v | any | The value to be wrapped by Identity. This cannot be `undefined`. | ### Identity.equals(j) -Check if the values of the current Identity is equal to the values of the passed Identity. This checks for `===`'ty of the values of the 2 Identities +Checks if the value of the current Identity is equal to the value of the passed Identity. This uses strict equality (`===`) to compare the values of the two Identities. -| Param | Type | Description | -| --- | --- | --- | -| j | [Identity](#Identity) | The Identity to compare with | +| Param | Type | Description | +| ----- | ---------------------------------- | ---------------------------- | +| j | [Identity](#identity) | The Identity to compare with | -### Identity.concat( p) -Concat the current Identity with the passed one. Note that values of both the Identities should be of the same type and should be of type semigroup for cancat to work +### Identity.concat(p) +Concatenates the current Identity with the passed one. Note that the values of both Identities must be of the same type and must be of a type that supports the `Semigroup` concatenation operation for this to work. -| Param | Type | Description | -| --- | --- | --- | -| p | [Identity](#Identity) | Identity to concat | +| Param | Type | Description | +| ----- | ---------------------------------- | -------------------------------- | +| p | [Identity](#identity) | The Identity to concatenate with | ### Identity.getValue() -Get the value within the Identity + +Gets the value within the Identity. ### Identity.map(f) -Apply the function to the value of the current Identity +Applies the function to the value of the current Identity. -| Param | Type | Description | -| --- | --- | --- | -| f | function | Function | +| Param | Type | Description | +| ----- | --------------------- | ----------- | +| f | function | Function | ### Identity.chain(f) -Chain a computation that returns an Identity +Chains a computation that returns an Identity. -| Param | Type | Description | -| --- | --- | --- | -| f | function | Function that returns another Identity | +| Param | Type | Description | +| ----- | --------------------- | -------------------------------------- | +| f | function | Function that returns another Identity | ### Identity.toString() -Get a stringified version of the Identity +Returns a stringified version of the Identity. --- + ### Examples -** TODO: Add some examples ** \ No newline at end of file +**TODO: Add some examples** diff --git a/docs/maybe.md b/docs/maybe.md index 8a883f8..b279cb8 100644 --- a/docs/maybe.md +++ b/docs/maybe.md @@ -1,167 +1,177 @@ -## Maybe -Maybe is a structure for values that may not be present, or things that may fail. -A Maybe can help in dealing with optional values, arguments, and records with optional fields etc. +## Maybe + +`Maybe` is a structure for values that may not be present or for situations that may fail. A `Maybe` can help in dealing with optional values, arguments, records with optional fields, etc. **Implements:** [Alt](https://github.com/fantasyland/fantasy-land#alt), [Monad](https://github.com/fantasyland/fantasy-land#monad), [Semigroup](https://github.com/fantasyland/fantasy-land#semigroup), [Setoid](https://github.com/fantasyland/fantasy-land#setoid) - [Maybe](#maybe) - - [Maybe.of(v)](#maybeofv) - - [Maybe.zero()](#maybezero) - - [Maybe.Just(v)](#maybejustv) - - [Maybe.Nothing()](#maybenothing) - - [Maybe.fromNullable(v)](#maybefromnullablev) - - [Maybe.withDefault(def, v)](#maybewithdefaultdef-v) - - [Maybe.](#maybe-1) - - [Maybe.catMaybes(ar)](#maybecatmaybesar) - - [Maybe.isNothing(v)](#maybeisnothingv) - - [Maybe.isJust(v)](#maybeisjustv) - - [Maybe.equals(n)](#maybeequalsn) - - [Maybe.map(f)](#maybemapf) - - [Maybe.chain(f)](#maybechainf) - - [Maybe.isNothing()](#maybeisnothing) - - [Maybe.isJust()](#maybeisjust) - - [Maybe.alt(v)](#maybealtv) - - [Maybe.ap(j)](#maybeapj) - - [Maybe.getValue()](#maybegetvalue) - + - [Maybe.of(v)](#maybeofv) + - [Maybe.zero()](#maybezero) + - [Maybe.Just(v)](#maybejustv) + - [Maybe.Nothing()](#maybenothing) + - [Maybe.fromNullable(v)](#maybefromnullablev) + - [Maybe.withDefault(def, v)](#maybewithdefaultdef-v) + - [Maybe.catMaybes(ar)](#maybecatmaybesar) + - [Maybe.isNothing(v)](#maybeisnothingv) + - [Maybe.isJust(v)](#maybeisjustv) + - [Maybe.equals(n)](#maybeequalsn) + - [Maybe.map(f)](#maybemapf) + - [Maybe.chain(f)](#maybechainf) + - [Maybe.isNothing()](#maybeisnothing) + - [Maybe.isJust()](#maybeisjust) + - [Maybe.alt(v)](#maybealtv) + - [Maybe.ap(j)](#maybeapj) + - [Maybe.getValue()](#maybegetvalue) ### Maybe.of(v) -Creates a Just v +Creates a `Just v`. -| Param | Type | Description | -| --- | --- | --- | -| v | any | Value | +| Param | Type | Description | +| ----- | ---------------- | ----------- | +| v | any | Value | ### Maybe.zero() -Creates a Nothing + +Creates a `Nothing`. ### Maybe.Just(v) -Creates a Just v +Creates a `Just v`. -| Param | Type | Description | -| --- | --- | --- | -| v | any | Value | +| Param | Type | Description | +| ----- | ---------------- | ----------- | +| v | any | Value | ### Maybe.Nothing() -Creates a Nothing + +Creates a `Nothing`. ### Maybe.fromNullable(v) -Creates a Just if the value is not null or undefined else creates a Nothing +Creates a `Just` if the value is not `null` or `undefined`; otherwise, creates a `Nothing`. -| Param | Type | Description | -| --- | --- | --- | -| v | any | Value | +| Param | Type | Description | +| ----- | ---------------- | ----------- | +| v | any | Value | ### Maybe.withDefault(def, v) -Creates a Just if the value v is not null or undefined else creates a Just with the default value def - -| Param | Type | Description | -| --- | --- | --- | -| def | any | Value | -| v | any | Value | +Creates a `Just` if the value `v` is not `null` or `undefined`; otherwise, creates a `Just` with the default value `def`. -### Maybe. +| Param | Type | Description | +| ----- | ---------------- | ------------- | +| def | any | Default value | +| v | any | Value | ### Maybe.catMaybes(ar) -A static method that takes an Array of Maybes and returns back an Array of values of all the Just in the passed Array -| Param | Type | Description | -| --- | --- | --- | -| ar | Array.<any> | Array of Maybes | +A static method that takes an array of `Maybe` values and returns an array of the values of all the `Just` elements in the passed array. + +| Param | Type | Description | +| ----- | ------------------------------ | ----------------------- | +| ar | Array.<any> | Array of `Maybe` values | ### Maybe.isNothing(v) -A static method that returns true if the passed Maybe is a Nothing -| Param | Type | Description | -| --- | --- | --- | -| v | any | Maybe | +A static method that returns `true` if the passed `Maybe` is a `Nothing`. + +| Param | Type | Description | +| ----- | ---------------- | ----------- | +| v | any | `Maybe` | ### Maybe.isJust(v) -A static method that returns true if the passed Maybe is a Just -| Param | Type | Description | -| --- | --- | --- | -| v | any | Maybe | +A static method that returns `true` if the passed `Maybe` is a `Just`. + +| Param | Type | Description | +| ----- | ---------------- | ----------- | +| v | any | `Maybe` | ### Maybe.equals(n) -Returns true if the current and the passed element are of Maybe type with the same value -| Param | Type | Description | -| --- | --- | --- | -| n | any | Any Value of Type Setoid | +Returns `true` if the current and the passed elements are of the `Maybe` type with the same value. + +| Param | Type | Description | +| ----- | ---------------- | -------------------------- | +| n | any | Any value of type `Setoid` | ### Maybe.map(f) -Applies the passed function to the value of the current Maybe if it is a Just -| Param | Type | Description | -| --- | --- | --- | -| f | function | Function | +Applies the passed function to the value of the current `Maybe` if it is a `Just`. + +| Param | Type | Description | +| ----- | --------------------- | ----------- | +| f | function | Function | ### Maybe.chain(f) -Chains together many computations that return a Maybe type -| Param | Type | Description | -| --- | --- | --- | -| f | function | Function that returns another Maybe | +Chains together many computations that return a `Maybe` type. + +| Param | Type | Description | +| ----- | --------------------- | ------------------------------------- | +| f | function | Function that returns another `Maybe` | ### Maybe.isNothing() -Returns true if the current Maybe is a Nothing + +Returns `true` if the current `Maybe` is a `Nothing`. + ### Maybe.isJust() -Returns true if the current Maybe is a Just + +Returns `true` if the current `Maybe` is a `Just`. ### Maybe.alt(v) -An instance method that returns the current maybe if it is a Just else returns the passed Maybe -| Param | Type | Description | -| --- | --- | --- | -| v | any | Maybe | +An instance method that returns the current `Maybe` if it is a `Just`; otherwise, returns the passed `Maybe`. + +| Param | Type | Description | +| ----- | ---------------- | ----------- | +| v | any | `Maybe` | ### Maybe.ap(j) -Applies the function inside the passed Maybe to the current Maybe if it is a Just -| Param | Type | Description | -| --- | --- | --- | -| j | any | Maybe with a function | +Applies the function inside the passed `Maybe` to the current `Maybe` if it is a `Just`. + +| Param | Type | Description | +| ----- | ---------------- | ----------------------- | +| j | any | `Maybe` with a function | ### Maybe.getValue() -Get the value within the Maybe \ No newline at end of file + +Gets the value within the `Maybe`. diff --git a/docs/pair.md b/docs/pair.md index 331b1f8..51e0695 100644 --- a/docs/pair.md +++ b/docs/pair.md @@ -2,100 +2,100 @@ # Pair -A Pair is another way of storing two values in a single value. Elements of a Pair do not need to be of the same type +A `Pair` is a structure for storing two values in a single value. The elements of a `Pair` do not need to be of the same type. **Implements:** [BiFunctor](https://github.com/fantasyland/fantasy-land#bifunctor), [Monad](https://github.com/fantasyland/fantasy-land#monad), [Semigroup](https://github.com/fantasyland/fantasy-land#semigroup), [Setoid](https://github.com/fantasyland/fantasy-land#setoid) -- [Pair](#pair) - - [Pair(v1, v2)](#pairv1-v2) - - [Pair.of(v)](#pairofv) - - [Pair.equals(j)](#pairequalsj) - - [Pair.concat( p)](#pairconcat-p) - - [Pair.fst()](#pairfst) - - [Pair.snd()](#pairsnd) - - [Pair.concat(j)](#pairconcatj) - - [Pair.getValue()](#pairgetvalue) - - [Pair.map(f)](#pairmapf) - - [Pair.bimap(f1, f2)](#pairbimapf1-f2) - - [Pair.chain(f)](#pairchainf) - - [Pair.swap()](#pairswap) - - [Pair.toString()](#pairtostring) - - [Examples](#examples) +- [Pair](#pair) + - [Pair(v1, v2)](#pairv1-v2) + - [Pair.of(v)](#pairofv) + - [Pair.equals(j)](#pairequalsj) + - [Pair.concat(p)](#pairconcatp) + - [Pair.fst()](#pairfst) + - [Pair.snd()](#pairsnd) + - [Pair.concat(j)](#pairconcatj) + - [Pair.getValue()](#pairgetvalue) + - [Pair.map(f)](#pairmapf) + - [Pair.bimap(f1, f2)](#pairbimapf1-f2) + - [Pair.chain(f)](#pairchainf) + - [Pair.swap()](#pairswap) + - [Pair.toString()](#pairtostring) + - [Examples](#examples) ### Pair(v1, v2) -Pair constructor +Pair constructor. | Param | Type | Description | | ----- | ---------------- | -------------------------- | | v1 | any | First element of the Pair | -| v2 | any | second element of the Pair | +| v2 | any | Second element of the Pair | ### Pair.of(v) -Pair constructor +Pair constructor. -| Param | Type | Description | -| ----- | ---------------- | ------------------------------------------------------------------- | -| v | any | Element that will be stored as first and second element of the Pair | +| Param | Type | Description | +| ----- | ---------------- | ---------------------------------------------------------------------------- | +| v | any | Element that will be stored as both the first and second element of the Pair | ### Pair.equals(j) -Check if the values of the current pair is equal to the values of the passed Pair. Pairs are equal only if the first and second values of both Pairs are equal +Checks if the values of the current `Pair` are equal to the values of the passed `Pair`. Pairs are equal only if the first and second values of both pairs are equal. -| Param | Type | Description | -| ----- | -------------------------- | ------------------------ | -| j | [Pair](#Pair) | The Pair to compare with | +| Param | Type | Description | +| ----- | -------------------------- | -------------------------- | +| j | [Pair](#Pair) | The `Pair` to compare with | -### Pair.concat( p) +### Pair.concat(p) -Concat the current pair with the passed one. Note that both first and second elements of the Pair should be of type semigroup for cancat to work +Concatenates the current `Pair` with the passed one. Note that both the first and second elements of the `Pair` must be of type `Semigroup` for concatenation to work. -| Param | Type | Description | -| ----- | -------------------------- | -------------- | -| p | [Pair](#Pair) | Pair to concat | +| Param | Type | Description | +| ----- | -------------------------- | ---------------- | +| p | [Pair](#Pair) | `Pair` to concat | ### Pair.fst() -Get the first element of the Pair +Gets the first element of the `Pair`. ### Pair.snd() -Get the second element of the Pair +Gets the second element of the `Pair`. ### Pair.concat(j) -Applies the function inside the second element of the passed Pair to the current Pair and concats the first element of the second Pair to the first element of the current Pair +Applies the function inside the second element of the passed `Pair` to the current `Pair` and concatenates the first element of the second `Pair` to the first element of the current `Pair`. -| Param | Type | Description | -| ----- | -------------------------- | ---------------------------------------- | -| j | [Pair](#Pair) | Pair with function as the second element | +| Param | Type | Description | +| ----- | -------------------------- | -------------------------------------------- | +| j | [Pair](#Pair) | `Pair` with a function as the second element | ### Pair.getValue() -Get the values within the Pair as an Array of length 2 +Gets the values within the `Pair` as an array of length 2. ### Pair.map(f) -Apply the function to the second element of the current Pair +Applies the passed function to the second element of the current `Pair`. | Param | Type | Description | | ----- | --------------------- | ----------- | @@ -105,42 +105,57 @@ Apply the function to the second element of the current Pair ### Pair.bimap(f1, f2) -Apply f1 to the first element and f2 to the second element of the current Pair +Applies `f1` to the first element and `f2` to the second element of the current `Pair`. | Param | Type | Description | | ----- | --------------------- | -------------------------------------------- | -| f1 | function | Function to be applied on the first element | -| f2 | function | Function to be applied on the second element | +| f1 | function | Function to be applied to the first element | +| f2 | function | Function to be applied to the second element | ### Pair.chain(f) -Chain together many computations that return a Pair +Chains together many computations that return a `Pair`. -| Param | Type | Description | -| ----- | --------------------- | ---------------------------------- | -| f | function | Function that returns another Pair | +| Param | Type | Description | +| ----- | --------------------- | ------------------------------------ | +| f | function | Function that returns another `Pair` | ### Pair.swap() -Swap the elements of the current pair +Swaps the elements of the current `Pair`. ### Pair.toString() -Get a stringified version of the Pair +Gets a stringified version of the `Pair`. --- +### Examples + +Let's construct some `Pairs`. + +```javascript +import { Pair } from "fp-kudojs"; + +const point1 = Pair(1, 2); +console.log(point1.toString()); // Pair((1), (2)) + +const point2 = Pair.of(2); +console.log(point2.toString()); // Pair((2), (2)) + + ### Examples Lets construct some Pairs ``` + import {Pair} from "fp-kudojs"; const point1 = Pair(1, 2); @@ -148,11 +163,13 @@ console.log(point1.toString()); // Pair((1), (2)) const point2 = Pair.of(2); console.log(point2.toString()); // Pair((2), (2)) + ``` Two Pairs are equal if the first and the second element of each Pair are equal ``` + console.log(point1.equals(Pair(1,2))) //true console.log(point2.equals(point1) //false @@ -161,9 +178,10 @@ console.log(Pair([1], [2]).equals(Pair([1],[2]))) //false ``` -Concat Pairs. Note that to concat pairs the elements of each Pair should be semigroups of the same type +Concatenate Pairs. Note that to concatenate Pairs, the elements of each Pair should be Semigroups of the same type. ``` + const p1 = Pair([1], [2]); const p2 = Pair([3], [4]); @@ -174,3 +192,4 @@ console.log(p3.getValue()); // [[1, 3], [2, 4]] ``` ** TODO: Add more examples ** +``` diff --git a/docs/reader.md b/docs/reader.md index beed805..261515c 100644 --- a/docs/reader.md +++ b/docs/reader.md @@ -1,83 +1,89 @@ ## Reader -The Reader monad represents a computation, which can read values from a shared environment, pass values from function to function, and execute sub-computations in a modified environment. It is also useful when it comes to dependency injections + +The `Reader` monad represents a computation that can read values from a shared environment, pass values from function to function, and execute sub-computations in a modified environment. It is also useful for dependency injection. **Implements:** [Monad](https://github.com/fantasyland/fantasy-land#monad) - [Reader](#reader) - - [Reader(f)](#readerf) - - [Reader.of(v)](#readerofv) - - [Reader.toString()](#readertostring) - - [Reader.map(f)](#readermapf) - - [Reader.getValue()](#readergetvalue) - - [Reader.ap(t)](#readerapt) - - [Reader.chain(f)](#readerchainf) - - [Reader.runWith(e)](#readerrunwithe) + - [Reader(f)](#readerf) + - [Reader.of(v)](#readerofv) + - [Reader.toString()](#readertostring) + - [Reader.map(f)](#readermapf) + - [Reader.getValue()](#readergetvalue) + - [Reader.ap(t)](#readerapt) + - [Reader.chain(f)](#readerchainf) + - [Reader.runWith(e)](#readerrunwithe) ### Reader(f) -Reader constructor +The `Reader` constructor. -| Param | Type | Description | -| --- | --- | --- | -| f | function | A function of the form (e -> a) that is wrapped by the Reader, nothing is executed until it is run with an environment | +| Param | Type | Description | +| ----- | --------------------- | --------------------------------------------------------------------------------------------------------------------------- | +| f | function | A function of the form `(e -> a)` that is wrapped by the `Reader`. Nothing is executed until it is run with an environment. | ### Reader.of(v) -Reader constructor that populates the right portion with it's argument. of essentially will lift a value of type a into a Reader - -| Param | Type | Description | -| --- | --- | --- | -| v | any | any value that needs to be lifted to the Reader | +The `Reader` constructor that populates the right portion with its argument. `of` essentially lifts a value of type `a` into a `Reader`. +| Param | Type | Description | +| ----- | ---------------- | --------------------------------------------------- | +| v | any | Any value that needs to be lifted into the `Reader` | ### Reader.toString() -Get a stringified version of the Reader + +Gets a stringified version of the `Reader`. ### Reader.map(f) -Apply the function f to the right portion of the Reader -| Param | Type | Description | -| --- | --- | --- | -| f | function | Function | +Applies the function `f` to the right portion of the `Reader`. + +| Param | Type | Description | +| ----- | --------------------- | ----------- | +| f | function | Function | ### Reader.getValue() -Get the function within the Reader + +Gets the function within the `Reader`. ### Reader.ap(t) -ap allows for values wrapped in a Reader to be applied to functions also wrapped in a Reader. In order to use ap, the Reader must contain a function as its value. -| Param | Type | Description | -| --- | --- | --- | -| t | [Reader](#Reader) | Reader with function as the second element | +`ap` allows for values wrapped in a `Reader` to be applied to functions also wrapped in a `Reader`. In order to use `ap`, the `Reader` must contain a function as its value. + +| Param | Type | Description | +| ----- | ------------------------------ | --------------------------------------- | +| t | [Reader](#Reader) | A `Reader` with a function as its value | ### Reader.chain(f) -Chain together many computations that return a Reader -| Param | Type | Description | -| --- | --- | --- | -| f | function | Function that returns another Reader | +Chains together many computations that return a `Reader`. + +| Param | Type | Description | +| ----- | --------------------- | -------------------------------------- | +| f | function | Function that returns another `Reader` | ### Reader.runWith(e) -As Reader is a lazy datatype that requires a shared environment to run, it's instance provides a runWith method that takes in an environment and returns the result of the computation. -| Param | Type | Description | -| --- | --- | --- | -| e | any | An environment that needs to be passed to the Reader | +Since `Reader` is a lazy datatype that requires a shared environment to run, its instance provides a `runWith` method. This method takes in an environment and returns the result of the computation. + +| Param | Type | Description | +| ----- | ---------------- | ------------------------------------------------------ | +| e | any | An environment that needs to be passed to the `Reader` | diff --git a/docs/setup.md b/docs/setup.md new file mode 100644 index 0000000..0b0bd3d --- /dev/null +++ b/docs/setup.md @@ -0,0 +1,33 @@ +### Installation + +Install and save KudoJS as a dependency in your current project + +``` +$ npm install --save fp-kudojs +``` + +### Import using CommonJS + +``` +const kudoJS = require("fp-kudojs") +``` + +### Import using ES Modules + +``` +import kudoJS from "fp-kudojs" +``` + +### Import single entities using CommonJS + +``` +const compose = require("fp-kudojs/function/compose"); +const Maybe = require("fp-kudojs/adt/Maybe"); +``` + +### Import single entities using ES Modules + +``` +import compose from "fp-kudojs/function/compose"; +import Maybe from "fp-kudojs/adt/Maybe"; +``` diff --git a/docs/state.md b/docs/state.md index 48a9d53..daba143 100644 --- a/docs/state.md +++ b/docs/state.md @@ -1,104 +1,112 @@ ## State -State is parameterized by two types, a state s and a result a -State should wrap a function of the form s -> Pair a s and can be constructed by providing a function of this form. There are 3 methods that are available on the State for running with a given initial state + +`State` is parameterized by two types: a state `s` and a result `a`. +`State` should wrap a function of the form `s -> Pair a s` and can be constructed by providing a function of this form. There are three methods available on the `State` for running with a given initial state. **Implements:** [Monad](https://github.com/fantasyland/fantasy-land#monad) - [State](#state) - - [State(f)](#statef) - - [State.of(v)](#stateofv) - - [State.toString()](#statetostring) - - [State.map(f)](#statemapf) - - [State.getValue()](#stategetvalue) - - [State.ap(t)](#stateapt) - - [State.chain(f)](#statechainf) - - [State.runWith(s)](#staterunwiths) - - [State.execWith(s)](#stateexecwiths) - - [State.evalWith(s)](#stateevalwiths) + - [State(f)](#statef) + - [State.of(v)](#stateofv) + - [State.toString()](#statetostring) + - [State.map(f)](#statemapf) + - [State.getValue()](#stategetvalue) + - [State.ap(t)](#stateapt) + - [State.chain(f)](#statechainf) + - [State.runWith(s)](#staterunwiths) + - [State.execWith(s)](#stateexecwiths) + - [State.evalWith(s)](#stateevalwiths) ### State(f) -State constructor +The `State` constructor. -| Param | Type | Description | -| --- | --- | --- | -| f | function | A function of the form s -> Pair a that is wrapped by the State, nothing is executed until it is run with an initial state s | +| Param | Type | Description | +| ----- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| f | function | A function of the form `s -> Pair a` that is wrapped by the `State`. Nothing is executed until it is run with an initial state `s`. | ### State.of(v) -State constructor that populates the right portion with it's argument. of essentially will lift a value of type a into a State - -| Param | Type | Description | -| --- | --- | --- | -| v | any | any value that needs to be lifted to the State | +The `State` constructor that populates the right portion with its argument. `of` essentially lifts a value of type `a` into a `State`. +| Param | Type | Description | +| ----- | ---------------- | -------------------------------------------------- | +| v | any | Any value that needs to be lifted into the `State` | ### State.toString() -Get a stringified version of the State + +Gets a stringified version of the `State`. ### State.map(f) -Apply the function f to the right portion of the State -| Param | Type | Description | -| --- | --- | --- | -| f | function | Function | +Applies the function `f` to the right portion of the `State`. + +| Param | Type | Description | +| ----- | --------------------- | ----------- | +| f | function | Function | ### State.getValue() -Get the function within the State + +Gets the function within the `State`. ### State.ap(t) -ap allows for values wrapped in a State to be applied to functions also wrapped in a State. In order to use ap, the State must contain a function as its value on the right section. -| Param | Type | Description | -| --- | --- | --- | -| t | [State](#State) | State with function as the second element | +`ap` allows for values wrapped in a `State` to be applied to functions also wrapped in a `State`. In order to use `ap`, the `State` must contain a function as its value on the right side. + +| Param | Type | Description | +| ----- | ---------------------------- | ---------------------------------------------- | +| t | [State](#State) | A `State` with a function as its right element | ### State.chain(f) -Chain together many computations that return a State -| Param | Type | Description | -| --- | --- | --- | -| f | function | Function that returns another State | +Chains together many computations that return a `State`. + +| Param | Type | Description | +| ----- | --------------------- | ------------------------------------- | +| f | function | Function that returns another `State` | ### State.runWith(s) -As State is a lazy datatype that requires a initial state to run, it's instance provides a runWith method that takes in a initial state and returns the result of the computation as a Pair result state. -| Param | Type | Description | -| --- | --- | --- | -| s | any | An initial state that needs to be passed to the State | +Since `State` is a lazy datatype that requires an initial state to run, it provides a `runWith` method that takes in an initial state and returns the result of the computation as a `Pair result state`. + +| Param | Type | Description | +| ----- | ---------------- | ------------------------------------------------------- | +| s | any | An initial state that needs to be passed to the `State` | ### State.execWith(s) -When called, execWith will run the state transition with the given value as the initial state and will return the state. -| Param | Type | Description | -| --- | --- | --- | -| s | any | An initial state that needs to be passed to the State | +When called, `execWith` will run the state transition with the given value as the initial state and return the state. + +| Param | Type | Description | +| ----- | ---------------- | ------------------------------------------------------- | +| s | any | An initial state that needs to be passed to the `State` | ### State.evalWith(s) -When called, evalWith will run the state transition with the given value as the initial state and will return the result. -| Param | Type | Description | -| --- | --- | --- | -| s | any | An initial state that needs to be passed to the State | +When called, `evalWith` will run the state transition with the given value as the initial state and return the result. + +| Param | Type | Description | +| ----- | ---------------- | ------------------------------------------------------- | +| s | any | An initial state that needs to be passed to the `State` | diff --git a/docs/task.md b/docs/task.md index 60b92da..1195b10 100644 --- a/docs/task.md +++ b/docs/task.md @@ -1,112 +1,119 @@ ## Task -A Task makes it easy to model asynchronous operations that may fail, like HTTP requests or reading/writing to a files/databases + +A `Task` makes it easy to model asynchronous operations that may fail, such as HTTP requests or reading/writing to files/databases. **Implements:** [Monad](https://github.com/fantasyland/fantasy-land#monad), [Semigroup](https://github.com/fantasyland/fantasy-land#semigroup) -* [Task](#Task) - * [Task(f)](#new_Task_new) - * [.of](#Task.of) - * [.rejected](#Task.rejected) - * [.fork](#Task.fork) - * [.toString()](#Task.toString) - * [.map(f)](#Task.map) - * [.getValue()](#Task.getValue) - * [.ap(t)](#Task.ap) - * [.concat(t)](#Task.concat) - * [.chain(f)](#Task.chain) - * [.toPromise()](#Task.toPromise) +- [Task](#task) + - [Task(f)](#taskf) + - [Task.of(v)](#taskofv) + - [Task.rejected(v)](#taskrejectedv) + - [Task.fork(reject, resolve)](#taskforkreject-resolve) + - [Task.toString()](#tasktostring) + - [Task.map(f)](#taskmapf) + - [Task.getValue()](#taskgetvalue) + - [Task.ap(t)](#taskapt) + - [Task.concat(t)](#taskconcatt) + - [Task.chain(f)](#taskchainf) + - [Task.toPromise()](#tasktopromise) ### Task(f) -Task constructor +`Task` constructor. -| Param | Type | Description | -| --- | --- | --- | -| f | function | A function that takes two arguments reject and resolve, which in turn are functions. Function f normally initiates an asynchronous work or one that has effects, and then, once it completes, either calls the resolve function to resolve the Task or else rejects it. | +| Param | Type | Description | +| ----- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| f | function | A function that takes two arguments: `reject` and `resolve`, which are functions. The function `f` normally initiates an asynchronous task or one that has side effects, and once it completes, it either calls the `resolve` function to resolve the task or rejects it. | ### Task.of(v) -Task constructor that creates a Task which immediately resolves +`Task` constructor that creates a `Task` which immediately resolves. -| Param | Type | Description | -| --- | --- | --- | -| v | any | value that is passed to the resolve function | +| Param | Type | Description | +| ----- | ---------------- | -------------------------------------------------- | +| v | any | The value that is passed to the `resolve` function | ### Task.rejected(v) -Task constructor that creates a Task which immediately gets rejected +`Task` constructor that creates a `Task` which immediately gets rejected. -| Param | Type | Description | -| --- | --- | --- | -| v | any | value that is passed to the rejected function | +| Param | Type | Description | +| ----- | ---------------- | --------------------------------------------------- | +| v | any | The value that is passed to the `rejected` function | ### Task.fork(reject, resolve) -Executes the Task +Executes the `Task`. -| Param | Type | Description | -| --- | --- | --- | -| reject | function | Function to be called when the Task is rejected | -| resolve | function | Function to be called when the Task is resolved | +| Param | Type | Description | +| ------- | --------------------- | ------------------------------------------------- | +| reject | function | Function to be called when the `Task` is rejected | +| resolve | function | Function to be called when the `Task` is resolved | ### Task.toString() -Get a stringified version of the Task + +Gets a stringified version of the `Task`. ### Task.map(f) -Apply the function f to value of a successfully resolved Task -| Param | Type | Description | -| --- | --- | --- | -| f | function | Function | +Applies the function `f` to the value of a successfully resolved `Task`. + +| Param | Type | Description | +| ----- | --------------------- | ----------- | +| f | function | Function | ### Task.getValue() -Get the function within the Task + +Gets the function within the `Task`. ### Task.ap(t) -Applys the successful value of the Task t to the successful value(a function) of the current Task -| Param | Type | Description | -| --- | --- | --- | -| t | [Task](#Task) | Task with function as the second element | +Applies the successful value of the `Task` `t` to the successful value (a function) of the current `Task`. + +| Param | Type | Description | +| ----- | -------------------------- | -------------------------------------------- | +| t | [Task](#Task) | `Task` with a function as the second element | ### Task.concat(t) -Concat the current Task with the passed one and get a new Task. Which when resloved would get the successfull result of both the tasks. +Concatenates the current `Task` with the passed one and returns a new `Task`. When resolved, it will return the successful result of both tasks. -| Param | Type | Description | -| --- | --- | --- | -| t | [Task](#Task) | Task to concat | +| Param | Type | Description | +| ----- | -------------------------- | --------------------- | +| t | [Task](#Task) | `Task` to concatenate | ### Task.chain(f) -Chain together many computations that return a Task -| Param | Type | Description | -| --- | --- | --- | -| f | function | Function that returns another Task | +Chains together many computations that return a `Task`. + +| Param | Type | Description | +| ----- | --------------------- | ------------------------------------ | +| f | function | Function that returns another `Task` | ### Task.toPromise() -Converts the current task to a Promise + +Converts the current `Task` to a `Promise`. diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..400783b --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,15 @@ +site_name: KudoJS Documentation +theme: + name: material +nav: + - Home: README.md + - Setup: setup.md + - Helper Functions: helper-functions.md + - Algebraic Data Types: + - Identity: identity.md + - Pair: pair.md + - Maybe: maybe.md + - Either: either.md + - Task: task.md + - Reader: reader.md + - State: state.md