First version

Author: bjornua

docs/option.md

@@ -0,0 +1,110 @@
+# `Option<T>`
+
+This container represents an optional value. You can create a `Option<T>` by calling either of the following constructors:
+
+- `Some('Hello world')`
+- `None()`
+
+### Methods
+
+- [Option.some](#optionsome)
+- [Option.value](#optionvalue)
+- [Option.map()](#optionmap)
+- [Option.and()](#optionand)
+- [Option.unwrap()](#optionunwrap)
+- [Option.unwrapOr()](#optionunwrapor)
+
+### Full example
+
+```javascript
+import { Option, Some, None } from "containers-ts";
+
+function toNumber(s: string): Option<number> {
+  const number = Number(s);
+  if (isNaN(number)) {
+    return new None();
+  }
+  return new Some(number);
+}
+
+function addToString(s: string, n: number): Option<string> {
+  return toNumber("4").map(n => String(n + 1));
+}
+
+console.log(addToString("4", 4));
+// Outputs: Some("8")
+
+console.log(addToString("Vertical Strategy", 4));
+// Outputs: None
+```
+
+## Option.map()
+
+Map `Option<T>` into a new `Option<U>`.
+
+- [.map()](#optionmap) is used to continue work on references that may point to a value or not
+
+### Example
+
+```typescript
+const helloWorld = new Some("Hello world");
+
+// Converts Some("Hello world") → Some(11)
+const helloWorldLength = helloWorld.map(helloStr => helloStr.length);
+
+// Outputs 'Some(11)'
+console.log(helloWorldLength);
+```
+
+## Option.and()
+
+Combine `Option<T>` with another `Option<U>` to create `Option<U>`.
+
+- [.and()](#optionand) is similar to [.map()](#optionmap)
+- [.and()](#optionand) is useful for when you are combining many `Option` types.
+
+### Example
+
+```typescript
+const helloWorld = new Some("Hello world");
+
+// Converts Some("Hello world") → Some(11)
+const helloWorldLength = helloWorld.and(helloStr => new Some(helloStr.length));
+
+// Outputs 'Some(11)'
+console.log(helloWorldLength);
+```
+
+## Option.unwrap()
+
+Returns the internal value of `Option<T>`. Throws if there is no value.
+
+In general, because this function may throw, use of [.unwrap()](#optionunwrap) use is discouraged. Instead, prefer to use an if statment and check [.some](#optionsome) and handle the `None` case explicitly.
+
+- [.unwrap()](#optionunwrap) can be used when an `Option` is guaranteed to hold a value.
+- [.unwrap()](#optionunwrap) can be used when writing first versions of software and refactored later
+
+### Example:
+
+```typescript
+const helloWorld = new Some("Hello world");
+
+// Outputs 'Hello world'
+console.log(helloWorld.unwrap());
+```
+
+## Option.unwrapOr(default)
+
+Returns the internal value of `Option<T>` if any, otherwise a default value.
+
+### Example
+
+```typescript
+const helloWorld = new Some("Hello world");
+
+// Outputs 'Some("Hello world")'
+console.log(helloWorld);
+
+// Outputs 'Hello world'
+console.log(helloWorld.unwrap());
+```

docs/result.md

@@ -0,0 +1,19 @@
+### `Result<T, E>`
+
+This container represent the result of an operation that can fail. You can create a `Result<T, E>` by calling either of the following constructors:
+
+- `Ok('Hello world')`
+- `Err('Error value')`
+
+You can map optional values into new values:
+
+```typescript
+import { Option } from "containers";
+
+const helloWorld = new Some("Hello world");
+const helloWorldLength = helloWorld.map(helloStr => helloStr.length);
+
+console.log(helloWorldLength); // Will output 'Some()'
+```
+
+Checkout the full documentation for [`Option<T>`](docs/option.md) here:

package.json

@@ -0,0 +1,15 @@
+{
+  "scripts": {
+    "test": "ts-node ./node_modules/.bin/tape **/*.test.ts | tap-spec",
+    "watch-test": "nodemon -e ts -w ./src -x yarn test"
+  },
+  "dependencies": {
+    "@types/tape": "^4.2.32",
+    "nodemon": "^1.18.4",
+    "tap-spec": "^5.0.0",
+    "tape": "^4.9.1",
+    "ts-node": "^7.0.1",
+    "typedoc": "^0.12.0",
+    "typescript": "^3.0.1"
+  }
+}

readme.md

@@ -0,0 +1,18 @@
+# Containers
+
+## Installation
+
+```bash
+ yarn add containers-ts
+```
+
+## Content
+
+This module provides the containers:
+
+| Type                           | Description                    |
+| ------------------------------ | ------------------------------ |
+| [Option<T>](docs/option.md)    | Represent an optional value    |
+| [Result<R, E>](docs/result.md) | Represent a result or an error |
+
+Click the individual type to learn more about usage

src/containers/option.test.ts

@@ -0,0 +1,75 @@
+import * as test from "tape";
+import { Option, Some, None } from "./option";
+
+test("Option.some", t => {
+  const none: Option<number> = new None();
+  const some: Option<number> = new Some(4);
+
+  t.equal(none.some, false, "None.some should equal false");
+  t.equal(some.some, true, "Some.some should equal true");
+  t.end();
+});
+
+function lol(t: Option<number>) {
+  console.log(t.some);
+}
+
+test("Option.map()", t => {
+  const none: Option<number> = new None();
+  const some: Option<number> = new Some(4);
+
+  const add4 = (value: number) => value + 4;
+  const toString = (value: number) => String(value);
+
+  const noneNewValue = none.map(add4);
+  const someNewValue = some.map(add4);
+
+  t.ok(noneNewValue instanceof None, "None.map() should return None");
+  t.ok(none instanceof None, "None.map() should not mutate");
+
+  t.ok(someNewValue instanceof Some, "Some.map() should return Some");
+  const someNewValueString = some.map(toString);
+  t.equal(someNewValue.unwrap(), 8, "Some.map() should apply function");
+  t.equal(
+    someNewValueString.unwrap(),
+    "4",
+    "Some.map() should be able to map to a different type"
+  );
+  t.equal(some.unwrap(), 4, "Some.map() should not mutate");
+  t.end();
+});
+
+test("Option.unwrap()", t => {
+  const none: Option<number> = new None();
+  const some: Option<number> = new Some(4);
+
+  t.throws(() => none.unwrap(), "None.unwrap() should throw");
+  t.equal(some.unwrap(), 4, "Some(4).unwrap() should equal 4");
+  t.end();
+});
+
+test("Option.unwrapOr()", t => {
+  const none: Option<number> = new None();
+  const some: Option<number> = new Some(4);
+
+  t.equal(none.unwrapOr(8), 8, "None.unwrapOr() should return default");
+  t.equal(some.unwrapOr(8), 4, "Some(4).unwrapOr() should return value");
+  t.end();
+});
+
+test("Option.and()", t => {
+  const none: Option<number> = new None();
+  const some: Option<number> = new Some(4);
+  const toString = (n: number): Option<string> => new Some(String(n));
+  const returnNone = (n: number): Option<string> => new None();
+
+  t.equal(none.and(toString).some, false, "None.and() should return None");
+  t.equal(none.and(returnNone).some, false, "None.and() should return None");
+  t.equal(
+    some.and(toString).unwrap(),
+    "4",
+    "Some.and(() => Some) should return new Some()"
+  );
+  t.equal(some.and(returnNone).some, false, "Some.and(() => None) return None");
+  t.end();
+});

src/containers/option.ts

@@ -0,0 +1,99 @@
+import * as Result from "./option";
+
+interface OptionInterface<T> {
+  /**
+   * `true` if `.value` exists
+   * `false` if there is not `.value`
+   *
+   * This can be used to safely check if there is a value
+   * before proceding.
+   *
+   * ```
+// Here we have no `result.value`
+if (!result.some) {
+  return 'No value'
+}
+// Now the compiler knows that `result.value` must exist
+console.log(result.value)
+```
+   */
+  readonly some: boolean;
+
+  /**
+   * Maps an `Option<T>` to `Option<U>` by applying a function to a contained value.
+   */
+  /**
+   * If there is a value, map that value with `f`
+   * and return an Option with the new value.
+   *
+   * @param f A function that takes the value and maps it to a new value
+   *
+   */
+  map<U>(f: (r: T) => U): Option<U>;
+
+  /**
+   *
+   * @param f
+   */
+  and<U>(f: (r: T) => Option<U>): Option<U>;
+  unwrap(): T;
+  unwrapOr(defaultValue: T): T;
+}
+
+/**
+ * Some value `T`
+ */
+export class Some<T> implements OptionInterface<T> {
+  public readonly some: true = true;
+
+  /**
+   * The value `T` contained in this Option
+   */
+  value: T;
+  /**
+   * Create a new Option containing `value`
+   */
+  constructor(value: T) {
+    this.value = value;
+  }
+  map<U>(f: (r: T) => U): Option<U> {
+    return new Some(f(this.value));
+  }
+  and<U>(f: (r: T) => Option<U>): Option<U> {
+    return f(this.value);
+  }
+  unwrap() {
+    return this.value;
+  }
+  unwrapOr(defaultValue: T) {
+    return this.value;
+  }
+}
+
+/**
+ * No value
+ */
+export class None<T> implements OptionInterface<T> {
+  public readonly some: false = false;
+
+  constructor() {}
+  map<U>(f: (r: T) => U): Option<U> {
+    return new None();
+  }
+  and<U>(f: (r: T) => Option<U>): Option<U> {
+    return new None();
+  }
+  unwrap(): never {
+    throw new Error("Tried to unwrap None");
+  }
+  unwrapOr(defaultValue: T) {
+    return defaultValue;
+  }
+}
+
+/**
+ * `Option<T>` represents an optional value.
+ * `Option` can either be `Some<T>` and contain a value
+ * or the opposite None<T> and not contain a value.
+ */
+export type Option<T> = Some<T> | None<T>;