From 74d26dc6d9c3a8b062c8444bcf5400efff207bed Mon Sep 17 00:00:00 2001 From: "andy.patterson" Date: Thu, 12 Apr 2018 08:42:01 -0400 Subject: [PATCH] docs: add descriptions and examples to api --- README.md | 60 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 59 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 0a37848..0781871 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ function getUsername(): string | undefined { let normalizedUsername = 'username'; const username = getUsername(); -if (username === undefined) { +if (username !== undefined) { const firstName = username.split(' ')[0]; normalizedUsername = firstName.toLowerCase(); } @@ -37,6 +37,14 @@ if (username === undefined) { ## Api ### map +Map gives access to the contained value. +Imagine an array, `Array`, as a container for strings, the `map` function applies a function to each element if the container is not empty and gives back a new container. +For instance: +```typescript +const orig: Array = ['1', '2', '3']; +const now: Array = orig.map(x => parseInt(x)); +``` + ```typescript some('thing').map(v => console.log(v)) // prints "thing" @@ -44,6 +52,13 @@ if (username === undefined) { ``` ### flatMap +FlatMap also accesses the contained value, but it expects that its "mapper" function returns a container of the same type. +Imagine the conceptually equivalent array container: +```typescript +const orig: Array = [1, 3, 5]; +const now: Array = orig.flatMap(x => ( [x, x + 1] )); +console.log(now); // => [1, 2, 3, 4, 5, 6] +``` ```typescript const maybeAdd1 = (x: Maybe) => x.map(y => y + 1); @@ -53,6 +68,9 @@ const y = none().flatMap(maybeAdd1); // Maybe ``` ### or +Similar to the `or` logical operator. +Tries to get the value (true) of the first maybe; if it is empty (false), tries to get the value (true) of the second maybe. +If both are empty (false), returns an empty (false) maybe. ```typescript const first = none(); const second = some(22); @@ -61,6 +79,13 @@ const third = first.or(second); // Maybe<22> ``` ### orElse +Similar to `or`, except the second value is not allowed to be empty. +`orElse` _must_ return an instance of the contained value, even if the maybe is empty. +This is useful for supplying default values: +```typescript +const maybeName = maybe(getNameFromInput()); +const name = maybeName.orElse('enter name please'); +``` ```typescript const first = none(); const second = 'hi'; @@ -69,6 +94,20 @@ const third = first.orElse(second); // 'hi'; ``` ### expect +`expect` forcefully gets the value out of the `Maybe` container, or throws an error if there is no value. +This is useful whenever you _know_ the value must be defined at this point, and you want to get out of the `Maybe` chain. +For instance: +```typescript +function tryOption1(): Maybe { ... } +function tryOption2(): Maybe { ... } +function tryOption3(): Maybe { ... } // The string must be created by one of these 3, we just don't know which + +const str: string = + tryOption1() + .or(tryOption2) + .or(tryOption3) + .expect('We expected to get the from one of these three methods'); +``` ```typescript function getData(): Maybe { ... } const maybeData = getData(); @@ -79,6 +118,15 @@ const shouldHaveData = maybeData.expect("oops, guess I didn't"); ``` ### caseOf +`caseOf` is a pattern matcher for the `Maybe`. +This is useful when you want to execute different logic dependent on whether the container is empty. +For instance: +```typescript +maybeData.caseOf({ + none: () => attemptToGetFromApi().map(doThingWithData), + some: data => doThingWithData(data), +}); +``` ```typescript getData().caseOf({ some: value => value + 1, @@ -89,6 +137,16 @@ getData().caseOf({ ``` ### asNullable +`asNullable` provides an "out" for escaping the `Maybe` container. +This is particularly useful at the boundaries of your API. +Often the internals of a library use `Maybe` to clean up code, but would like their external contracts to not be forced to use `Maybe`s, but instead "vanilla" JS. +For instance: +```typescript +export function doThing(): string | undefined { + const maybeValue: Maybe = getFromSomewhereInLib(); + return maybeValue.asNullable(); +} +``` ```typescript const value = 'hi'; const nullable = maybe(value).asNullable();