About

CooperTS - Practical Patterns

Guide

Task Manager App

Cellular Automata Emulator

This Doc Site 😁

Examples

What's All This About Map Then?

Avoiding The Billion Dollar Mistake

When to Use Which - getOrElse vs getOrElseValue

Imperative vs Declarative Programming

When To Use Which - map vs. andThen

When To Use Which - Maybe vs Result vs Task (and other Monads)

Frequently Asked Questions

ajaxian

ajaxios

@kofno/cute

@kofno/gaia

jsonous

maybeasy

nonempty-list

@kofno/piper

resulty

@kofno/stack-ts

taskarian

@execonline-inc/appy

@execonline-inc/collections

@execonline-inc/decoders

@execonline-inc/dom

@execonline-inc/environment

@execonline-inc/error-handling

@execonline-inc/logging

@execonline-inc/maybe-adapter

@execonline-inc/numbers

@execonline-inc/resource

@execonline-inc/strings

@execonline-inc/time

@execonline-inc/time-distance

@execonline-inc/translations

@execonline-inc/url

@execonline-inc/web-url

Packages

## Caveats and Disclaimers

I make no guarantees that the code examples compile or execute. All code examples are syntactically similar to Typescript, but should be treated as pseudo-code. Also, I expect to reference behaviors (methods, etc) that actually don't exist in the JavaScript standard library (though it'd be nice if some of them did). I try to call out where I'm doing this, but really who knows if I got every case. The intent of this is not because I'm lazy (well, not exclusively because I'm lazy), but because I want to emphasize the concepts, and not muddy the waters of learning with the intricacies of the JavaScript implementation reality.

With that out of the way, on to the topic at hand...

## But First... (a Pure Function Primer)

Before we tackle Map and AndThen, we should make sure that we are all on the same page about functions.

In the mathematical sense, a function is just a mapping from a Set of inputs to a Set of outputs. The output for any given input will always be the same. In the programming world, we call these functions "pure" functions. and they are becoming quite popular.

Pure functions are defined by having no side effects and always returning the same value for the same arguments.This idea is often called "referential integrity", which simply means that if you replace your function call with the value returned from the function, your program doesn't break.

Let's take a moment to explore referential integrity. Given this function:

### add2

```typescript
const add2 = (n: number) => n + 2;
```

Then this program:

### referential program 1

```typescript
add2(2) === 4;
```

is identical to this program:

### referential program 2

```typescript
4 === 4;
```

So.. that was probably a tad underwhelming.

Now let's consider a slightly different version of add2.

### side effectual add2

```typescript
const add2 = (n: number) => {
 sendEngagement(`Someone added 2 to ${n}`);
 return n + 2;
};
```

Now when I replace add2(2) === 4 with 4 === 4, how many Product Managers am I going to have in my inbox in the morning because the add2 engagements are broken? Imagine trying to write tests for both versions of add2. Which one is easier?

The problem with the second version of add2 is that has side effects in addition to the computation we were expecting. Side effects could include mutating inputs, modifying global variables, I/O operations (reading writing to disk, http requests, reading environment variables, etc.). You can't have a meaningful program without side-effects, but a key tenant of CooperTS is that we want to separate our side effects from our business logic. This makes the business logic easier to write and understand, while isolating parts of the code that are going to fail at runtime.

So why did we go through all this just to talk about Map and AndThen? Well, the laws that govern how Map and AndThen work assume that the functions that are passed in are pure. Applying side effectual behaviors using Map and AndThen are generally discouraged as they subvert optimizations and logic that the mapping behavior is applying in the implementation. Map, after, all isn't just a stylistic preference for looping.

With all that out of the way, let's look at Map and AndThen as applied to Arrays.

## The Array

So let's look at a map in the familiar context of an Array.

Before we begin, let's define some types to work with:

### Types.ts

```typescript
interface Encoding {
 id: string;
 name: string;
}

interface Stream {
 id: string;
 codec: string;
}

interface Video {
 encoding: Encoding;
 streams: Stream[]
}

const videos: Video[] = // ... assume we initialized this array with videos
```

Now lets write a couple loops. One that gets all of the encoding ids from the list of videos, and another that gets all the stream ids from the list of videos:

### Get you some encoding ids

```typescript
const encodingIds: string[] = [];

for (let i = 0; i < videos.length; i++) {
 const id = videos[i].encoding.id;
 encodingIds.push(id);
}

const streamIds: string[] = [];

for (let i = 0; i < videos.length; i++) {
 const streams = videos[i].streams;

 for (let j = 0; j < streams.length; j++) {
 const id = streams[j].id;
 streamIds.push(id);
 }
}
```

If you read this code honestly, you have to admit that it's mostly loop management and state initialization; low level concepts that muddy up our business concerns.

Now let's extract the "business logic" into some functions:

### Functions.ts

```typescript
const getId = <T extends { id: string }>(thing: T): string => thing.id;

const getStreams = (video: Video): Stream[] => video.streams;

const getEncoding = (video: Video): Encoding => video.encoding;
```

And we'll try again:

### Loops redeux

```typescript
const encodingIds: string[] = [];

for (let i = 0; i < videos.length; i++) {
 const id = getId(getEncoding(videos[i]));
 encodingIds.push(id);
}

const streamIds: string[] = [];

for (let i = 0; i < videos.length; i++) {
 const streams = getStreams(videos[i]);

 for (let j = 0; j < streams.length; j++) {
 const id = getId(streams[j]);
 streamIds.push(id);
 }
}
```

Is this better? Well, each piece of business logic is much easier to test now. But we're still doing loop maintenance and state management, and depending on how you feel about reading functions vs. dot notation, this might be harder for you to read.

Let's look again at the encoding ids example, this time using map:

### Encoding IDs, Mapped edition

```typescript
const encodingIds: string[] = videos.map(getEncoding).map(getId);
```

And that's all she wrote. Loop maintenance is gone. State management is gone. All that's left are the declarations of what the logic is doing.

"So tell me...", you may be thinking. "How does map work?"

Let us now take a look at a hypothetical implementation of map in a hypothetical Array class:

### Map's Guts

```typescript
class Array<A> {
 //... a bunch of stuff that makes arrays arrays
 map = (fn: (a: A) => B): Array => {
 const newArray: B[] = [];

 for (let i = 0; i < this.length; i++) {
 const b = fn(this[i]);
 newArray.push(b);
 }

 return newArray;
 };
}
```

So that's where all the loop maintenance and state management went!? Indeed. This is the power of map: It abstracts away low level considerations, and surfaces only the business concerns.

Now I want to take a look at the signature of the fn argument in map and compare it to our business logic functions:

### Map Signature

```typescript
fn: (a: A) => B

getId: (thing: T): string

getStreams: (video: Video): Stream[]

getEncoding: (video: Video): Encoding
```

Every single one of our business logic functions is compatible with map. And this will be true of any pure function. As long as it takes a single argument (or can be curried down to take a single argument) then that function can be used with map. And we can see in the array example that map frees up a lot of mental bandwidth, freeing up cycles that were once devoted to tracking loop and state details but can now be applied to solving actual application space problems.

This idea of map abstracting away low level details is powerful. In the array, it hides looping and state mutation. But imagine if all of your ugly, side effectual, state management details could be modeled as mappable data structures. In that world, all of your business logic could be written in easily tested, easily reasoned about, type checkable, pure functions. No mocks. No browser. No environment considerations. WOW!

Of course, when everything seems rosy, there's always something that comes along and throws a wrench in the works. Let's see what happens when we apply map the stream ids case:

### map stream ids

```typescript
const streamIds: string[] = videos.map(getStreams).map((streams) => streams.map(getId));
```

Ugh... getStreams is breaking my beautiful code. Since it returns an array, I have to nest a map inside another map; abstraction details are leaking out. Also, this won't compile because I've declared that I need a string[], but I'm actually getting a string[][]. Ay caramba!

We could fix the compiler error with something intensely JavaScripty, like this:

### Intense JavaScript

```typescript
const tempStreamIds: string[][] = videos.map(getStreams).map((streams) => streams.map(getId));

const streamIds: string[] = [].concat.apply([], tempStreamIds);
```

It should compile now, but so help me... I need to know how JavaScript functions can be applied; the lowest of low level details. Calgon, take me away.

What would be great here, is if we had a function like map, but instead of appending the results of the map function (fn), it concatenated them. What would we call such a function? How about concatMap? Let's look at a hypothetical implementation of concatMap:

### concatMap

```typescript
class Array<A> {
 //... a bunch of stuff that makes arrays arrays
 concatMap = (fn: (a: A) => B[]): Array => {
 let newArray: B[] = [];

 for (let i = 0; i < this.length; i++) {
 const bs = fn(this[i]);
 newArray = newArray.concat(bs);
 }

 return newArray;
 };
}
```

Heavens to Betsy, that looks a lot like map, doesn't it? The differences are that the fn function argument must return an array, and those arrays are being concatenated, rather then appended.

Well, now that we have concatMap, let's go back and fix our streamIds:

### fixed stream ids

```typescript
const streamIds: string[] = videos.concatMap(getStreams).map(getId);
```

Phew... that is so much nicer.

In this section we've seen that map and it's close sibling concatMap are incredibly handy abstractions to have around. They de-emphasize low level details allowing us to re-emphasize business logic. In many cases, that leads to purely functional application logic that is easily tested and easily reasoned about.

That's a lot to take in. Why don't we take a break here and enjoy a Blueberry Acai Diet Coke before moving on to the next section?

## Walk-thru of Map

To make sure we clearly understand what is going on here, let's walk through the map implementation for arrays. Here is the code again...

### Map's Guts

```typescript
class Array<A> {
 //... a bunch of stuff that makes arrays arrays
 map = (fn: (a: A) => B): Array => {
 const newArray: B[] = [];

 for (let i = 0; i < this.length; i++) {
 const b = fn(this[i]);
 newArray.push(b);
 }

 return newArray;
 };
}
```

Line 4: When we enter into map, the first thing that happens is a new Array is instantiated.

Line 7: Then, we apply fn to each item in the array.

Line 8: The result of that function call is appended to the new array.

Line 11. Then we return the new array.

In the case where the array is empty, the looping logic falls through and we simply return the new, empty array.

## Walk-thru of concatMap

Now we'll do the same walk through, but with concatMap. Here's the code again:

### concatMap

```typescript
class Array<A> {
 //... a bunch of stuff that makes arrays arrays
 concatMap = (fn: (a: A) => B[]): Array => {
 let newArray: B[] = [];

 for (let i = 0; i < this.length; i++) {
 const bs = fn(this[i]);
 newArray = newArray.concat(bs);
 }

 return newArray;
 };
}
```

Line 4: When we enter into concatMap, we start by create a new array (same as with map)

Line 7: Then we apply fn to each item in the array. In the case of concatMap, the result from fn will be another array.

Line 8: Next we concatenate the array from line 7, onto the new array that we are constructing.

Line 11: Finally, we return our new array, which is flattened out without any nesting.

In the case where the array is empty, the loop logic falls through and the empty array is returned.

## Other Mappable Types

We can now take this understanding of map and concatMap and apply it to other mappable types. For example, let's create a data type that represents an optional value. This is a type that can replace the use of undefined. It encapsulates checks for undefined in one place, and makes it possible to cleanly chain together computations on values that may or may not be available.

Let's start with a simple class definition for Optional:

```typescript
class Optional<A> {
 public static some = <A>(value: A) => {
 return new Optional<A>(value);
 };

 public static none = <A>() => {
 return new Optional<A>();
 };

 private value?: A;

 private constructor(value?: A) {
 this.value = value;
 }

 // ... more to come
}
```

This class has a private value that could be undefined, or it could be some generic type of A.

So far we can construct some value or we can construct a none value, but since the value is private, we can't do anything with it. Let's add a map method first, so we can at least get at the value. As we read this code, try to keep the Array map intuition in mind. The None case is like having an empty array, and the Some case is like having a one item array. Let's write this:

```typescript
class Optional<A> {
 // ... constructors and stuff

 map = (fn: (a: A) => B) => {
 return typeof this.value !== 'undefined' ? Optional.some(fn(this.value)) : Optional.none();
 };
}
```

Because there is no looping construct here, this logic is a bit more direct. We check if the value is defined. If it is, we apply fn to the value and return it wrapped in a new some. Otherwise, we return none.

The concatMap implementation is equally direct.

```typescript
class Optional<A> {
 // ... constructors and stuff

 concatMap = (fn: (a: A) => Optional) => {
 return typeof this.value !== 'undefined' ? fn(this.value) : Optional.none();
 };
}
```

Now we can compose operations that may fail or return no results in the same way we could chain those calls to an array. For example:

```typescript
const add =
 (n1: number) =>
 (n2: number): n => {
 return n1 + n2;
 };

const safeDiv =
 (dividend: number) =>
 (divisor: number): Optional<number> => {
 return divisor === 0 ? Optional.none() : Optional.some(dividend / divisor);
 };

Optional.some(2).map(add(-2)).concatMap(safeDiv(4));
```

Rather then producing NaN, this code will return None if the division fails (divide by zero error). That makes it easier to chain operations together.

## Some Final Notes

We've demonstrated the logic behind map and concatMap in terms of Arrays, so that we can leverage that intuition and apply it to other mappable types. We've even looked at some hypothetical implementations of map and concatMap to help our understanding.

When developing using CooperTS, our default optional value is actually called Maybe. But the logic and implementation details are applicable, only the names have been changed.

Also note, concatMap can be known by many names: bind, chain, flatMap,, >>=, etc. In CooperTS libraries like Maybeasy, Taskarain, and Jsonous, concatMap is named andThen.

And now you know the rest of the story.


Tony Hoare famously called NULL his "billion dollar mistake". In this post, we'll explore what null (and undefined) is, where it came from, and why we feel it is an inappropriate abstraction to use in modern business software development. We'll also explore how to program without null using CooperTS friendly libraries and patterns.

## The Birth of NULL

> I call it my billion-dollar mistake. It was the invention of the null reference in 1965. At that time, I was designing the first comprehensive type system for references in an object oriented language (ALGOL W). My goal was to ensure that all use of references should be absolutely safe, with checking performed automatically by the compiler. But I couldn't resist the temptation to put in a null reference, simply because it was so easy to implement. This has led to innumerable errors, vulnerabilities, and system crashes, which have probably caused a billion dollars of pain and damage in the last forty years.
>
> --- Tony Hoare (C.A.R. Hoare)

Null references were originally created as a stand-in value for pointers that don't actually point to valid memory. This effectively breaks early type systems. Since the NULL reference can inhabit any types, the programmer is responsible for checking every single reference to ensure that it is not a NULL reference. So this puts the responsibility of safety and security into the hands of the programmers. regardless of their experience and motivation. In most programming languages, dereferencing a null pointer results in an immediate program crash. This is usually the result of one or more developer assumptions being violated (put a pin in that). This leads to reliability problems, but Null pointer exceptions can also be used by attackers to bypass security checks or produce a core dump, revealing details about the program that can aid future attacks.

Over the years, many programming languages (Java, C#, etc,) have developed safe memory models to reduce the security risks of NULL pointer references, but many of those languages continue to allow NULL references to inhabit any type.

## The Nullable Type

Some programming languages don't specifically support a NULL reference, but instead implement a Nullable type. Ruby, for example, uses NilClass to represent the concept of NULL. A nullable type can be safely dereferenced, but as Ruby developers can attest, you still suffer from reliability problems. Sending an unsupported method to the nullable type still results in an immediate crash.

Many programming languages that support Nullable types also support a "safe" dereference operator. Newer versions of Ruby (>= 2.3), for example, use the &. operator to allow any method to be safely sent to the NilClass object. The problem with this operator is that, while the program doesn't crash, an unexpected Nullable type still represents a violation of developer assumptions. So, while the program may not crash, there is likely still a bug. How this bug will ultimately manifest is undetermined.

## The Null Object Pattern

A user space extension of the Nullable Type that some OO programmers favor is the Null Object pattern. In this pattern, a stand-in object is used to represent the absence of a value. The stand-in object upholds the interface contract of whatever object it stands-in for. Null objects then act as a no-op for side-effectual method calls, and returns a sensible default value for query method calls. Implementing the Null Object pattern across a large code base can lead to a fairly complex object graph. If you decide to go all in on Null Objects, you need to implement Null Objects for all of your business objects and then you also need to keep your null objects implementations in sync with the actual implementation. This is often error prone and tedious.

Another side effect of the Null object pattern is that, from object oriented principles, the caller should not know if it has the Null Object or the real object. But some business decisions are based on knowing if you have Nothing or Something. In this case, you are back to needing to understand the difference between having nothing and having a real value.

## The Optional Type

There is a significant impedance mismatch that comes from trying to use a low level memory abstraction to also represent a high level concept of a missing value. Some language developers (mostly typed languages) acknowledge this by NOT having NULL references and providing an Optional data type. This type is usually called Option or Maybe, depending on the language.

Optional types make the concept of Nothing (None) an explicit and first class value. Any other type can be stored in an Optional type (integers, strings, object, arrays, etc.) And it provides a consistent and reliable interface for getting at the optional values and in the case where the value isn't available, operations against an optional type short circuit, resulting in... Nothing.

Optional types can be composed through their functor or monad interfaces. They encapsulate the nothing checking so that the developer isn't required to remember to perform those checks. It also requires developers to explicitly declare when values can be optional or not, removing the risk that bugs will result from incorrect developer assumptions.

## Rolling with Optional

Rather then relying on the leaky NULL abstraction, we prefer Optional types in CooperTS. It's an explicitly declared type who's intent is to express the concept of Nothing vs. Something. It is preferred for its consistent interface and for the security and reliability taking null checking out of the hands of developers.



The CooperTS monads have two options for extracting a value from the context; `getOrElseValue` and `getOrElse`. These are not interchangeable. Be careful when choosing which one to use.

## getOrElseValue

This method is strict. The value passed to this is evaluated even if it is never needed. This option should be chosen for any value that is less expensive than an anonymous function and has no side effects.

In the context of React component rendering, choosing this can lead to bugs because you could be eagerly instantiating a component that may have side effects.

## getOrElse

This method is lazy. The function passed to this is only evaluated when it is to be used. This is the option for any value that is more expensive than function construction or if the computation has side effects.



## Imperative

Imperative programming refers to a style of programming where programming statements change the state of the program. Imperative style is a bit of a leaky abstraction because it involves manipulating memory. Many developers prefer imperative programming because it appears to grant the developer more control over the execution of the program. It also tends to lead to an interleaving of lower level programming concepts (allocating memory) with higher level concepts (business rules). This can result in a hiding of the actual intent of the code.

C, Java, JavaScript, etc. tend to be imperative programming languages.

## Declarative

Declarative programming refers to a style of programming where higher level expressions describe the behavior of the program without describing the flow control. This style prevents the interleaving of business logic with lower level algorithmic concerns. This makes is easier to swap out implementations and improve the performance at a lower level, without touching the business logic. This valuable separation of concerns can lead to programs that are easier to understand and maintain.

SQL is an example of a declarative language.


map and andThen are very similar operations and so developers new to functors and monads are often confused about when to apply which operations. The easiest way to make that decision is to allow the types to guide you. But if you are also new to type systems, this is not very helpful advice. So let’s walk through an example following the types.

## The Types

For our contrived example, we’ll assume we are working with a simple library for converting dates to strings and strings to date. This library consists of two functions. Their type signatures are presented here:

```typescript
const dateToString = (date: Date) => string;

const stringToDate = (candidate: string) => Maybe<Date>;
```

Even without the implementations, these type signatures convey a lot of information. The `dateToString` function maps a Date type to a string type, and every Date can be converted to a string. The `stringToDate` function maps a string to a Date, but since it returns `Maybe<Date>` we know that not every string produces a valid date.

## Map

Given that we have a type of `Maybe<Date>`, then we will have functor and monad interfaces with the following type signatures:

```typescript
.map<S>(fn: (value: Date) => S): Maybe<S>

.andThen<S>(fn: (value: Date) => Maybe<S>): Maybe<S>
```

If we are hoping to convert the Date to a string, then we must use `dateToString`. In this scenario, one of these interfaces will never work. Using `dateToString` with `andThen` will not even compile. So our only option here is to use `map`.

Using `dateToString` converts our functor type signature to this:

```typescript
.map<string>(dateToString): Maybe<string>
```

I’m being explicit here, but typescript will infer the return type from the function being passed. So in practice, this can usually just be written as:

```typescript
.map(dateToString)
```

This is what makes functors extremely powerful. We can now use this simple function in any context that is represented by a functor (ie. implements `map`). Result, Task, Decoder, NonEmptyList, Array; this function will work unchanged in any of them.

## AndThen

Given a type of `Maybe<string>`, then we will have functor and monad interfaces with the following type signatures:

```typescript
.map<S>(fn: (value: string) => S): Maybe<S>

.andThen<S>(fn: (value: string) => Maybe<S>): Maybe<S>
```

If we need to convert the string to a Date, then we will need to use our `stringToDate` function. We can use `.map` in this case too, but it may not be what we want. Let’s look at the type signature and see why that might be.

```typescript
.map<Maybe<Date>>(stringToDate): Maybe<Maybe<Date>>
```

This will compile, but you can see that we have a Maybe type nested within another Maybe. This nesting of a monad within the same type of monad is a red flag for maintainability and clarity. Let’s see what happens when we use the monad interface:

```typescript
.andThen<Date>(stringToDate): Maybe<Date>
```

This is much easier to maintain. We lose the nesting when we use the monad interface.

The downside to the monad interface is that our `stringToDate` function is specific to Maybe. This requires us to write new versions of the function to work with other monads. However, it is easy enough to convert a Maybe type to other monads as appropriate. In fact, `toResult` and `toTask` helpers already exist for converting between these types.

## Summary

Hopefully, this helps to clarify when it is best to use `map` vs. `andThen`.


There is often confusion about when to use each of these types since they have such similar interfaces.

The first thing to understand about these types is that their similarity is because they are all Monads. All monads will have the same interface, though they may have different uses. In some cases, the difference will be obvious. In some cases, it may be just the difference of intent. We’ll explore these differences by first looking at monads that have obviously different purposes.

## Monads

A Monad is a data abstraction that allows programs to be structured generically. A particular Monad represents a specific form of computation. The consistent interface allows programs to look the same, regardless of the nature of the computation being performed.

We’ll discuss the most commonly used monads in our system here, but there is no real limit to the types of computations that monads can represent. But the goal of the abstraction is to separate the lower-level abstraction from the higher-level abstraction, level the purpose of the code clear.

### Lists (Nonempty Lists)

A List monad is used when we are expecting the result of a computation to be indeterminate. If I ask for people named “Smith”, I may be zero people or I may get 100 people. The key is that I don’t know ahead of time how large the result set of the computation is.

In the case of a non-empty list, the computation is expected to produce at least one result.

### Decoders

A decoder is used when a computation must rely on an unknown data type. With decoders, we can validate unknown data and transform it into something useful in the application context.

### Maybe

Maybe is used for computations that may fail, but the failure either isn’t an error condition, or the reason for the failure isn’t important. For example, using our find function on an array returns a Maybe type, because the value may not be in the array.

Maybe is strongly preferred over using null, undefined, empty string, -1, or any other imperative style representations of computational failure.

### Result

Result is used for computations that may fail, but the reason for the failure is important. Decoders use Result types internally to handle the error reporting.

### Task

A Task is used for computations that may fail and the reason for failure is important. They differ from Results though because it is a lazy abstraction. The computation isn’t run until the Task is forked. This makes Tasks ideal for asynchronous operations.

Tasks are more determinate and have fewer foot guns than Promises.
