Skip to content

Commit

Permalink
Update README
Browse files Browse the repository at this point in the history
  • Loading branch information
rgeraldporter committed Jun 9, 2018
1 parent 2694d78 commit 2454dc9
Show file tree
Hide file tree
Showing 2 changed files with 22 additions and 22 deletions.
42 changes: 21 additions & 21 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
# Inquiry
### v0.19.1
### v0.19.2

[![Build Status](https://travis-ci.com/rgeraldporter/inquiry-monad.svg?branch=master)](https://travis-ci.com/rgeraldporter/inquiry-monad)

Inquiry creates a process flow that allows one to chain multiple functions together to test a value ("subject"), granting observability over all results and returning a full report containing successes, failures, and the original test subject without mutation.

Inquiry's API is comparible to Promises, and is designed to have an expressive, friendly API. It utilizes the concepts of functional programming, though experience with functional programming is not meant to be a requirement for ease of use.
Inquiry's API is comparible to Promise chains, and is designed to have an expressive, friendly API. It utilizes the concepts of functional programming, though experience with functional programming is not meant to be a requirement for ease of use.

To those experienced with functional programming, Inquiry can be compared with an `Either` or a `Validation`.

Expand All @@ -32,7 +32,7 @@ Inquiry.subject(subjectData)
.inquire(x => x.d ? Pass('is no d value') : Fail('has a d value')) // anonymous functions work as well
.join();

// >> result: {subject: {a:1, b:false}, pass: Pass(['has a', 'b is valid', 'has no c value', 'has no d value']), fail: Fail([]), iou: IOU([])}
// result: {subject: {a:1, b:false}, pass: Pass(['has a', 'b is valid', 'has no c value', 'has no d value']), fail: Fail([]), iou: IOU([])}

/* With failures */
const subjectDataWithFailure = {
Expand All @@ -47,22 +47,21 @@ Inquiry.subject(subjectDataWithFailure)
.inquire(hasNoC)
.join();

// >> result: {subject: {a:1, b:'string', c:true}, pass: Pass(['has a']), fail: Fail(['b is invalid', 'has c value']), iou: IOU()}
// result: {subject: {a:1, b:'string', c:true}, pass: Pass(['has a']), fail: Fail(['b is invalid', 'has c value']), iou: IOU()}

/* With async Promises */
const checkDb = async x =>
Promise.resolve(Pass('pretend I looked something up in a db'));

InquiryP.subject(subjectDataWithFailure)
.informant(console.log)
.inquire(checkDb)
.inquire(hasA)
.inquire(validateB)
.inquire(hasNoC)
.conclude(x => x, y => y);
// .conclude or another "unwrap" fn is necessary to complete "IOUs" to give a clean exit (resolve all unresolved Promises)

// >> Promise.resolve(result: {subject: {a:1, b:'string', c:true}, pass: Pass(['has a', 'pretend I looked something up in a db']), fail: Fail(['b is invalid', 'has c value']), iou: IOU()})
// result: Promise.resolve(result: {subject: {a:1, b:'string', c:true}, pass: Pass(['has a', 'pretend I looked something up in a db']), fail: Fail(['b is invalid', 'has c value']), iou: IOU()})
```

## Get started
Expand Down Expand Up @@ -92,7 +91,7 @@ There are three result types used in Inquiry:
* `Fail`: a negative result
* `IOU`: a result to be determined later (relevant to `InquiryP` and `InquiryF` chains only)

Each of these types is a monad, and come with built-in methods for handling and exposing their data without mutating the values. See `Monad methods` below for details on how to handle results within these types.
Each of these types is a monad, and come with built-in methods for handling and exposing their data without mutating the values. See "Monad methods" below for details on how to handle results within these types.

## Inquiry subject type

Expand All @@ -101,7 +100,7 @@ The subject uses `Maybe` to contain the value, which can result in one of two ty
* `Just`: a non-null, non-undefined value
* `Nothing`: an undefined or null value

These are also monads, see `Monad methods` below for details on how to handle these types.
These are also monads, see "Monad methods" below for details on how to handle these types.

## Use

Expand All @@ -127,7 +126,7 @@ For those who might wish to compare to a conventional `Either` (`Left`/`Right`)

## `Inquiry.subject(value)`

Returns a new `Inquiry` monad, which contains an object with properties `subject`, `pass`, `fail`, `iou`, and a single method, `informant`.
Returns a new `Inquiry` monad, which contains an object with properties `subject`, `pass`, `fail`, `iou`, and a single method, `informant`.

* `subject`: the `value` that was passed to `Inquiry.subject`. This value is contained within a `Maybe` monad, meaning it will either be `Just(value)` or `Nothing()`.
* `pass`: a `Pass` monad, containing an array of values
Expand All @@ -146,14 +145,15 @@ Also same, however it returns a monad called `InquiryF` which enables function `
As a basic example:

```js
const checkDb = x =>
Future.of(Pass('pretend I looked something up in a db'));

const value = { something: true };
console.log(
Inquiry.subject(value)
.informant(console.log)
.join()
); // .join will reveal contained value
InquiryF.subject(value)
.inquire(checkDb)
.fork(console.error, console.log);

// > {subject: Just({something: true}), pass: Pass([]), fail: Fail([]), iou: IOU([]), informant: console.log};
// console.log >> {subject: Just({something: true}), pass: Pass(['pretend I looked something up in a db']), fail: Fail([]), iou: IOU([]), informant: null};
```

## `Inquiry.of(inquiry)`
Expand Down Expand Up @@ -186,7 +186,7 @@ console.log(result);

### `.inquireMap(f, i)`

Map version of `.inquire`. Pass function `f` that can curried `i` and `subject`, and collect `Pass`, `Fail`, `IOU` from the results.
Map version of `.inquire`. Pass function `f` that can curry both `i` and `subject`, and collect `Pass`, `Fail`, `IOU` from the results.

This can be useful to prevent sprawling `.inquire` chains.

Expand Down Expand Up @@ -347,31 +347,31 @@ console.log(results);

Runs function `f` against the `Fail` list -- but only if there are items in that list. Otherwise returns the `Inquiry`.

i.e., "Run the function when something fails."
i.e., "Run the function if something fails."

Functionally equivalent to `.conclude(f, x => x)`.

### `.cleared(f)`

Runs function `f` against the `Pass` list -- but only if there are no items in the `Fail` list. Otherwise, returns the `Inquiry`.

i.e., "Run the function when everything passes."
i.e., "Run the function if everything passes."

Functionally opposite of `.faulted(f)`. These two can be in the same chain.

### `.suffice(f)`

Runs function `f` against the `Pass` list -- but only if there are items in the `Pass` list. Otherwise, returns the `Inquiry`. (This is a `Pass`-preferring version of `faulted`.)

i.e., "Run the function when something passes."
i.e., "Run the function if something passes."

Functionally equivalent to `.conclude(x => x, f)`.

### `.scratch(f)`

Runs function `f` against the `Pass` list -- but only if there are no items in the `Pass` list. Otherwise, returns the `Inquiry`.
Runs function `f` against the `Fail` list -- but only if there are no items in the `Pass` list. Otherwise, returns the `Inquiry`.

i.e., "Run the function when everything fails"
i.e., "Run the function if everything fails"

Functionally opposite of `.suffice(f)`. These two can be in the same chain.

Expand Down
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "inquiry-monad",
"version": "0.19.1",
"version": "0.19.2",
"description": "A module for chaining testing functions and returning an aggregate of both passes and failures and the original value. Functional, much like an Either.",
"main": "built/index.js",
"scripts": {
Expand Down

0 comments on commit 2454dc9

Please sign in to comment.