# `appy`

The `appy` package provides functions to interface with HATEOAS API endpoints.

## Types

### `MissingApplicationId`

```ts
interface MissingApplicationId {
  kind: 'missing-application-id';
}
```

### `AppyError`

```ts
import { MissingApplicationId } from '@execonline-inc/appy';
import { HttpError } from 'ajaxian';

type AppyError = HttpError | MissingApplicationId;
```

### `HReferenceable`

```ts
import { HttpError, Method } from 'ajaxian';

interface HReferenceable {
  href: string;
  method: Method;
}
```

## Functions

### `request`

This curried function creates an HTTP request `Task` using a given authentication token, HATEOAS link, and payload data, and decodes the response using the given decoder.

```ts
import { AppyError, HReferenceable, request } from '@execonline-inc/appy';
import Decoder, { succeed } from 'jsonous';
import { Maybe, just } from 'maybeasy';
import { Task } from 'taskarian';

const token: Maybe<string> = just('3ad1afde-6d9f-4e29-97d4-4396f891267f');
const link: HReferenceable = { href: 'https://example.com/', method: 'get' };
interface Response {}
const decoder: Decoder<Response> = succeed({});
const payload = {};

const req: Task<AppyError, RequestBuilder<Response>> = request(token)(link, decoder, payload);
```

### `callApi`

Similar to `request`, this function creates an HTTP request `Task`. The significant differences are that a given `Task` is executed when the response indicates that the authentication is invalid, and the ultimate return value is an object of the decoded type itself, not one wrapped in a `RequestBuilder` object.

```ts
import { AppyError, callApi, HReferenceable } from '@execonline-inc/appy';
import Decoder, { succeed } from 'jsonous';
import { Maybe, just } from 'maybeasy';
import { Task } from 'taskarian';

const token: Maybe<string> = just('3ad1afde-6d9f-4e29-97d4-4396f891267f');
const link: HReferenceable = { href: 'https://example.com/', method: 'get' };
const whenUnauthenticated: Task<never, void> = new Task(() => noop);
interface Response {}
const decoder: Decoder<Response> = succeed({});
const payload = {};

const req: Task<AppyError, Response> = callApi(token)(whenUnauthenticated)(decoder, payload)(link);
```

### `postToApi`

Similar to `callApi`, this function creates an HTTP request `Task`, but it's hardcoded for the `post` verb and does not decode the response.

```ts
import { AppyError, HReferenceable, postToApi } from '@execonline-inc/appy';
import { Maybe, just } from 'maybeasy';
import { Task } from 'taskarian';

const token: Maybe<string> = just('3ad1afde-6d9f-4e29-97d4-4396f891267f');
const link: HReferenceable = { href: 'https://example.com/', method: 'post' };
const whenUnauthenticated: Task<never, void> = new Task(() => noop);
const payload = {};

const req: Task<AppyError, string> = postToApi(token)(whenUnauthenticated)(payload)(link);
```

### `putToApi`

Similar to `callApi`, this function creates an HTTP request `Task`, but it's hardcoded for the `put` verb and does not decode the response.

```ts
import { AppyError, HReferenceable, putToApi } from '@execonline-inc/appy';
import { Maybe, just } from 'maybeasy';
import { Task } from 'taskarian';

const token: Maybe<string> = just('3ad1afde-6d9f-4e29-97d4-4396f891267f');
const link: HReferenceable = { href: 'https://example.com/', method: 'put' };
const whenUnauthenticated: Task<never, void> = new Task(() => noop);
const payload = {};

const req: Task<AppyError, string> = putToApi(token)(whenUnauthenticated)(payload)(link);
```

### `deleteToApi`

Similar to `callApi`, this function creates an HTTP request `Task`, but it's hardcoded for the `delete` verb, does not decode the response, and does not accept request payload data.

```ts
import { AppyError, deleteToApi, HReferenceable } from '@execonline-inc/appy';
import { Maybe, just } from 'maybeasy';
import { Task } from 'taskarian';

const token: Maybe<string> = just('3ad1afde-6d9f-4e29-97d4-4396f891267f');
const link: HReferenceable = { href: 'https://example.com/', method: 'delete' };
const whenUnauthenticated: Task<never, void> = new Task(() => noop);

const req: Task<AppyError, string> = deleteToApi(token)(whenUnauthenticated)(link);
```

### `getFromApi`

Similar to `callApi`, this function creates an HTTP request `Task`, but it's hardcoded for the `get` verb and does not decode the response.

```ts
import { AppyError, getFromApi, HReferenceable } from '@execonline-inc/appy';
import { Maybe, just } from 'maybeasy';
import { Task } from 'taskarian';

const token: Maybe<string> = just('3ad1afde-6d9f-4e29-97d4-4396f891267f');
const link: HReferenceable = { href: 'https://example.com/', method: 'get' };
const whenUnauthenticated: Task<never, void> = new Task(() => noop);
const payload = {};

const req: Task<AppyError, string> = getFromApi(token)(whenUnauthenticated)(payload)(link);
```

### `getRespFromApi`

Similar to `callApi`, this function creates an HTTP request `Task`, but it's hardcoded for the `get` verb, does not decode the response, and returns the entire successful response object rather than just its body.

```ts
import { AppyError, getRespFromApi, HReferenceable } from '@execonline-inc/appy';
import { Maybe, just } from 'maybeasy';
import { Task } from 'taskarian';

const token: Maybe<string> = just('3ad1afde-6d9f-4e29-97d4-4396f891267f');
const link: HReferenceable = { href: 'https://example.com/', method: 'get' };
const whenUnauthenticated: Task<never, void> = new Task(() => noop);
const payload = {};

const req: Task<AppyError, HttpSuccess<string>> = getRespFromApi(token)(whenUnauthenticated)(
  payload
)(link);
```


# `collections`

The `collections` package provides functions to work with lists in various ways.

## Functions

### `bifurcateWhen`

This function splits an array once the provided function evaluates to `true` for an element of that array. The element that resulted in the `true` evaluation is the first element of the second returned array.

```ts
import { bifurcateWhen } from '@execonline-inc/collections';

const list = [1, 2, 3, 4, 5];
const result = bifurcateWhen((item: number): boolean => item === 3, list);
// [[1, 2], [3, 4, 5]]
```

### `bifurcateBy`

This function splits an array by the evaluation of the provided function. Array elements that evaluate to `true` are returned as the first bifurcated array, those that evaluate to `false` are returned as the second bifurcated array.

```ts
import { bifurcateBy } from '@execonline-inc/collections';

const list = [1, 2, 3, 4, 5];
const isEven = (item: number): boolean => !(item % 2);
const result = bifurcateBy(isEven, list);
// [[2, 4], [1, 3, 5]]
```

### `concat`

This curried function simply concatenates two arrays.

```ts
import { concat } from '@execonline-inc/collections';

const listA = [1, 2, 3];
const listB = [4, 5, 6];

const result = concat(listA)(listB);
// [1, 2, 3, 4, 5, 6]
```

### `concatAll`

This function takes an array of arrays, and concatenates them all in order.

```ts
import { concatAll } from '@execonline-inc/collections';

const lists = [
  [1, 2, 3],
  [4, 5, 6],
  [7, 8, 9],
];

const result: number[] = concatAll(lists);
// [1, 2, 3, 4, 5, 6, 7, 8, 9]
```

### `drop`

`drop` creates a new array by dropping the specified number of items from the front of the array.

This function has a curried and non-curried form.

```ts
import { drop } from '@execonline-inc/collections';

const list = [1, 2, 3, 4, 5];
const result = drop(3)(list);
// [ 4, 5 ]
```

### `dropUntil`

This function has a curried and non-curried form. It takes an evaluation function and an array.

The evaluation function is called on elements of the array until it evaluates to `true`. The element that caused the function to evaluate to `true` and subsequent elements of the array are returned in a new array.

```ts
import { dropUntil } from '@execonline-inc/collections';

const list = [1, 2, 3, 4, 5];
const result: number[] = dropUntil((item: number): boolean => item === 3)(list);
// [3, 4, 5]
```

### `uniqBy`

This curried function takes a transformation function and an array. Each element of the array is passed to the transformation function. Duplicate evaluations of this function exlude the corresponding original element from the returned array.

```ts
import { uniqBy } from '@execonline-inc/collections';

const list = [1, 2, 3, 4, 5];
const result: number[] = uniqBy((item: number): string => (item > 3 ? String(item) : ''));
// [1, 4, 5]
```

### `uniq`

This function returns only the unique elements of a given array.

```ts
import { uniq } from '@execonline-inc/collections';

const list = [1, 1, 2, 3, 3];
const result: number[] = uniq(list);
// [1, 2, 3]
```

### `find`

`find` returns the first matching element in an Array.

Matching is determined by the function passed as the first argument.
If it returns true, then a match has been identified.

If a match is found, the item is return wrapped in a `Just`.
Otherwise, a `Nothing` is returned.

This function has a curried and non-curried form.

```ts
import { find } from '@execonline-inc/collections';
import { Maybe } from 'maybeasy';

const list = [1, 2, 3];
const result: Maybe<number> = find((item: number): boolean => item === 2)(list);
// Just<2>
```

### `findIndex`

`findIndex` takes an evaluation function and an array.

The evaluation function is called on elements of the array until it evaluates to `true`, at which point that element's index is returned as a `Just`. If no element is found, a `Nothing` iss returned.

This function has a curried and non-curried form.

```ts
import { findIndex } from '@execonline-inc/collections';
import { Maybe } from 'maybeasy';

const list = [1, 2, 3];
const result: Maybe<number> = findIndex((item: number): boolean => item === 2)(list);
// Just<1>
```

### `findR`

This curried function operates like `find<T>`, but returns a `Result<NothingFound, T>` instead of a `Maybe<T>`.

```ts
import { findR, NothingFound } from '@execonline-inc/collections';

const list = [1, 2, 3];
const result: Result<NothingFound, number> = findR((item: number): boolean => item === 4)(list);
// Err<NothingFound>
```

### `findItem`

This curried function finds the first item of the given ID in an array of objects of the interface `{ id: number }`.

```ts
import { findItem } from '@execonline-inc/collections';
import { Maybe } from 'maybeasy';

const list = [{ id: 1 }, { id: 2 }, { id: 3 }];
const result: Maybe<{ id: number }> = findItem(2)(list);
// Just<{ id: 2 }>
```

### `findItemT`

This curried function wraps `findItem` functionality in a `Task`. It is particularly useful in chaining of tasks:

```ts
import { findItemT, ItemNotFound } from '@execonline-inc/collections';
import { Task } from 'taskarian';

const list = [{ id: 1 }, { id: 2 }, { id: 3 }];
const task = Task.succeed<ItemNotFound, { id: number }[]>(list);

const example: Task<ItemNotFound, { id: 2 }> = task.andThen(findItemT(2));
```

### `findPayload`

`findPayload` accepts an ID and a list of payloads of a `{ payload: { id: number } }` interface and returns the first payload with the matching ID as a `Maybe`.

This function has a curried and non-curried form

```ts
import { findPayload } from '@execonline-inc/collections';
import { Maybe } from 'maybeasy';

const payloads = [{ payload: { id: 1 } }, { payload: { id: 2 } }, { payload: { id: 3 } }];
const result: Maybe<{ payload: { id: number } }> = findPayload(2)(payloads);
// Just<{ payload: { id: 2 } }>
```

### `findPayloadT`

Same as `findItemT` but with the functionality of `findPayload`.

```ts
import { findPayloadT, PayloadNotFound } from '@execonline-inc/collections';
import { Task } from 'taskarian';

const payloads = [{ payload: { id: 1 } }, { payload: { id: 2 } }, { payload: { id: 3 } }];
const task = Task.succeed<PayloadNotFound, { payload: { id: number } }[]>(payloads);

const example: Task<PayloadNotFound, { payload: { id: 2 } }> = task.andThen(findPayloadT(2));
```

### `findPayloadByUuid`

Same as `findPayload` but takes a `string` as the UUID to find and a list of payloads of a `{ payload: { uuid: string } }` interface.

```ts
import { findPayloadByUuid } from '@execonline-inc/collections';
import { Maybe } from 'maybeasy';

const payloads = [
  { payload: { uuid: 'cb08aa12-30f3-48b4-a6ec-bb95ca1e021d' } },
  { payload: { uuid: 'e1da03ff-46ff-49c9-bb69-a09ea68fbd76' } },
  { payload: { uuid: 'ea4c9aa3-b39b-4c3c-a931-b1bbc921970c' } },
];
const result: Maybe<{ payload: { id: number } }> = findPayloadByUuid(
  'cb08aa12-30f3-48b4-a6ec-bb95ca1e021d'
)(payloads);
// Just<{ payload: { uuid: 'cb08aa12-30f3-48b4-a6ec-bb95ca1e021d' } }>
```

### `groupBy`

This curried function takes a function to derive the group key for each element and an array of items.

```ts
import { groupBy } from '@execonline-inc/collections';

const list = ['abc-123', 'abc-456', 'def-789'];
const result = groupBy((item: string): string => item.split('-').shift())(list);
// { 'abc': ['abc-123', 'abc-456'], 'def': ['def-789'] }
```

### `toPairs`

This function takes an object and returns an array of key-value pairs.

```ts
import { toPairs } from '@execonline-inc/collections';

const obj = {
  abc: 123,
  def: 456,
};
const result = toPairs(obj);
// [['abc', 123], ['def', 456]]
```

### `map`

This curried function takes a transformation function and a list of items to return a new list of items.

```ts
import { map } from '@execonline-inc/collections';

const list = [1, 2, 3];
const result: number[] = map((item: number): number => item + 10)(list);
// [11, 12, 13]
```

### `flatMap`

`flatMap` takes a list of items and a transformation function that returns an array for each item. The final return value is a flattened array of each of those resulting arrays.

This function has curried and non-curried form.

```ts
import { flatMap } from '@execonline-inc/collections';

const list = [1, 2, 3];
const result = flatMap((item: number): number[] => [10, 100, 1000].map(n => n * item))(list);
// [10, 100, 1000, 20, 200, 2000, 30, 300, 3000]
```

### `mapMaybe`

`mapMaybe` takes a list of items and a function that maps each item of the array to a `Maybe`. The final return value is an array of only the mapped values that were a `Just`.

This function has curried and non-curried form.

```ts
import { mapMaybe } from '@execonline-inc/collections';
import { Maybe } from 'maybeasy';

const list = [1, 2, 3, 4, 5, 6];
const result = mapMaybe(
  (item: number): Maybe<number> => item % 2 ? nothing() : just(item);
)(list);
// [2, 4, 6]
```

### `byId`

This curried function checks whether the given ID matches the ID in the given payload.

```ts
import { byId } from '@execonline-inc/collections';

const payload = { id: 123 };
const result: boolean = byId(123)(payload);
```

### `byPayloadId`

This curried function checks whether the given ID matches the ID in the given resource.

```ts
import { byPayloadId } from '@execonline-inc/collections';

const resource = { payload: { id: 123 } };
const result: boolean = byPayloadId(123)(resource);
```

### `byPayloadUuid`

This curried function checks whether the given UUID matches the UUID in the given resource.

```ts
import { byPayloadUuid } from '@execonline-inc/collections';

const resource = { payload: { id: '9f925583-7a8f-4459-979d-5ad2d5ede2f8' } };
const result: boolean = byPayloadUuid('9f925583-7a8f-4459-979d-5ad2d5ede2f8')(resource);
```

### `sort`

`sort` provides stable sorting of an array using a given comparison function.

The comparison function should return:

- `< 0` to sort `a` before `b`
- `0` to consider `a` equal to `b`
- `> 0` to sort `a` after `b`

This function has a curried and non-curried form.

```ts
import { sort } from '@execonline-inc/collections';

const list = [
  { age: 30, name: 'Ava' },
  { age: 25, name: 'Bob' },
  { age: 20, name: 'Cas' },
  { age: 25, name: 'Dan' },
];
const result = sort((a, b) => a.age - b.age)(list);
// [{ age: 20, name: 'Cas' }, { age: 25, nam: 'Bob' }, { age: 25, name: 'Dan' }, { age: 30, name: 'Ava' }]
```

### `take`

`take` creates a new array of the specified amount of items from the given array from its beginning.

This function has a curried and non-curried form.

```ts
import { take } from '@execonline-inc/collections';

const list = [1, 2, 3, 4, 5];
const result = take(3)(list);
// [1, 2, 3]
```

### `first`

This function returns the first item from an array. When present, the item is wrapped in a `Just`, otherwise the return value is a `Nothing`.

```ts
import { first } from '@execonline-inc/collections';

const list = [1, 2, 3];
const result = first(list);
// Just<1>
```

### `last`

This function returns the last item from an array. When present, the item is wrapped in a `Just`, otherwise the return value is a `Nothing`.

```ts
import { last } from '@execonline-inc/collections';

const list = [1, 2, 3];
const result = last(list);
// Just<3>
```

### `takeLastUntil`

`takeLastUntil` returns a new array of the items from the end of the given array until the given function evalutes `true`.

This function has a curried and non-curried form.

```ts
import { takeLastUntil } from '@execonline-inc/collections';

const list = [1, 2, 3, 4, 5];
const result = takeLastUntil((item: number): boolean => item === 3)(list);
// [4, 5]
```

### `takeLastWhile`

`takeLastWhile` returns a new array of the items from the end of the given array while the given function evaluates `true`.

This function has a curried and non-curried form.

```ts
import { takeLastWhile } from '@execonline-inc/collections';

const list = [1, 2, 3, 4, 5];
const result = takeLastWhile((item: number): boolean => item > 3)(list);
// [4, 5]
```


# `decoders`

The `decoders` package provides useful utility decoder implementations.

```ts
import * as decoders from '@execonline-inc/decoders';

import Decoder, { fail, field, succeed } from 'jsonous';
import { fromEmpty, Maybe } from 'maybeasy';
import { Result } from 'resulty';
```

## Functions

### `eql`, `stringLiteral`

The `eql` decoder decodes for a specific value rather than some type. The `stringLiteral` decoder is an application of the `eql` decoder for just `string` values.

```ts
import { eql } from '@execonline-inc/decoders';
import Decoder from 'jsonous';
import { Result } from 'resulty';

const example: Decoder<123> = eql<123>(123);
const result: Result<string, 123> = example.decodeAny(123);
```

```ts
import { stringLiteral } from '@execonline-inc/decoders';
import Decoder from 'jsonous';
import { Result } from 'resulty';

const example: Decoder<'abc'> = stringLiteral('abc');
const result: Result<string, 'abc'> = example.decodeAny('abc');
```

### `regexDecoder`

```ts
import { regexDecoder } from '@execonline-inc/decoders';
import Decoder, { fail, succeed } from 'jsonous';

const example: Decoder<string> = regexDecoder(/(abc)/).andThen(result =>
  fromEmpty(result[1]).map(str => succeed(str).getOrElse(() => fail('Could not find "abc"')))
);
```

### `nullableBlankString`

This decoder handles a value that should be a string but could also be `null` or `undefined` and converts it to a `Maybe`.

```ts
import { nullableBlankString } from '@execonline-inc/decoders';
import Decoder from 'jsonous';
import { Result } from 'resulty';

const example: Decoder<Maybe<string>> = nullableBlankString;
const result: Result<string, Maybe<string>> = example.decodeAny('abc');
```

### `base64Decoder`

This decoder decodes input as base64 using the browser's `atob` function. A decoder error is the result from any thrown errors.

```ts
import { base64Decoder } from '@execonline-inc/decoders';
import Decoder from 'jsonous';
import { Result } from 'resulty';

const example: Decoder<string> = base64Decoder;
const result: Result<string, string> = example.decodeAny('aGVsbG8=');
```

### `jsonParserDecoder`

This decoder takes a decoder whose output is parsed as JSON. If JSON parsing fails, then a decoder error is the result.

```ts
import { base64Decoder, jsonParserDecoder } from '@execonline-inc/decoders';
import Decoder from 'jsonous';
import { Result } from 'resulty';

const example: Decoder<string> = jsonParserDecoder(base64Decoder);
const result: Result<string, string> = example.decodeAny('ImhlbGxvIg==');
```

### `pipeD`

This decoder is used to run two decoders in sequence passing the successfully decoded value from the first as the input for the second.

```ts
import { base64Decoder, pipeD, stringLiteral } from '@execonline-inc/decoders';
import Decoder from 'jsonous';
import { Result } from 'resulty';

const example: Decoder<'hello'> = pipeD(base64Decoder, stringLiteral('hello'));
const result: Result<string, string> = example.decodeAny('aGVsbG8=');
```

### `numberToStringDecoder`

```ts
import { numberToStringDecoder } from '@execonline-inc/decoders';
import Decoder from 'jsonous';
import { Result } from 'resulty';

const example: Decoder<string> = numberToStringDecoder;
const result: Result<string, string> = example.decodeAny(123);
```

### `stringToNumberDecoder`

```ts
import { stringToNumberDecoder } from '@execonline-inc/decoders';
import Decoder from 'jsonous';
import { Result } from 'resulty';

const example: Decoder<number> = stringToNumberDecoder;
const result: Result<string, number> = example.decodeAny('123');
```

### `jsonValueDecoder`

TODO

### `secondsDecoder`

```ts
import { secondsDecoder } from '@execonline-inc/decoders';
import Decoder from 'jsonous';
import { Result } from 'resulty';

const example: Decoder<Time> = secondsDecoder;
const result: Result<string, Time> = example.decodeAny(60);
```

### `explicitJust`

This is used to decode a JSON object representing a `Maybe` monad that's expected to be a `Just`:

```ts
import { explicitJust } from '@execonline-inc/decoders';
import Decoder from 'jsonous';
import { Result } from 'resulty';

const thing = { kind: 'just', value: 123 };
const example: Decoder<Maybe<number>> = explicitJust;
const result: Result<string, Maybe<number>> = example.decodeAny(thing);
```

### `explicitNothing`

This is used to decode a JSON object representing a `Maybe` monad that's expected to be a `Nothing`:

```ts
import { explicitNothing } from '@execonline-inc/decoders';
import Decoder from 'jsonous';
import { Result } from 'resulty';

const thing = { kind: 'nothing' };
const example: Decoder<Maybe<number>> = explicitNothing;
const result: Result<string, Maybe<number>> = example.decodeAny(thing);
```

### `explicitMaybe`

This is used to decode a JSON object representing a `Maybe` monad that could be either a `Just` or a `Nothing`.

### `mergeObjectDecoders`

This will produce a single decoder by combining the decoded fields of the two given decoders.

If the given decoders overlap for any fields, the second decoder will decide the final value for those fields.

```ts
import { mergeObjectDecoders, stringLiteral } from '@execonline-inc/decoders';
import Decoder, { field } from 'jsonous';
import { Result } from 'resulty';

interface A {
  foo: string;
  bar: string;
}
interface B {
  bar: 'star';
  baz: 'jazz';
}

const objA: A = { foo: 'goo', bar: 'car' };
const objB: B = { bar: 'star', baz: 'jazz' };

const decoderA: Decoder<A> = succeed({})
  .assign('foo', field('foo', string))
  .assign('bar', field('bar', string));
const decoderB: Decoder<B> = succeed({})
  .assign('bar', field('bar', stringLiteral('star')))
  .assign('baz', field('baz', stringLiteral('jazz')));

const example: Decoder<A & B> = mergeObjectDecoders(decoderA, decoderB);
const result: Result<string, A & B> = example.decodeAny({ ...objA, ...objB });
```


# `dom`

> TODO: description

## Usage

```
const dom = require('dom');

// TODO: DEMONSTRATE API
```


# `environment`

The `environment` package provides functions read from the execution environment.

## Types

### `MissingVarError`

Resembles the error when the environment variable doesn't exist for a read attempt.

```ts
interface MissingVarError {
  kind: 'missing-var-error';
  key: string;
}
```

### `Production`

Interface representing a production environment.

```ts
interface Production {
  kind: 'production';
}
```

### `Development`

Interface representing a development environment.

```ts
interface Development {
  kind: 'development';
}
```

### `Unknown`

Interface representing an unknown environment.

```ts
interface Unknown {
  kind: 'unknown';
}
```

### `Environment`

```ts
type Environment = Production | Development | Unknown;
```

## Functions

### `missingVarError`

This function takes an environment variable name and constructs a `MissingVarError` type from it.

```ts
import { missingVarError, MissingVarError } from '@execonline-inc/environment';

const result: MissingVarError = missingVarError('SOME_ENV_VAR');
// { kind: 'missing-var-error', key: 'SOME_ENV_VAR' }
```

### `readVarM`

This function reads for a given key from `process.env` and wraps the value in a `Maybe`. When a value exists for the key, the result is a `Just`, otherwise it is a `Nothing`.

```ts
import { readVarM } from '@execonline-inc/environment';
import { Maybe } from 'maybeasy';

const result: Maybe<string> = readVarM('SOME_ENV_VAR');
```

### `readVarR`

Like `readVarM`, but the condition for no value is an error `Result`.

```ts
import { MissingVarError, readVarR } from '@execonline-inc/environment';
import { Result } from 'resulty';

const result: Result<MissingVarError, string> = readVarR('SOME_ENV_VAR');
```

### `readVarT`

Like `readVarR`, but as a `Task` instead of a `Result`.

```ts
import { MissingVarError, readVarT } from '@execonline-inc/environment';
import { Task } from 'taskarian';

const result: Task<MissingVarError, string> = readVarT('SOME_ENV_VAR');
```

### `environment`

This function reads the `NODE_ENV` environment variable and returns an object representing the detected environment.

```ts
import { environment, Environment } from '@execonline-inc/environment';

const result: Environment = environment();
```


# `error-handling`

The `error-handling` package provides several utility functions that allow you to convert between the types Task, Maybe, and Result while handling any errors.

## Functions

### `asTask`
The asTask function takes a Result object as input and converts it into a Task object.

```ts
import { ok } from 'resulty';
import { asTask } from 'error-handling';

const result = ok('test');
const task = asTask(result); // Task
```

### `asMaybe`
The asMaybe function takes a Result object as input and converts it into a Maybe object.

```ts
import { ok } from 'resulty';
import { asMaybe } from 'error-handling';

const result = ok('test');
const task = asMaybe(result); // Maybe
```

### `runResult`
The runResult function tries to execute the throwable input function, and if it throws an error, it returns an Err case with the error as the value. If the input function runs successfully, it returns an Ok case with the returned value.

```ts
import { runResult } from 'error-handling';

const randomErrorFunction = (): boolean => {
  if (Math.random() < 0.5) {
    return true;
  } else {
    throw new Error('Random Error!');
  }
};

const result = runResult(randomErrorFunction); // Result
```

### `runMaybe`

The runMaybe function tries to execute the throwable input function, and returns a maybe. If an error is thrown `nothing()` will be returned and if the function is successful a `just(value)` will be returned.

```ts
import { runMaybe } from 'error-handling';

const randomErrorFunction = (): boolean => {
  if (Math.random() < 0.5) {
    return true;
  } else {
    throw new Error('Random Error!');
  }
};

const maybe = runMaybe(randomErrorFunction); // Maybe
```

### `runTask`
The runTask function tries to execute the throwable input function, and if it throws an error, it returns an Err case with the error as the value. If the input function runs successfully, it returns an Ok case with the returned value.

```ts
import { runTask } from 'error-handling';

const randomErrorFunction = (): boolean => {
  if (Math.random() < 0.5) {
    return true;
  } else {
    throw new Error('Random Error!');
  }
};

const task = runTask(randomErrorFunction); // Task
```

# `logging`

The `logging` package provides a few logging functions.

## Functions

### `logger`

This curried function provides a console logging function with a given prefix.

```ts
import { logger } from '@execonline-inc/logging';

const logger = logger('[EXAMPLE]');
logger('abc', 'def');
// [EXAMPLE] abc def
```

### `warner`

This curried function provides a console warning function with a given prefix.

```ts
import { warner } from '@execonline-inc/logging';

const warner = warner('[EXAMPLE]');
warner('abc', 'def');
// [EXAMPLE] abc def
```

### `log`

_Specific to ExecOnline_

A `logger` with an `[EXO]` prefix.

```ts
import { log } from '@execonline-inc/logging';

log('hello');
// [EXO] hello
```

### `logWithTimestamp`

A logger with a timestamp prefix.

```ts
import { logWithTimestamp } from '@execonline-inc/logging';

logWithTimestamp('hello');
// [2022-05-23T16:34:13.462-04:00] hello
```

### `warn`

_Specific to ExecOnline_

A `warner` with an `[EXO]` prefix.

```ts
import { warn } from '@execonline-inc/logging';

warn('hello');
// [EXO] hello
```

### `warnAndNotify`

_Specific to ExecOnline_

This function accepts an error name, an error message, and a context object. It sends the message to the console using `warn`, and also uses the provided information to post a notification to the third-party [Honeybadger](https://www.honeybadger.io/) exception monitoring service.

```ts
import { warnAndNotify as warnAndNotifyImpl } from '@execonline-inc/logging';

export const warnAndNotify = warnAndNotifyImpl(Honeybadger.notify);

const context = { user_id: 123 };
warnAndNotify('ErrorName', 'Some error message', context);
// [EXO] Some error message
```


# `maybe-adapter`

The `maybe-adapter` package provides functions to convert to/from `Maybe` types.

## Functions

### `toResult`

This function has a curried and non-curried form. It takes an error and a `Maybe`. When the `Maybe` is a `Just`, a successful `Result` is returned with the wrapped value, otherwise an error `Result` is returned with the given error value.

```ts
import { toResult } from '@execonline-inc/maybe-adapter';
import { nothing } from 'maybeasy';

toResult<string, number>('an error message')(nothing());
```

### `toTask`

This function has a curried and non-curried form. It takes an error and a `Maybe`. When the `Maybe` is a `Just`, a succeeding `Task` is returned with the wrapped value, otherwise a failing `Task` is returned with the given error value.

```ts
import { toTask } from '@execonline-inc/maybe-adapter';
import { nothing } from 'maybeasy';

toTask<string, number>('an error message')(nothing());
```

### `fromBool`, `when`

This function has a curried and non-curried form. It wraps a given value in a `Maybe` depending on either the given boolean value or boolean return value of the given function.

Also, if the first argument is a function, the second argument is passed to that function for evaluation. (See advanced usage example)

Aliased as `when`

```ts
import { fromBool } from '@execonline-inc/maybe-adapter';

fromBool(true)(123);
fromBool((): boolean => true)(123);
// Just<123>

// Advanced usage.
mapMaybe(when(even), [1, 2, 3, 4]);
// [2, 4]
```


# `numbers`

Safely parse numbers from strings

## Functions

### `parseIntM`

Attempts to parse an integer from a string, using `Maybe<number>` to wrap the success or failure of
the parse.

```ts
import { parseIntM } from '@execonline-inc/numbers';

parseIntM('123').getOrElseValue(0) // returns `123`
parseIntM('123.42').getOrElseValue(0) // returns `123`
parseIntM('Hello World!').getOrElseValue(0) // returns `0`
```

### `parseIntR`

Attempts to parse an integer from a string, using `Result<NumberParseFailure, number>` to wrap the
success or failure of the parse.

```ts
import { parseIntR } from '@execonline-inc/numbers';

parseIntR('123').getOrElseValue(0) // returns `123`
parseIntR('123.42').getOrElseValue(0) // returns `123`

parseIntR('Hello World').elseDo(console.warn).getOrElseValue(0)
// Prints object: { kind: 'number-parse-failure', message: `Couldn't parse string into a number` }
// Returns 0
```

### `parseIntT`

Attempts to parse an integer from a string, using `Task<NumberParseFailure, number>` to wrap the
success or failure of the parse.

```ts
import { parseIntT } from '@execonline-inc/numbers';

parseIntT('123').fork(() => {}, console.log); // Prints the integer 123
parseIntT('123.42').fork(() => {}, console.log); // Prints the integer 123

parseIntT('Hello World').fork(console.warn, () => {});
// Prints object: { kind: 'number-parse-failure', message: `Couldn't parse string into a number` }
```

### `percentage`

Display a number as a percentage.

```ts
import { percentage } from '@execonline-inc/numbers';

percentage(42.22) // returns the string "42%"
```

# Numeric Predicates

Compare numbers in a declarative way.

## Functions

### `positive`

Check if a value is greater than zero.

```ts
import { positive } from '@execonline-inc/numbers';

positive(10) // true
positive(0) // false

```

### `whenPositive`

A function that returns Maybe is available

```ts
import { whenPositive } from '@execonline-inc/numbers';
import { nothing, just } from 'maybeasy';

const widgetMessage = (value: Maybe<number>) =>
  value
    .andThen(whenPositive)
    .map((count) => `${count} widgets still remain!`)
    .getOrElseValue("No remaining widgets!");

widgetMessage(just(7)) // "7 widgets still remain!"
widgetMessage(just(0)) // "No remaining widgets!"
widgetMessage(nothing()) // No remaining widgets!
```

### `gt`

Check if a value is greater than.

```ts
import { gt } from '@execonline-inc/numbers';
import { just, isJust } from 'maybeasy';

const checkForGreaterThan = (value: number): boolean => just(value).map(gt(10)).isJust();

checkForGreaterThan(7) // evaluates to false
checkForGreaterThan(11) // evaluates to true
```

### `whenGt`

A function that returns Maybe is available

```ts
import { gt, multiplyBy } from '@execonline-inc/numbers';

const checkForGreaterThanAndMultiply = (value: Maybe<number>) =>
  value
    .andThen(whenGt(7))
    .map(multiplyBy(6))
    .getOrElseValue(0);

checkForGreaterThanAndMultiply(4) // evaluates to 0
checkForGreaterThanAndMultiply(11) // evaluates to 66
```

## Other Functions

The following functions work similarly. Many are available with versions that return Maybe.

### `lt`
Less than
### `gte`
Greater than or equal to
### `lte`
Less than or equal to
### `eq`
Equal to
### `neq`
Not equal to
### `between`
Takes a min and max as arguments, returns a boolean.
### `betweenEq`
Takes a min and max as arguments, returns a boolean.
### `even`
Value is even
### `odd`
Value is odd
### `positive`
Value is positive
### `negative`
Value is negative
### `zero`
Value is zero
### `multiplyBy`
Multiplies the value by inputted value
### `divideBy`
Divides the value by inputted value
### `add`
Adds the value to inputted value
### `subtractBy`
Subtracts the value from inputted value



# `resource`

The `resource` package provides types and functions for dealing with HATEOAS REST resources.

## Usage

Create a module dedicated to resources and export as necessary.

```ts
import {
  Link as LinkR,
  payload as payloadR,
  Resource as ResourceR,
  resource as resourceR,
  ResourceWithErrors as ResourceWithErrorsR,
  ResourceWithMetadata as ResourceWithMetadataR,
} from '@execonline-inc/resource';
import { Result } from 'resulty';

const rels = ['prev', 'next', 'self'] as const;

export type Rel = typeof rels[number];

export const toRel = (value: string): Result<string, Rel> =>
  toResult(
    `Expected to find an HTTP rel string. Instead I found ${value}`,
    find(rel => rel === value, rels)
  );

export type Link = LinkR<Rel>;
export type Resource<T> = ResourceR<T, Rel>;
export type ResourceWithErrors<T> = ResourceWithErrorsR<T, Rel>;
export type ResourceWithMetadata<T, M> = ResourceWithMetadataR<T, M, Rel>;

export const resource: <T>(links: ReadonlyArray<Link>, payload: T) => Resource<T> = resourceR;
export const payload: <T, R extends Resource<T>>(r: R) => T = payloadR;
```

## Types

### `ResourceCollection`

```ts
import { Empty, None, Results } from '@execonline-inc/resource';

type ResourceCollection<T, Rel extends string> = None | Empty | Results<T, Rel>;
```

### `None`

```ts
interface None {
  kind: 'none';
}
```

### `Empty`

```ts
interface Empty {
  kind: 'empty';
}
```

### `Results`

```ts
import { Resource } from '@execonline-inc/resource';

interface Results<T, Rel extends string> {
  kind: 'results';
  results: Resource<T[], Rel>;
}
```

### `Link`

```ts
import { Method } from 'ajaxian';

interface Link<Rel extends string> {
  rel: Rel;
  href: string;
  method: Method;
  type: string;
}
```

### `ServerError`

```ts
interface ServerError {
  type: string;
  param: string;
  message: string;
  code: string;
  source: string;
}
```

### `Linkable`

```ts
import { Link } from '@execonline-inc/resource';

interface Linkable<Rel extends string> {
  links: ReadonlyArray<Link<Rel>>;
}
```

### `PossiblyLinkable`

```ts
import { Linkable } from '@execonline-inc/resource';

interface PossiblyLinkable<Rel extends string> {
  whenLinks: Maybe<Linkable<Rel>>;
}
```

### `Payloaded`

```ts
interface Payloaded<T> {
  payload: T;
}
```

### `Resource`

```ts
import { Linkable, Payloaded } from '@execonline-inc/resource';

interface Resource<T, Rel extends string> extends Payloaded<T>, Linkable<Rel> {}
```

### `ResourceWithErrors`

```ts
import { Resource, ServerError } from '@execonline-inc/resource';

interface ResourceWithErrors<T, Rel extends string> extends Resource<T, Rel> {
  errors: ServerError[];
}
```

### `IdentifiablePayload`

```ts
interface IdentifiablePayload {
  id: number;
}
```

### `ResourceWithMetadata`

```ts
import { Resource } from '@execonline-inc/resource';

interface ResourceWithMetadata<T, M, Rel extends string> extends Resource<T, Rel> {
  metadata: M;
}
```

### `ValidationError`

```ts
interface ValidationError {
  kind: 'validation-error';
  on: string;
  param: string;
  error: string;
  detail: string;
}
```

### `ValidationErrors`

```ts
import { ValidationError } from '@execonline-inc/resource';

type ValidationErrors = ValidationError[];
```

### `PaginationMetadata`

```ts
interface PaginationMetadata {
  resultsCount: number;
  pageCount: number;
  perPage: number;
  currentPage: number;
}
```

## Functions

### `none`

Creates a `None` object.

```ts
import { none, ResourceCollection } from '@execonline-inc/resource';

const result: ResourceCollection<unknown, 'self'> = none();
```

### `empty`

Creates an `Empty` object.

```ts
import { empty, ResourceCollection } from '@execonline-inc/resource';

const result: ResourceCollection<unknown, 'self'> = empty();
```

### `results`

Creates a `Results` object.

```ts
import { Link, results, Resource, ResourceCollection } from '@execonline-inc/resource';

interface ExamplePayload {
  kind: 'example-payload';
}
const payload = { kind: 'example-payload' };
const links: ReadonlyArray<Link<'self'>> = [
  {
    rel: 'self',
    href: 'https://example.com/',
    method: 'get',
    type: 'application/json',
  },
];
const resource: Resource<ExamplePayload[], 'self'> = { payload: [payload], links };
const result: ResourceCollection<ExamplePayload, 'self'> = results(resource);
```

### `resources`

This function returns the appropriate `ResourceCollection` type depending on the presence of the given resource and its payload.

```ts
import { Link, resources, Resource, ResourceCollection } from '@execonline-inc/resource';
import { just } from 'maybeasy';

interface ExamplePayload {
  kind: 'example-payload';
}
const payload = { kind: 'example-payload' };
const links: ReadonlyArray<Link<'self'>> = [
  {
    rel: 'self',
    href: 'https://example.com/',
    method: 'get',
    type: 'application/json',
  },
];
const resource: Resource<ExamplePayload[], 'self'> = { payload: [payload], links };
const result: ResourceCollection<ExamplePayload, 'self'> = resources(just(resource));
```

### `linksDecoder`

This function returns a decoder for decoding HATEOAS links with valid `rel` values. It takes a function that checks for valid `rel` values.

```ts
import { find } from '@execonline-inc/collections';
import { toResult } from '@execonline-inc/maybe-adapter';
import { Link, linksDecoder } from '@execonline-inc/resource';
import { Result } from 'resulty';

const validRels = ['self'] as const;
type Rel = typeof validRels[number];
const toRel = (v: string): Result<string, Rel> =>
  toResult(
    `Invalid rel found: ${v}`,
    find(rel => rel === v, validRels)
  );
const linksDecoder: Decoder<ReadonlyArray<Link<Rel>>> = linksDecoder<Rel>(toRel);
```

### `errorDecoder`

This decoder is for a particular error object structure.

```ts
import { errorDecoder, ServerError } from '@execonline-inc/resource';

const obj = {
  type: 'some type',
  param: 'some param',
  code: '123',
  source: 'some source',
  message: 'some message',
};
const decoder: Decoder<ServerError> = errorDecoder;
const result: Result<string, ServerError> = decoder.decodeAny(obj);
```

### `resourceDecoder`

This function with a curried and non-curried form. The returned decoder is for a HATEOAS resource structure.

```ts
import { find } from '@execonline-inc/collections';
import { resourceDecoder, Resource } from '@execonline-inc/resource';
import { toResult } from '@execonline-inc/maybe-adapter';
import { Result } from 'resulty';

type Rel = 'self';
interface ExamplePayload {}
const obj = { payload: {}, links: [] };

const toRel = (v: string): Result<string, Rel> =>
  toResult(
    `Invalid rel found: ${v}`,
    find(rel => rel === v, validRels)
  );

const payloadDecoder: Decoder<ExamplePayload> = succeed({});
const decoder: Decoder<Resource<ExamplePayload, Rel>> = resourceDecoder<ExamplePayload, Rel>(toRel)(
  payloadDecoder
);
const result: Result<string, Resource<ExamplePayload, Rel>> = decoder.decodeAny(obj);
```

### `resourceWithMetadataDecoder`

This curried function returns a decoder for a resource with an additional `metadata` key.

```ts
import { find } from '@execonline-inc/collections';
import { resourceWithMetadataDecoder, ResourceWithMetadata } from '@execonline-inc/resource';
import { toResult } from '@execonline-inc/maybe-adapter';
import Decoder, { succeed } from 'jsonous';
import { Result } from 'resulty';

type Rel = 'self';
interface ExamplePayload {}
interface ExampleMetadata {}

const obj = {
  payload: {},
  links: [],
  metadata: {},
};
const toRel = (v: string): Result<string, Rel> =>
  toResult(
    `Invalid rel found: ${v}`,
    find(rel => rel === v, validRels)
  );

const payloadDecoder: Decoder<ExamplePayload> = succeed({});
const metadataDecoder: Decoder<ExampleMetadata> = succeed({});
const decoder: Decoder<ResourceWithMetadata<
  ExamplePayload,
  ExampleMetadata,
  Rel
>> = resourceWithMetadataDecoder<ExamplePayload, ExampleMetadata, Rel>(toRel)(
  payloadDecoder,
  metadataDecoder
);
const result: Result<
  string,
  ResourceWithMetadata<ExamplePayload, ExampleMetadata, Rel>
> = decoder.decodeAny(obj);
```

### `resourceWithErrorsDecoder`

This curried function returns a decoder for a resource with an additional `errors` key.

```ts
import { find } from '@execonline-inc/collections';
import { resourceWithErrorsDecoder, ResourceWithErrors } from '@execonline-inc/resource';
import { toResult } from '@execonline-inc/maybe-adapter';
import Decoder, { succeed } from 'jsonous';
import { Result } from 'resulty';

type Rel = 'self';
interface ExamplePayload {}

const obj = {
  payload: {},
  links: [],
  errors: [],
};
const toRel = (v: string): Result<string, Rel> =>
  toResult(
    `Invalid rel found: ${v}`,
    find(rel => rel === v, validRels)
  );

const payloadDecoder: Decoder<ExamplePayload> = succeed({});
const decoder: Decoder<ResourceWithErrors<ExamplePayload, Rel>> = resourceWithErrorsDecoder<
  ExamplePayload,
  Rel
>(toRel)(payloadDecoder, metadataDecoder);
const result: Result<string, ResourceWithErrors<ExamplePayload, Rel>> = decoder.decodeAny(obj);
```

### `paginationMetadataDecoder`

This decoder decodes a specific pagination object structure.

```ts
import { paginationMetadataDecoder, PaginationMetadata } from '@execonline-inc/resource';
import { Result } from 'resulty';

const obj = { results_count: 1, page_count: 1, per_page: 1, current_page: 1 };
const result: Result<string, PaginationMetadata> = paginationMetadataDecoder.decodeAny(obj);
```

### `validationErrorDecoder`

This decoder decodes a specific validation error object structure.

```ts
import { validationErrorDecoder, ValidationError } from '@execonline-inc/resource';
import { Result } from 'resulty';

const obj = {
  kind: 'validation-error',
  on: 'that',
  param: 'that',
  error: 'error',
  detail: 'detail',
};
const result: Result<string, ValidationError> = validationErrorDecoder.decodeAny(obj);
```

### `validationErrorsDecoder`

This decoder is for decoding an array with `validationErrorDecoder`.

### `selfUrl`

This function finds the link in a resource with a `rel` of `self`.

```ts
import { Resource, selfUrl } from '@execonline-inc/resource';
import { Maybe } from 'maybeasy';

type Rel = 'self';
interface ExamplePayload {}

const resource: Resource<ExamplePaylod, Rel> = {
  payload: {},
  links: [
    {
      rel: 'self',
      href: 'https://example.com/',
      method: 'get',
      type: 'application/json',
    },
  ],
};
const result: Maybe<Link<Rel>> = selfUrl<ExamplePayload, Rel>(resource);
```

### `iconUrl`

This function finds the link in a resource with a `rel` of `icon`.

```ts
import { iconUrl, Resource } from '@execonline-inc/resource';
import { Maybe } from 'maybeasy';

type Rel = 'icon';
interface ExamplePayload {}

const resource: Resource<ExamplePaylod, Rel> = {
  payload: {},
  links: [
    {
      rel: 'icon',
      href: 'https://example.com/',
      method: 'get',
      type: 'application/json',
    },
  ],
};
const result: Maybe<Link<Rel>> = iconUrl<ExamplePayload, Rel>(resource);
```

### `isNotSelf`

This curried function determines if the given URL is not the same as the link in the resource with a rel of `self`.

```ts
import { isNotSelf, Resource } from '@execonline-inc/resource';

type Rel = 'self';
interface ExamplePayload {}

const resource: Resource<ExamplePaylod, Rel> = {
  payload: {},
  links: [
    {
      rel: 'self',
      href: 'https://example.com/',
      method: 'get',
      type: 'application/json',
    },
  ],
};
const result: boolean = isNotSelf('https://not.example.com/')(resource);
```

### `resource`

This function constructs a resource object given separated links and a payload.

```ts
import { Link, resource, Resource } from '@execonline-inc/resource';

type Rel = 'self';
interface ExamplePayload {}

const links: ReadonlyArray<Link<Rel>> = [];
const payload: ExamplePayload = {};
const result: Resource<ExamplePayload, Rel> = resource<Rel, ExamplePayload>(links, payload);
```

### `payload`

This function retrieves the payload from a given resource.

```ts
import { payload, Resource } from '@execonline-inc/resource';

type Rel = 'self';
interface ExamplePayload {}

const resource: Resource<ExamplePayload, Rel> = { payload: {}, links: [] };
const result: ExamplePayload = payload(resource);
```

### `links`

This function retrieves the links from a given resource.

```ts
import { links, Link, Resource } from '@execonline-inc/resource';

type Rel = 'self';
interface ExamplePayload {}

const resource: Resource<ExamplePayload, Rel> = { payload: {}, links: [] };
const result: ReadonlyArray<Link<Rel>> = links(resource);
```


# `strings`

> TODO: description

## Usage

```
const strings = require('strings');

// TODO: DEMONSTRATE API
```


# `time`

The `time` package provides interfaces and functions for dealing with time durations.

```ts
import * as time from '@execonline-inc/time';
```

## Types

### `Milliseconds`

```ts
interface Milliseconds {
  kind: 'milliseconds';
  milliseconds: number;
}
```

### `Seconds`

```ts
interface Seconds {
  kind: 'seconds';
  seconds: number;
}
```

### `Minutes`

```ts
interface Minutes {
  kind: 'minutes';
  minutes: number;
}
```

### `Hours`

```ts
interface Hours {
  kind: 'hours';
  hours: number;
}
```

### `Days`

```ts
interface Days {
  kind: 'days';
  days: number;
}
```

### `Time`

```ts
import { Days, Hours, Milliseconds, Minutes, Seconds } from '@execonline-inc/time';

type Time = Days | Hours | Minutes | Seconds | Milliseconds;
```

## Functions

### `milliseconds`, `seconds`, `minutes`, `hours`, `days`

These functions accept a `number` and construct an object of the corresponding type with that quantity.

```ts
import * as time from '@execonline-inc/time';

const milliseconds: time.Milliseconds = time.milliseconds(86400000);
const seconds: time.Seconds = time.seconds(86400);
const minutes: time.Minutes = time.minutes(1440);
const hours: time.Hours = time.hours(24);
const days: time.Days = time.days(1);
```

### `toMilliseconds`, `toSeconds`, `toMinutes`, `toHours`, `toDays`

These functions accept a `Time` and convert the quantity of that type to the type that their name states.

```ts
import * as time from '@execonline-inc/time';

const milliseconds: time.Milliseconds = time.toMilliseconds(time.minutes(3));
const seconds: time.Seconds = time.toSeconds(time.hours(3));
const minutes: time.Minutes = time.toMinutes(time.days(2));
const hours: time.Hours = time.toHours(time.milliseconds(1000));
const days: time.Days = time.toDays(time.seconds(200));
```

### `toJS`

This function takes a `Time` and returns the equivalent millisecond count as a `number`.

```ts
import { minutes, toJS } from '@execonline-inc/time';

const millisecondCount: number = toJS(minutes(1));
```


# `time-distance`

The `time-distance` package provides interfaces and functions for dealing with distances between dates.

```ts
import * as time from '@execonline-inc/time-distance';
```

## Types

### `Future`

```ts
interface Future {
  kind: 'future';
  gap: Time;
}
```

### `Now`

```ts
interface Now {
  kind: 'now';
}
```

### `TimeDistance`

```ts
interface Past {
  kind: 'past';
  gap: Time;
}
```

### `Past`

```ts
type TimeVector = Future | Now | Past;
```

### `EffectivelyNow`

```ts
interface EffectivelyNow {
  kind: 'effectively-now';
  time: Time;
}
```

## Functions

### `distanceFrom`

This function computes the gap between two Times. If the first Time is
larger then the second, than the result is considered to be in the
future. A smaller first number is considered to be in the past. And
equal times are considered now.

```ts
import { distanceFrom } from '@execonline-inc/time-distance';
import { Time, seconds } from '@execonline-inc/time';

const time1: Time = seconds(10);
const time2: Time = seconds(20);
distanceFrom(time1, time2); // --> Past { ... }
```

### `distanceFromDate`

This function computes the Time distance between two dates. Be aware
that Date objects in Javascript can be invalid.

```ts
import { distanceFromDate } from '@execonline-inc/time-distance';

const future = distanceFromDate(new Date(1), new Date());
const badDates = distanceFromDate(new Date('foo'), new Date());
```

### `toLargestMeaningfulUnit`

This function converts a TimeDistance so that the gap is expressed in
terms of the largest meaningful time unit. Using this function may
cause a loss of precision on the time gap.

```ts
const distance: TimeVector = distanceBetween(minutes(15), minutes(25));
toLargestMeaningfulUnit(distance);
```

### `largestMeaningfulUnit`

This function takes a Time and returns a new Time that represents
that largest meaningful unit of time. For example, `seconds(60)` would
be converted to `minutes(1)`, since that is the largest unit of time
that isn't effectively zero.

Note that "meaningful" here means meaningful to human beings. Anything
less than a second is treated as EffectivelyNow

```ts
const result: Ok<Time> = largestMeaningfulUnit(seconds(60));
const nowish: Err<EffectivelyNow> = largestMeaningfulUnit(milliseconds(100));
```


# `translations`

The `translations` package provides a library for support of typed translation keys and typed React-based translation interpolation.

## Usage

This library uses the [i18next](https://www.i18next.com/) library underneath a custom adapter. The i18next library handles translating, pluralizing, and basic interpolation (using `{{abc}}` placeholders).

The custom adapter implementation handles type-checking and component interpolation (using `<abc/>` and `<abc>...</abc>` placeholders).

All translation content must be added to the translation files whose location is specified with the `loadPath` configuration which is passed to i18next.

See the `translations` function for integrating the library into an application. Create a translations module in the application and export the relevant things.

## Types

## Components

### `AlreadyTranslated`

This component represents content that has already been translated (such as pre-translated content from a backend). Its use in a component tree helps to distinguish content that has been addressed for translation with content that has not.

```tsx
import { AlreadyTranslated, AlreadyTranslatedText } from '@execonline-inc/translations';

const text: AlreadyTranslatedText = { kind: 'already-translated-text', text: 'content' };
const component = <AlreadyTranslated content={text} />;
```

### `L`

This component will localize a date/time according to a given format.

```ts
import { LocalizationFormat, Localizeable, translations } from '@execonline-inc/translations';
const { L } = translations<...>(...) // see `translations` documentation

const localizeable: Localizeable = new Date();
const format: LocalizationFormat = 'long-date-and-time';

const component = <L localizeable={localizeable} format={format} />;
```

### `T`

This component performs all available translation features given a typed translation definition via its props.

```tsx
import { translations } from '@execonline-inc/translations';
const { T } = translations<...>(...) // see `translations` documentation

const component = <T kind="something to translate" />;
```

### `NotTranslated`

Some content is not suitable for translation. Some examples of this are:

- proper names (though there may be cases where they can be represented in the target language)
- email addresses
- URLs

Rendering this type of content directly in component trees may be confused with content that hasn't been addressed for translation yet, so wrapping it in this component makes it clear that it has been considered for translation.

```tsx
import { NotTranslated } from '@execonline-inc/translations';

const text: string = 'not translatable';
const component = <NotTranslated text={text} />;
```

### `TranslationsContext`

This component is an implementation of a [React Context](https://reactjs.org/docs/context.html) whose data is a `TranslationsState`.

```tsx
import { TranslationsContext, TranslationsState } from '@execonline-inc/translations';

const state: TranslationsState = { kind: 'uninitialized' };
const consumer = (ts: TranslationsState): React.ReactNode => <>{ts.kind}</>;

const Example: React.FC = () => (
  <TranslationsContext.Provider value={state}>
    <TranslationsContext.Consumer>{consumer}</TranslationsContext.Consumer>
  </TranslationsContext.Provider>
);
```

### `TranslationsLoader`

This component loads the the translations when it is mounted and wraps its children in a `TranslationsContext.Provider`. It renders the component passed as the `loading` prop until the translations are loaded to prevent the normal child components from rendering without content (because it's awaiting translation) and eventually appearing suddenly.

```tsx
import { translations, TranslationsLoader } from '@execonline-inc/translations';
const { loader } = translations<...>(...) // see `translations` documentation

const component = <TranslationsLoader loader={loader} loading={<></>} />;
```

## Functions

### `alreadyTranslatedText`

This decoder decodes to an `AlreadyTranslatedText` object from a string.

```ts
import { alreadyTranslatedText, AlreadyTranslatedText } from '@execonline-inc/translations';

const decoder: Decoder<AlreadyTranslatedText> = alreadyTranslatedText;
const result: Result<string, AlreadyTranslatedText> = decoder.decodeAny('content');
```

### `defaultSettings`

These are default settings for `i18next` based on ExecOnline's use of the library.

### `initTask`

This function will return a `Task` to initialize `i18next`. It provides the opportunity for `i18next` to be configured as necessary by the user of this library.

```tsx
import { initTask, TranslationsLoader } from '@execonline-inc/translations';
import i18next from 'i18next';
import LanguageDetector from 'i18next-browser-languagedetector';
import HttpApi from 'i18next-http-backend';

const i18nextSettings = {
  /* ... */
};

const i18nextWithModules = i18next.use(HttpApi).use(LanguageDetector);

const loader = initTask(i18nextWithModules, i18nextSettings);

<TranslationsLoader loader={loader} loading={<></>} />;
```

### `localization`

This function will localize a date/time for a given language and according to a given format.

```ts
import { localization, LocalizationFormat, Localizeable } from '@execonline-inc/translations';

const localizeable: Localizeable = new Date();
const format: LocalizationFormat = 'long-date-and-time';
const language = 'en-US';

const result = localization(localizeable, format, language);
```

### `localizer`

This curried function will localize a date/time according to a given format under certain translation mapping load states.

When the state is `loaded` or `loaded-from-fallback`, localization occurs via a call to `localization`.

When the state is `uninitialized`, the localizeable argument is converted to a string.

```ts
import {
  localizer,
  LocalizationFormat,
  Localizeable,
  TranslationsState,
} from '@execonline-inc/translations';

const localizeable: Localizeable = new Date();
const format: LocalizationFormat = 'long-date-and-time';
const state: TranslationsState = { kind: 'uninitialized' };

const result: string = localizer(localizeable, format)(state);
```

### `translation`

This curried function performs the lookup in the translation mapping file and simple interpolation when appropriate based on the text to be translated and the state of the mapping.

When the state is `loaded` or `loaded-from-fallback`, the mapped translation text is returned. If the text is found to be "not translatable", then it is returned without translation.

When the state is `uninitialized`, an empty string is returned.

```ts
import { translations, TranslationsState } from '@execonline-inc/translations';
const { translation } = translations<...>(...) // see `translations` documentation

const state: TranslationsState = { kind: 'uninitialized' };
const result: string = translation('something to translate', {})(state);
```

### `translator`

This curried function performs all available translation features given a typed translation definition and the mapping load state.

```ts
import { translations, TranslationsState } from '@execonline-inc/translations';
const { translator } = translations<...>(...) // see `translations` documentation

const state: TranslationsState = { kind: 'uninitialized' };
const result: React.ReactNode = translator({ kind: 'something to translate' })(state);
```

### `translations`

This function returns an object of functions and components that are typed according to the translation types provided to the `translations` function.

```ts
import {
  Config,
  translations,
  interpolator,
  Interpolator,
  parameterized,
  Parameterized,
  ParameterizedFn,
  scalar,
} from '@execonline-inc/translations';
import i18next, * as i18n from 'i18next';
import LanguageDetector from 'i18next-browser-languagedetector';

const loader = initTask(i18next.use(LanguageDetector), {
  ...defaultSettings,
  backend: {
    loadPath: 'public/locales/{{lng}}/{{ns}}.json',
  },
});

const translatablePlainTextKeys = ['something to translate', 'something else'] as const;
const notTranslatable = ['email@example.com', 'https://example.com/'] as const;

type TranslatablePlainTextKey = typeof translatablePlainTextKeys[number];
type NotTranslatable = typeof notTranslatable[number];
type ParameterizedProps =
  | { kind: '{{count}} minutes'; count: number }
  | { kind: '<bolded>So</bolded> cool!'; bolded: Interpolator };

type PlainTextKey = TranslatablePlainTextKey | NotTranslatable;
type ParameterizedKey = ParameterizedProps['kind'];

const parameterizedValues: ParameterizedFn<ParameterizedKey, ParameterizedProps> = (
  props: ParameterizedProps
): Parameterized<ParameterizedKey, ParameterizedProps> => {
  switch (props.kind) {
    case '{{count}} minutes':
      return parameterized(props, { count: scalar(props.count) });
    case '<bolded>So</bolded> cool!':
      return parameterized(props, { bolded: interpolator(props.bolded) });
  }
};

const { L, translation, translator, T } = translations<
  PlainTextKey,
  NotTranslatable,
  ParameterizedKey,
  ParameterizedProps
>(translatablePlainTextKeys, notTranslatable, parameterizedValues);
```


# `url`

The `url` package provides functions to validate URLs.

## Types

### `InvalidUrlError`

```ts
interface InvalidUrlError {
  kind: 'invalid-url-error';
  href: string;
  base?: string | URL;
  error: unknown;
}
```

## Functions

### `invalidUrlError`

This function constructs an `InvalidUrlError` object from the given parameters.

```ts
import { invalidUrlError, InvalidUrlError } from '@execonline-inc/url';

const error: unknown = {};
const href: string = 'href';
const base: string = 'base';
const result: InvalidUrlError = invalidUrlError(error, href, base);
```

### `toUrlR`

This function attempts construction of a `URL` object and returns a `Result`. Handles a related [bug in Safari](https://github.com/zloirock/core-js/issues/656).

```ts
import { InvalidUrlError, toUrlR } from '@execonline-inc/url';
import { Result } from 'resulty';

const result: Result<InvalidUrlError, URL> = toUrlR('href', 'base');
```

### `toUrl`

This function attempts construction of a `URL` object (via `toUrlR`) and returns a `Maybe`.

```ts
import { InvalidUrlError, toUrl } from '@execonline-inc/url';
import { Maybe } from 'maybeasy';

const result: Maybe<InvalidUrlError> = toUrl('href', 'base');
```

### `toUrlT`

This function attempts construction of a `URL` object (via `toUrlR`) as a `Task`.

```ts
import { InvalidUrlError, toUrlT } from '@execonline-inc/url';
import { Task } from 'taskarian';

const result: Task<InvalidUrlError, URL> = toUrlT('href', 'base');
```


# web-url

`web-url` provides services for validating and constructing URLs.

It is a wrapper around the [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL)
and [URLSearchParams](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) API.

## Types

### `InvalidWebUrlError`

```ts
interface InvalidWebUrlError {
  kind: 'invalid-web-url-error';
  error: unknown;
}
```

## Functions

### `invalidWebUrlError`

This function constructs an `InvalidWebUrlError` object from the given parameters.

```ts
import { InvalidWebUrlError } from '@execonline-inc/web-url';

const error: unknown = {};
const result: InvalidWebUrlError = invalidWebUrlError(error);
```

### `href`

This function returns the `href` of the `URL` object.

```ts
import { href, toUrl } from '@execonline-inc/web-url';
toUrl("https://example.com").map(href) // Just("https://example.com")
```

### `toUrlR`

This function attempts construction of a `URL` object and returns a `Result`. Handles a related [bug in Safari](https://github.com/zloirock/core-js/issues/656).

```ts
import { InvalidWebUrlError, toUrlR } from '@execonline-inc/web-url';
import { Result } from 'resulty';

toUrlR('foo', 'http://example.com').map((url: URL) => url.href) // Ok("http://example.com/foo")

const result: Result<InvalidWebUrlError, URL> = toUrlR('href', 'base');
```

### `toUrl`

This function attempts construction of a `URL` object (via `toUrlR`) and returns a `Maybe`.

```ts
import { InvalidWebUrlError, toUrl } from '@execonline-inc/web-url';
import { Maybe } from 'maybeasy';

toUrl('foo', 'http://example.com').map((url: URL) => url.href) // Just("http://example.com/foo")
```

### `toUrlT`

This function attempts construction of a `URL` object (via `toUrlR`) as a `Task`.

```ts
import { InvalidWebUrlError, toUrlT } from '@execonline-inc/web-url';
import Task from 'taskarian';

toUrlT('foo', 'http://example.com').fork(
  (error: InvalidWebUrlError) => console.error(error),
  (url: URL) => console.log(url.href) // $> "http://example.com/foo"
);
```

### `getQueryParam`

This function returns the first value of the query parameter with the given name.

```ts
import { getQueryParam, toUrl } from '@execonline-inc/web-url';
toUrl("https://example.com?foo=bar&foo=baz").andThen(getQueryParam("foo")) // Just("bar")
```

### `getQueryParamArray`

This function returns all values in a query parameter with the given name.

```ts
import { getQueryParamArray, toUrl } from '@execonline-inc/web-url';
toUrl("https://example.com?foo=bar&foo=baz").map(getQueryParamArray("foo")) // Just(["bar", "baz"])
```

### `getQueryParamRailsArray`

This function returns all values in a query parameter with the given name, Rails-style.

```ts
import { getQueryParamRailsArray, toUrl } from '@execonline-inc/web-url';
toUrl("https://example.com?foo[]=bar&foo[]=baz").map(getQueryParamRailsArray("foo")) // Just(["bar", "baz"])
```


### `putQueryParam`

This function adds a query parameter with the given name and value to the URL.

```ts
import { putQueryParam, toUrl, href } from '@execonline-inc/web-url';
toUrl("https://example.com").map(putQueryParam("foo", "bar")).map(href) // Just("https://example.com?foo=bar")
```

### `putQueryParamArray`

This function adds a query parameter with the given name and values to the URL.

```ts
import { putQueryParamArray, toUrl, href } from '@execonline-inc/web-url';
toUrl("https://example.com").map(putQueryParamArray("foo", ["bar", "baz"])).map(href) // Just("https://example.com?foo=bar&foo=baz")
```

### `putQueryParamRailsArray`

This function adds a query parameter with the given name and values to the URL, Rails-style.

```ts
import { putQueryParamRailsArray, toUrl, href } from '@execonline-inc/web-url';
toUrl("https://example.com").map(putQueryParamRailsArray("foo", ["bar", "baz"])).map(href) // Just("https://example.com?foo[]=bar&foo[]=baz")
```

### `getPathname`

This function returns the pathname of the URL.

```ts
import { getPathname, toUrl, href } from '@execonline-inc/web-url';
toUrl("https://example.com/foo/bar").map(getPathname).map(href) // Just("/foo/bar")
```

### `setrPathname`

This function sets the pathname of the URL.

```ts
import { setPathname, toUrl, href } from '@execonline-inc/web-url';
toUrl("https://example.com").map(setPathname("/foo/bar")).map(href) // Just("https://example.com/foo/bar")
```

### `windowLocation`

This function returns the `URL` object for the current window as a `Task`.

```ts
import { windowLocation } from '@execonline-inc/web-url';

windowLocation().fork(
  (error: InvalidWebUrlError) => console.error(error),
  (url: URL) => console.log(url.href) // $> "https://example.com/foo/bar"
);
```


# Cute

[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg?style=plastic)](https://github.com/semantic-release/semantic-release)

Implementations of immutable Stacks and Deques for various use cases.

Compatible with Maybeasy and CooperTS.

## Install

```
> npm install --save @kofno/cute

> yarn add @kofno/cute
```


# Gaia

[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg?style=plastic)](https://github.com/semantic-release/semantic-release)

Read variables from the environment in a typesafe way.

Compatible with Maybeasy, Resulty, and Taskarian


# Piper

Functional composition in Typescript. This library is named after @kofno's cat. She is glorious.

# install

> npm install --save @kofno/piper

> yarn add @kofno/piper

## functions

### `pipe`

pipe takes in a sequence of functions which process an input parameter and return a output which
will be used as the input for the next function in the sequence. _pipe_ is copied almost
line-for-line from
[RxJS](https://github.com/ReactiveX/rxjs/blob/f8a9d6e52f6ab151d08da0e7424f64f70763c830/src/internal/util/pipe.ts).


```ts
    import { pipe } from '@kofno/piper';

    const add1 = n => n + 1;
    const double = n => n * 2;

    const doubleThenAdd1 = pipe(
      double,
      add1
    );

    doubleThenAdd1(2); // 5
```

### `pipeline`

pipeline wraps unary functions with a functor implementation so that functions can be composed using map.

```ts
      import { pipeline } from './index';

      const upper = (s: string) => s.toUpperCase();
      const split = (sep: string) => (s: string) => s.split(sep);
      const reverse = (ss: string[]) => ss.reverse();
      const join = (ss: string[]) => ss.join('');

      const doit = pipeline(upper)
        .map(split(''))
        .map(reverse)
        .map(join).fn;

      doit('food') // 'DOOF'
```

### `pick`

pick creates a function that pulls a particular value from an object which is useful for accessing objects in a functor chain.

```ts
    import { pick } from '@kofno/piper';

    const f = {
      a: 2,
      b: 'two',
      c: true,
    };

    pick('a', f) // 2
```


# Stack

[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg?style=plastic)](https://github.com/semantic-release/semantic-release)

An implementation of an immutable Stack data structure.

Compatible with Maybeasy.

## Install

```
> npm install --save @kofno/stack-ts

> yarn add @kofno/stack-ts
```


# ajaxian

[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg?style=flat-square)](https://github.com/semantic-release/semantic-release)

Ajaxian is a small wrapper around the XMLHttpRequest object. It borrows heavily
from the Elm Http module. In many ways it's not all that different from other
http libraries: build a request, send it to the server, and then handle the
response. The emphasis here is on handling error responses correctly and
consistently, without resorting to thrown exceptions.

Because it uses XMLHttpRequest, Ajaxian can only be used from the browser (or
a browser-like environment, like Electron). Browserify, Webpack, or some similar
tool may be required when packaging for deploy.

## tasks

Instead of Promises, Ajaxian uses Futures (here called Tasks, from the
Taskarian library). Tasks are lazy and will not execute until forked. This
means a Task can be returned from a pure function. Tasks are also composable.
You can build a complex chain of behaviors, while strictly controlling exactly
when the side effects happen. In this way I prefer them over Promises, which
are stateful and initiate side effects as soon as they are instantiated.

## errors

Ajaxian does not throw errors for failed requests. Instead, failed requests
are returned as one of several different types of errors. Error conditions
are documented this way because I believe that you create a better user
experience when you handle error conditions gracefully. I want to provide
the tools for doing that.

All of the error types are documented in the HttpError module.

## decoders

Decoders are another idea stolen from Elm. A decoder is a function that converts
the response body of a request into a data structure that can be used by the
application.

Ajaxian expects the decoder to return the results wrapped in a Result object.
If the data passes muster, then the decoder should return the data wrapped in
an Ok object. If the data is incorrect, then an error message wrapped will be
wrapped in an Err object. This will result in a BadPayload error.

If you are building a json heavy application, I would recommend checking out
[jsonous](https://github.com/kofno/festive-possum/tree/main/packages/jsonous). 
This library is specifically built for creating composable decoders for handling
json content.

# installing

> npm install --save ajaxian

> yarn add ajaxian

# usage

    import { toHttpTask, Request, header } from 'ajaxian';
    import { ok } from 'resulty';

    // Create a request object. This is a TS example.
    const request: Request<{}> = {
      url: '/some_end_point',
      method: 'post',
      data: { foo: 'bar' },
      timeout: 0,
      headers: [header('X-Some-Header', 'baz')],
      withCredentials: true,
      decoder: () => ok({}),
    };

    toHttpTask(request).fork(
      err => console.error(err),
      data => console.log("Success!", data)
    );

There are some convenience builders for making requests, too:

    import { post } from 'ajaxian';

    const request = post('/some_end_point', { foo: bar }, () => ok({}))
      .withHeader(header('X-Some-Header', 'baz'));

It is also possible to abort an HTTP request before it completes. Forking the
HTTP task returns an abort function from the underlying HTTP request object:

    const cancel = toHttpTask(request).fork(
      err => console.error(err),
      data => console.log("Success!", data),
    );

    cancel() // <-- aborts request


# ajaxios

[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg?style=flat-square)](https://github.com/semantic-release/semantic-release)

Ajaxios is a fork of Ajaxian. The key differenence is that, where Ajaxian wraps
XMLHttpRequest and only works in browsers, Ajaxios wraps the Axios library so
that it can work in browsers or Node. This means that the Ajaxios is suitable
for use in server side rendering or in a Node server or Lambda.

[More about the Axios library](https://www.npmjs.com/package/axios).

Ajaxios is NOT a drop-in replacement for Ajaxian. They are very similar APIs,
but some concessions have been made to how Axios works differently then the
XMLHttpRequest.

Ajaxios borrows heavily from the Elm Http module. In many ways it's not all
that different from other http libraries: build a request, send it to the
server, and then handle the response. The emphasis here is on handling error
responses correctly and consistently, without resorting to thrown exceptions.

## tasks

Instead of Promises, Ajaxios uses Futures (here called Tasks, from the
Taskarian library). Tasks are lazy and will not execute until forked. This
means a Task can be returned from a pure function. Tasks are also composeable.
You can build a complex chain of behaviors, while strictly controlling exactly
when the side effects happen. In this way I prefer them over Promises, which
are stateful and initiate side effects as soon as they are instantiated.

## errors

Ajaxios does not throw errors for failed requests. Instead, failed requests
are returned as one of several different types of errors. Error conditions
are documented this way because I believe that you create a better user
experience when you handle error conditions gracefully. I want to provide
the tools for doing that.

All of the error types are documented in the HttpError module.

## decoders

Decoders are another idea stolen from Elm. A decoder is a monad that converts
the response body of a request into a data structure that can be used by the
application.

Ajaxios uses Jsonous (as a peer dependency) to describe decoders.

If the data passes muster, then the decoder returns the data wrapped in
an Ok object. If the data is incorrect, then an error message will be
wrapped in an Err object and Ajaxios will return the result as a BadPayload
error.

# installing

> npm install --save ajaxios

> yarn add ajaxios

# usage

    import { toHttpTask, Request, header } from 'ajaxios';
    import { succeed } from 'jsonous';

    // Create a request object. This is a TS example.
    const request: Request<{}> = {
      url: '/some_end_point',
      method: 'post',
      data: { foo: 'bar' },
      timeout: 0,
      headers: [header('X-Some-Header', 'baz')],
      withCredentials: true,
      decoder: succeed({}),
    };

    toHttpTask(request).fork(
      err => console.error(err),
      data => console.log("Success!", data)
    );

There are some convenience builders for making requests, too:

    import { post } from 'ajaxios';

    const request = post('/some_end_point', { foo: bar }, succeed({}))
      .withHeader(header('X-Some-Header', 'baz'));

It is also possible to abort an HTTP request before it completes. Forking the
HTTP task returns an abort function from the underlying HTTP request object:

    const cancel = toHttpTask(request).fork(
      err => console.error(err),
      data => console.log("Success!", data),
    );

    cancel() // <-- aborts request


# jsonous

[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)

If you're building a web application, you're eventually going to need a reliable
way to convert JSON into type that you can use. `JSON.parse` will only get you
so far.

A better solution allows you to verify the structure of the source data while
converting it into the types you need to work with. It handles variations in
content structure. In a typed environment, it preserves your types so you don't
have to pass `any` types around. Errors are handled gracefully using a Result
type.

This library, heavily inspired by Elm's [JSON Decoder](http://package.elm-lang.org/packages/elm-lang/core/latest/Json-Decode), is just
such a solution.

# install

> npm install --save jsonous

> yarn add jsonous

# usage

## primitives

There are several decoders for handling JSON primitives; strings, numbers,
booleans, and arrays (more on objects later)

```typescript
string.decodeJson('"foo"'); // --> Ok("foo")
string.decodeJson('42'); // --> Err("42 is not a string")

number.decodeJson('42'); // --> Ok(42)
number.decodeJson('"foo"'); // --> Err("foo is not a number")

boolean.decodeJson('true'); // --> Ok(true)
boolean.decodeJson('"foo"'); // --> Err("foo is not a boolean")
```

## arrays

The array primitive applies another decoder to an array of values.

```typescript
array(string).decodeJson('["foo", "bar"]'); // --> Ok(["foo", "bar"])
array(string).decodeJson('["foo", 42]'); // --> Err("42 is not a string")
```

## objects

The `field` and `at` decoders are used to extract values from objects.

```typescript
field('bar', string).decodeAny({ bar: 'baz' }); // --> Ok('baz')
at(['foo', 0, 'bar'], number).decodeAny({ foo: [{ bar: 42 }] }); // --> Ok(42)
```

Object decoders can be chained together to build more complex data structures.

```typescript
// prettier-ignore
field('userId', number).andThen(id =>
field('emailAddress', string).andThen(email =>
succeed({ id, email })))
.decodeAny({ userId: 213, emailAddress: 'foo@example.com' })
// --> Ok({ id: 213, email: 'foo@example.com'})
```

Of course, your code editor may try to reformat this code.

```typescript
field('userId', number)
  .andThen((id) =>
    field('emailAddress', string).andThen((email) => succeed({ id, email }))
  )
  .decodeAny({ userId: 213, emailAddress: 'foo@example.com' });
// --> Ok({ id: 213, email: 'foo@example.com'})
```

For an object of any moderate complexity, this nesting is indistinguishable from
callback hell.

To combat this, decoders have a method named `assign`. It enacapsulates this
pattern of building objects such that objects can be built incrementally, without
nesting and without losing type safety.

The previous example would look like this using `assign`:

```typescript
succeed({})
  .assign('id', field('userId', number))
  .assign('email', field('emailAddress', string))
  .decodeAny({ userId: 213, emailAddress: 'foo@example.com' });
// --> Ok({ id: 213, email: 'foo@example.com' })
```

The best strategy for handling object construction with decoders
is to compose complex decoders from smaller, simpler decoders.

```typescript
succeed({})
  .assign('user', field('user', userDecoder))
  .assign('courses', at(['student', 'courses'], array(courseDecoder)))
  .decodeJson('... some json ... ')

const userDecoder = //...
const courseDecoder = //...
```

# docs

[API](https://kofno.github.io/jsonous)


# maybeasy

[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg?style=plastic)](https://github.com/semantic-release/semantic-release)

Whether we like it or not, not every computation in a program is going to
return a value. Sometimes there's no value to return. Other times, something
goes wrong and we're just not sure what value to return.

In JavaScript we often will return null or undefined to represent the value
of Nothing, however we arrive at that value. This can often lead to failures
at runtime when we forget (or are unaware) that a value may be nothing.
Strict null checking makes this situation tolerable in Typescript, if only by
nagging you every place you need to check for Nothing.

Arrays are less prone to these types of failures, because if when there is
nothing, we return an empty array. We can safely apply functions to an array
without being concerned if there are values present, because an empty array and
a populated array have the same interface. Can that same principle be applied
to singular values?

Sure it can! The Maybe type offers a way to express that a value may be something,
or it may be nothing. Our intuition for mapping over arrays is applicable here.

## the functor (this map)

Given a computation that may or may not return a value, we can apply logic to
this value by mapping pure functions over the result of the computation. For
example:

```typescript
const fetchSomething = (): Maybe<number> => ...; // <-- may or may not return something

const add2 = (n) => n + 2;

fetchSomething().map(add2); //
```

In this example, we add2 to the number that we fetched. But if the there is no
number -- it's Nothing -- the result of add2 is... Nothing. We won't get a
runtime error.

## chaining (the flat map)

Let's say that we have two computations. Both may return nothing, but one of the
computations depends on the other.

```typescript
const fetchSomething = (): Maybe<number> => ...;

const fetchSomethingElse = (n: number): Maybe<string> => ...; // <-- also may or may not return something
```

We _could_ use a map here, as in this examples:

```typescript
fetchSomething().map(fetchSomethingElse);
```

The problem with this is that we will end up a maybe nested inside another maybe.
You intuition for Arrays applies here, too; if we map over an Array with a function
that returns an Array, we end up with an Array of Arrays. That same thinking
applies here; we'll end up with `Maybe<Maybe<string>>`.

To chain computations that both may return nothing, we need a different tool:
`andThen`. We can rewrite our previous example, but just replace `map` with
`andThen`:

```typescript
fetchSomething().andThen(fetchSomethingElse);
```

If either computation is Nothing, the result is nothing. If both computations
succeed, then we have `Maybe<string>`.

## building an object

A common pattern in javascript is build an object from a set of computations.
When those computations may or may not return a value, it can be useful to
chain them together using Maybe.

Given our functions, you can chain them together using `andThen`. It looks like
this:

```typescript
fetchSomething().andThen(a => fetchSomethingElse.andThen(b => just({ a, b })));
```

If the object is fairly complex, this nesting can be quite deep.

```typescript
fetchSomething()
.andThen(a =>
  fetchSomethingElse().andThen(b =>
    fetchC().andThen(c =>
      fetchD().andThen(d =>
        fetchE().andThen(e =>
          ({ a, b, c, d, e })
        )
       )
      )
    );
```

This is barely distinguishable from callback hell. The `assign` method helps
flatten this out by allowing us to build an object incrementally. Here's the
last code example using `assign`:

```typescript
just({})
  .assign('a', fetchSomething())
  .assign('b', fetchSomethingElse())
  .assign('c', fetchC())
  .assign('d', fetchD())
  .assign('e', fetchE());
```

`assign` also accepts a function that returns a Maybe value as the second argument.
Use this when you need to calculate one value of the object, based on a previously
calculated value. For example:

```typescript
just({})
  .assign('a', just(8))
  .assign('b', scope => just(scope.a + 42)); // --> Just { a: 8, b: 50 }
```

## unwrapping the value

At some point, we may need to send our result to another part of the system.
The other part of the system may not understand Maybe values. Or possibly this
value needs to be serialized as a string for sending to a third party. We need
a safe way to _unwrap_ this value. For this purpose we have `getOrElse` and
`getOrElseValue`.

`getOrElse` and `getOrElseValue` will return the value if it is present (a Just),
but also requires us to provide a default value, in the case that we have Nothing.
`getOrElseValue` is strict and takes a value of the generic type of the Maybe.
`getOrElse` is lazy. It takes a function that returns a type of the generic
type of the Maybe. The function will only be evaluated if the Maybe is Nothing.
Prefer usinf `getOrElse` if the default value is expensive to calculate.

This makes _unwrapping_ the value safe.

## putting it all together

We can, of course, chain and map all we want to create a pipeline of data processors.
At the end we can unwrap our value for consumption by humans or other systems.
For example:

```typescript
fetchSomething()
  .map(add2)
  .andThen(fetchSomethingElse)
  .getOrElse('No data');
```

# install

> npm install --save maybeasy

> yarn add maybeasy

# usage

```typescript
import { just, nothing } from 'maybeasy';

function parse(s) {
  try {
    return just(JSON.parse(s));
  } catch (e) {
    return nothing();
  }
}
```

# docs

[API](https://kofno.github.io/maybeasy)


# NonEmpty List

An immutable data structure that acts like a list but guarantees that the list always has at least 
one item.

## Constructor

Because a `NonEmptyList<T>` guarantees the presence of at least one `T`, the constructor requires
a `T` object.

```typescript
const strings = new NonEmptyList('hello', ['world'])
const numbers = new NonEmptyList(1, [2, 3, 4])
```

## Other Construction Functions

### `fromValue`

Create a `NonEmptyList<T>` from a single `T`.

```typescript
const numbers = fromValue(1); // Equivalent to new NonEmptyList(1, [])
```

### `fromArray`

Create a `NonEmptyList<T>` from an `Array<T>`, returning a [`Result<string, NonEmptyList<T>>`]. If 
the array is empty return an error result, otherwise return a new non-empty list in an okay result.

Useful when the array is not known statically.

```typescript
const someArrayOfNumbers: Array<number> = calculateOrFetchTheArray();
const numbers: Result<string, NonEmptyList<number>> = fromArray(someArrayOfNumbers)
```

[`Result<string, NonEmptyList<T>>`]: https://github.com/kofno/festive-possum/tree/main/packages/resulty

### `fromArrayMaybe`

Similar to `fromArray`, but return a [`Maybe<NonEmptyList<T>>`]. Useful when the array is not known
statically.

```typescript
const someArrayOfNumbers: Array<number> = calculateOrFetchTheArray();
const numbers: Maybe<NonEmptyList<number>> = fromArrayMaybe(someArrayOfNumbers)
```

[`Maybe<NonEmptyList<T>>`]: https://github.com/kofno/festive-possum/tree/main/packages/maybeasy

## Attributes

### `first`

The first element in the list, guaranteed to exist.

```typescript
const numbers = new NonEmptyList(1, [2, 3, 4])
numbers.first // 1
```

### `rest`

An array of the rest of the elements in the list. May be empty.

```typescript
const numbers = new NonEmptyList(1, [2, 3, 4])
numbers.rest // [2, 3, 4]

const strings = new NonEmptyList('hello world', [])
strings.rest // []
```

### `length`

The number of elements in the list.

```typescript
const numbers = new NonEmptyList(1, [2, 3, 4])
numbers.length // 4
```

## Methods

### `reverse`

Returns a new `NonEmptyList` with the items reversed.

```typescript
const numbers = new NonEmptyList(1, [2, 3, 4])
const reversed = numbers.reverse()
numbers.first // 1
reversed.first // 4
```

### `includes`

Indicate whether the list includes some value.

```typescript
const numbers = new NonEmptyList(1, [2, 3, 4])
numbers.includes(2) // true
numbers.includes(8) // false
```

### `take`

Return an array of the first `count` elements.

```typescript
const numbers = new NonEmptyList(1, [2, 3, 4])
numbers.take(2) // [1, 2]
```

### `drop`

Return an array after dropping the first `count` elements.

```typescript
const numbers = new NonEmptyList(1, [2, 3, 4])
numbers.drop(2) // [3, 4]
```

### `concat`

Takes either an `Array` or another `NonEmptyList`, and returns a new `NonEmptyList` with the current
and given lists concatenated.


```typescript
const firstTwo = new NonEmptyList(1, [2])
const numbers = firstTwo.concat([3, 4])
numbers.first // 1
numbers.rest // [2, 3, 4]
```

### `every`

Similar to [`Array.prototype.every()`]: for some predicate, does every element in the list return
`true`?

```typescript
const numbers = new NonEmptyList(1, [2, 3, 4])
numbers.every(n => n < 5) // true
numbers.every(n => n < 4) // false
```

[`Array.prototype.every()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/every

### `some`

Similar to [`Array.prototype.some()`]: for some predicate, does some element in the list return 
`true`?

```typescript
const numbers = new NonEmptyList(1, [2, 3, 4])
numbers.some(n => n < 4) // true
numbers.some(n => n > 4) // false
```

[`Array.prototype.some()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/some

### `find`

Attempt to find an element where the given predicate returns `true`. Return [`Maybe<T>`].

```typescript
const numbers = new NonEmptyList(1, [2, 3, 4])
numbers.find(n => n < 4) // just(1)
numbers.find(n => n > 4) // nothing()
```

[`Maybe<T>`]: https://github.com/kofno/festive-possum/tree/main/packages/maybeasy

### `map`

Similar to [`Array.prototype.map()`]: create a new `NonEmptyList` by evaluating the callback for
every item in the current list.

```typescript
const numbers = new NonEmptyList(1, [2, 3, 4])
const mapped = numbers.map(n => n * 2).map(String)
mapped.first // "2"
mapped.rest // ["4", "6", "8"]
```

[`Array.prototype.map()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map

### `and`

Alias of [`map`](#map).

### `andThen`

Similar to [`Array.prototype.flatMap()`]. Given a callback that returns a new `NonEmptyList<U>` when
evaluated on an item `T`, return the result of mapping over the current list, and then flattening
all the new lists into a single `NonEmptyList<U>`.

```typescript
const numbers = new NonEmptyList(1, [2, 3, 4])
const createPair = (n: number) => new NonEmptyList(n, [n])
const pairs = numbers.andThen(createPair)
pairs.first // 1
pairs.rest // [1, 2, 2, 3, 3, 4, 4]
```

[`Array.prototype.flatMap()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/flatMap

### `reduce`

Similar to [`Array.prototype.reduce()`]: "reduce" the array of values into a single value.

```typescript
const numbers = new NonEmptyList(1, [2, 3, 4])
numbers.reduce((sum, n) => sum + n) // 10
```

[`Array.prototype.reduce()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reduce

### `filter`

Similar to [`Array.prototype.filter()`]: return an `Array` of values for which some predicate
returns `true`.

```typescript
const numbers = new NonEmptyList(1, [2, 3, 4])
numbers.filter(n => n % 2 === 0) // [2, 4]
```

[`Array.prototype.filter()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter

### `sort`

Returns a new `NonEmptyList` with the items sorted using [`Array.prototype.sort()`].

```typescript
const scrambled = new NonEmptyList(3, [1, 4, 2])
const sorted = numbers.sort()
scrambled.first // 3
sorted.first // 1
```

[`Array.prototype.sort()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort

### `join`

Equivalent to [`Array.prototype.join()`].

```typescript
const numbers = new NonEmptyList(1, [2, 3, 4])
numbers.join(', ') // "1, 2, 3, 4"
```

[`Array.prototype.join()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/join

### `toArray`

Return an `Array` of the elements in the list.

```typescript
const numbers = new NonEmptyList(1, [2, 3, 4])
numbers.toArray() // [1, 2, 3, 4]
```


# resulty

[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg?style=plastic)](https://github.com/semantic-release/semantic-release)


A disjunction implementation in TypeScript.

# install

> npm install --save resulty

> yarn add resulty

# usage

    import { ok, err } from 'resulty';

    function parse(s) {
      try {
        return ok(JSON.parse(s));
      }
      catch(e) {
        return err(e.message);
      }
    }

# docs

[API](https://kofno.github.io/resulty)


# taskarian

[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg?style=plastic)](https://github.com/semantic-release/semantic-release)

A Task (Future) implementation in TypeScript. Useful for managing asynchronous tasks
that may fail.

A Task is different then a Promise because it is lazy, rather then eager. A Promise
runs as soon as you instantiate it. A Task doesn't run until you call `fork`.
Pure functions can return tasks (just not execute them). This means that you
could, for example, return a task from a Redux reducer, if that's your thing.

# install

> npm install --save taskarian

> yarn add taskarian

# usage

    import Task from 'taskarian';

    function parse(s) {
      return new Task(function(reject, resolve) {
        try {
          resolve(JSON.parse(s));
        }
        catch(e) {
          reject(e.message);
        }
      });
    }

    parse('foo').fork(
      function(err) { console.error(err) },
      function(value) { console.log(value) }
    );

It is also possible to cancel a task, if the task supports it:

    import Task, { Resolve } from 'taskarian';

    const cancellable = new Task((reject, resolve: Resolve<string>) => {
      const x = setTimeout(() => resolve('Yo!'), 3000);
      return () => clearTimeout(x);
    });

    const cancel = task.fork(
      err => console.error(err),
      s => console.warn(`Task should never have finished; ${s}`),
    );

    cancel();

# docs

[API](https://kofno.github.io/taskarian)
