rstypes 1.0.0

package/lib/option.d.ts

@@ -0,0 +1,135 @@
+import { Err, Ok, Result } from "./result";
+/**
+ * An optional value.
+ *
+ * ### Example
+ * ```ts
+ * function divide(numerator: number, denominator: number): Option<number> {
+ *     if(y === 0) {
+ *         return None;
+ *     } else {
+ *         return Some(numerator / denominator);
+ *     }
+ * }
+ *
+ * let result = divide(2.0, 3.0);
+ * result.match({
+ *     Some(n) { console.log(`Result: ${x}`); },
+ *     None()  { console.log("Cannot divide by 0")}
+ * })
+ * ```
+ */
+export type Option<T> = Some<T> | None<T>;
+/**
+ * Wrap a function that can return `undefined`, `null` or `NaN`, to instead return an Option,
+ * which will be None in the above cases.
+ */
+export declare function as_option<A extends any[], T>(fn: (...args: A) => T): (...args: A) => Option<T>;
+/**
+ * Common method signatures for Option types.
+ */
+interface OptionMethods<T> {
+    /**
+     * Returns `other` if the result is `Some`, or `None` otherwise.
+     * @param other Option to return if the option is `Some`
+     */
+    and<U>(other: Option<U>): Option<U>;
+    /**
+     * Return the contained `Some` value. Will throw a hard error with the specified message if called on `None`.
+     * @param message Custom message to throw if `None`
+     */
+    expect(message: string): T;
+    /**
+     * returns `true` if the option is `Some`, `false` if `None`.
+     */
+    is_some(): this is Some<T>;
+    /**
+     * returns `true` if the option is `Some` and the value satisfies
+     * the given predicate, `false` otherwise.
+     */
+    is_some_and(predicate: (value: T) => boolean): boolean;
+    /**
+     * returns `false` if the option is `Some`, `true` if `None`.
+     */
+    is_none(): this is None<T>;
+    /**
+     * Returns `true` if the option is `None` or the value satisfies
+     * the given predicate, `false` otherwise
+     */
+    is_none_or(predicate: (value: T) => boolean): boolean;
+    /**
+     * Maps an `Option<T>` into an `Option<U>`.
+     * Will return `Some(fn(value))` if the option is `Some`, or propagate `None`.
+     * @param fn Function to transform the inner `value`
+     */
+    map<U>(fn: (arg: T) => U): Option<U>;
+    /**
+     * Pattern-match on the option, running the `Some` or `None` function in the respective cases.
+     * @param matcher Object containing a `Some(value)` and `None(error)` function to run
+     */
+    match<R>(matcher: {
+        Some(value: T): R;
+        None(): R;
+    }): R;
+    /**
+     * Pattern-match on the option, running the former or latter function
+     * in the `Some` or `None` cases respectively.
+     * @param on_some Function to run if the option is `Some`
+     * @param on_none Function to run if the option is `None`
+     */
+    match<R>(on_some: (value: T) => R, on_none: () => R): R;
+    /**
+     * Transforms the Option into a Result, mapping Some(value) to Ok(value)
+     * and None to Err(error).
+     * @param error Err value to use if the option is `None`
+     */
+    ok_or<E>(error: E): Result<T, E>;
+    /**
+     * Returns `other` if the result is `None`, otherwise returns the first option's `Some` value.
+     * @param other Option to return if the option is `Some`
+     */
+    or(other: Option<T>): Option<T>;
+    /**
+     * Return the contained `Some` value. Will throw a hard error if called on `None`.
+     */
+    unwrap(): T;
+    /**
+     * Return the contained `Some` value, or `default_value` if called on `None`.
+     * @param default_value Value to use if the option is `None`
+     */
+    unwrap_or(default_value: T): T;
+    /**
+     * Return the contained `Some` value, or the result of `otherwise` if called on `None`.
+     * @param otherwise Function to run if the option is `None`
+     */
+    unwrap_or_else(otherwise: () => T): T;
+    /**
+     * Returns None if either both the option and `other` are `Some` or `None`,
+     * or the single `Some(value)` otherwise.
+     */
+    xor(other: Option<T>): Option<T>;
+}
+/**
+ * A present optional value.
+ */
+export interface Some<T> extends OptionMethods<T> {
+    map<U>(fn: (value: T) => U): Some<U>;
+    ok_or<E>(error: E): Ok<T, E>;
+    or(other: Option<T>): Some<T>;
+}
+/**
+ * No optional value.
+ */
+export interface None<T = any> extends OptionMethods<T> {
+    and<U>(other: Option<U>): None<U>;
+    expect(message: string): never;
+    map<U>(fn: (value: T) => U): None<U>;
+    ok_or<E>(error: E): Err<T, E>;
+    unwrap(): never;
+}
+/**
+ * @param value Inner value
+ */
+export declare const Some: <T>(value: T) => Some<T>;
+export declare const None: None;
+export {};

package/lib/option.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.None = exports.Some = void 0;
+exports.as_option = as_option;
+const result_1 = require("./result");
+/**
+ * Wrap a function that can return `undefined`, `null` or `NaN`, to instead return an Option,
+ * which will be None in the above cases.
+ */
+function as_option(fn) {
+    return (...args) => {
+        let out = fn(...args);
+        if ((typeof out === "number" && isNaN(out))
+            || out === null
+            || out === "undefined") {
+            return exports.None;
+        }
+        return (0, exports.Some)(out);
+    };
+}
+// Implementations
+const nodeInspect = Symbol.for('nodejs.util.inspect.custom');
+/**
+ * @param value Inner value
+ */
+const Some = (value) => ({
+    and(other) { return other; },
+    expect() { return value; },
+    is_some() { return true; },
+    is_some_and(predicate) { return predicate(value); },
+    is_none() { return false; },
+    is_none_or(predicate) { return predicate(value); },
+    map(fn) { return (0, exports.Some)(fn(value)); },
+    match(matcher_or_some) {
+        if ("Some" in matcher_or_some) {
+            return matcher_or_some.Some(value);
+        }
+        return matcher_or_some(value);
+    },
+    ok_or() { return (0, result_1.Ok)(value); },
+    or() { return this; },
+    unwrap() { return value; },
+    unwrap_or() { return value; },
+    unwrap_or_else(_) { return value; },
+    xor(other) { return other.is_none() ? this : exports.None; },
+    toString() { return `Some(${value})`; },
+    [nodeInspect](_depth, inspectOptions, inspect) {
+        const cyan = inspectOptions.colors ? `\x1b[${inspect.colors.cyan[0]}m` : "";
+        const reset = inspectOptions.colors ? `\x1b[${inspect.colors.reset[0]}m` : "";
+        return `${cyan}Some${reset}(${inspect(value, inspectOptions)})`;
+    }
+});
+exports.Some = Some;
+exports.None = Object.freeze({
+    and() { return this; },
+    expect(message) { throw Error(message); },
+    is_some() { return false; },
+    is_some_and() { return false; },
+    is_none() { return true; },
+    is_none_or() { return true; },
+    map() { return exports.None; },
+    match(matcher_or_some, none) {
+        if ("None" in matcher_or_some) {
+            return matcher_or_some.None();
+        }
+        return none();
+    },
+    ok_or(err) { return (0, result_1.Err)(err); },
+    or(other) { return other; },
+    unwrap() { throw Error("Called unwrap on a None value"); },
+    unwrap_or(default_value) { return default_value; },
+    unwrap_or_else(otherwise) { return otherwise(); },
+    xor(other) { return other.is_some() ? other : exports.None; },
+    toString() { return "None"; },
+    [nodeInspect](_depth, inspectOptions, inspect) {
+        const yellow = inspectOptions.colors ? `\x1b[${inspect.colors.yellow[0]}m` : "";
+        const reset = inspectOptions.colors ? `\x1b[${inspect.colors.reset[0]}m` : "";
+        return `${yellow}None${reset}`;
+    }
+});

package/lib/result.d.ts

@@ -0,0 +1,148 @@
+import { None, Option, Some } from "./option";
+/**
+ * A succesful value or an expected, recoverable error.
+ *
+ * ### Example
+ * ```ts
+ * function parse_int(n: string): Result<number, string> {
+ *     let maybe = parseInt(n);
+ *     if(isNaN(maybe)) return Err("Could not parse input");
+ *     return Ok(maybe);
+ * }
+ *
+ * let result = parse_int(3);
+ * result.match({
+ *     Ok(value)  { console.log("Parsed number: ", value) },
+ *     Err(error) { console.error("Error: ", error)}
+ * });
+ * ```
+ */
+export type Result<T, E> = Ok<T, E> | Err<T, E>;
+/**
+ * Wrap a function that can throw, returning `Ok(fn())` if the function returns, `Err(error)` if it throws `error`.
+ * @param fn function that potentially throws
+ */
+export declare function as_result<A extends any[], T>(fn: (...args: A) => T): (...args: A) => Result<T, any>;
+/**
+ * Common method signatures for Result types.
+ */
+interface ResultMethods<T, E> {
+    /**
+     * Returns `other` if the result is `Ok`, otherwise returns the first result's Err value.
+     * @param other result to return if the result is `Ok`.
+     */
+    and<U>(other: Result<U, E>): Result<U, E>;
+    /**
+     * Transforms `Result<T, E>` into an `Option<E>`, mapping `Ok(value)` to `None` discarding `value`
+     * and `Err(error)` to `Some(error)`.
+     */
+    err(): Option<E>;
+    /**
+     * Return the contained `Ok` value. Will throw a hard error with the specified message if called on `Err`.
+     * @param message custom message to throw if `None`
+     */
+    expect(message: string): T;
+    /**
+     * returns `true` if the result is `Ok`, `false` if `Err`.
+     */
+    is_ok(): this is Ok<T, E>;
+    /**
+     * returns `true` if the result is `Ok` and the value satisfies
+     * the given predicate, `false` otherwise.
+     */
+    is_ok_and(predicate: (value: T) => boolean): boolean;
+    /**
+     * returns `false` if the result is `Ok`, `true` if `Err`.
+     */
+    is_err(): this is Err<T, E>;
+    /**
+     * returns `true` if the result is `Err` and the error satisfies
+     * the given predicate, `false` otherwise.
+     */
+    is_err_and(predicate: (error: E) => boolean): boolean;
+    /**
+     * Maps a `Result<T, E>` into a `Result<U, E>`.
+     * Will return `Ok(fn(value))` if the result is `Ok`, or propagate `Err`.
+     * @param fn function to transform the inner value
+     */
+    map<U>(fn: (value: T) => U): Result<U, E>;
+    /**
+     * Maps a `Result<T, E>` into a `Result<T, F>`.
+     * Will propagate `Ok`, or return `Err(fn(error))` if the result is `Err`.
+     * @param fn function to transform the inner value
+     */
+    map_err<F>(fn: (error: E) => F): Result<T, F>;
+    /**
+     * Pattern-match on the result, running the `Ok` or `Err` function in the respective cases.
+     * @param matcher object containing an `Ok(value)` and `Err(error)` function to run
+     */
+    match<R>(matcher: {
+        Ok(value: T): R;
+        Err(error: E): R;
+    }): R;
+    /**
+     * Pattern-match on the result, running the former or latter function
+     * in the `Ok` and `Err` cases respectively.
+     *
+     * @param on_ok function to run if the result is `Ok(value)`
+     * @param on_err function to run if the option is `Err(error)`
+     */
+    match<R>(on_ok: (value: T) => R, on_err: (error: E) => R): R;
+    /**
+     * Transforms the `Result<T, E>` into an `Option<T>`, mapping `Ok(value)` to `Some(value)`
+     * and `Err(error)` to `None`, discarding `error`.
+     */
+    ok(): Option<T>;
+    /**
+     * Returns `other` if the result is `Err`, otherwise returns the first result's `Ok` value.
+     * @param other result to return if the result is `Err`.
+     */
+    or<F>(other: Result<T, F>): Result<T, F>;
+    /**
+     * Return the contained `Ok` value. Will throw a hard error if called on `Err`.
+     */
+    unwrap(): T;
+    /**
+     * Return the contained `Ok` value, or `default_value` if called on `Err`.
+     * @param default_value value to use if the result is `Err`
+     */
+    unwrap_or<T>(default_value: T): T;
+    /**
+     * Return the contained `Ok` value, or the result of `otherwise` if called on `Err`.
+     * @param otherwise function to use if the result is `Err`
+     */
+    unwrap_or_else<T>(otherwise: (error: E) => T): T;
+}
+/**
+ * A succesful result.
+ */
+export interface Ok<T, E> extends ResultMethods<T, E> {
+    err(): None<E>;
+    is_err_and(predicate: (error: E) => boolean): false;
+    map<U>(fn: (value: T) => U): Ok<U, E>;
+    map_err<F>(fn: (error: E) => F): Ok<T, F>;
+    ok(): Some<T>;
+    or<F>(other: Result<T, F>): Ok<T, F>;
+}
+/**
+ * An expected, recoverable error.
+ */
+export interface Err<T, E> extends ResultMethods<T, E> {
+    and<U>(other: Result<U, E>): Err<U, E>;
+    err(): Some<E>;
+    expect(message: string): never;
+    is_ok_and(predicate: (value: T) => boolean): false;
+    map<U>(fn: (value: T) => U): Err<U, E>;
+    map_err<F>(fn: (error: E) => F): Err<T, F>;
+    ok(): None<T>;
+    unwrap(): never;
+}
+/**
+ * @param value Inner value
+ */
+export declare const Ok: <T, E>(value: T) => Ok<T, E>;
+/**
+ * @param error Inner error
+ */
+export declare const Err: <T, E>(error: E) => Err<T, E>;
+export {};

package/lib/result.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Err = exports.Ok = void 0;
+exports.as_result = as_result;
+const option_1 = require("./option");
+/**
+ * Wrap a function that can throw, returning `Ok(fn())` if the function returns, `Err(error)` if it throws `error`.
+ * @param fn function that potentially throws
+ */
+function as_result(fn) {
+    return (...args) => {
+        try {
+            return (0, exports.Ok)(fn(...args));
+        }
+        catch (x) {
+            return (0, exports.Err)(x);
+        }
+    };
+}
+// Implementations
+const nodeInspect = Symbol.for('nodejs.util.inspect.custom');
+/**
+ * @param value Inner value
+ */
+const Ok = (value) => ({
+    and(other) { return other; },
+    err() { return option_1.None; },
+    expect() { return value; },
+    is_err() { return false; },
+    is_err_and() { return false; },
+    is_ok() { return true; },
+    is_ok_and(predicate) { return predicate(value); },
+    map(fn) { return (0, exports.Ok)(fn(value)); },
+    map_err() { return this; },
+    match(matcher_or_ok) {
+        if ("Ok" in matcher_or_ok) {
+            return matcher_or_ok.Ok(value);
+        }
+        return matcher_or_ok(value);
+    },
+    ok() { return (0, option_1.Some)(value); },
+    or() { return this; },
+    unwrap() { return value; },
+    unwrap_or() { return value; },
+    unwrap_or_else() { return value; },
+    toString() { return `Ok(${value})`; },
+    [nodeInspect](_depth, inspectOptions, inspect) {
+        const green = inspectOptions.colors ? `\x1b[${inspect.colors.green[0]}m` : "";
+        const reset = inspectOptions.colors ? `\x1b[${inspect.colors.reset[0]}m` : "";
+        return `${green}Ok${reset}(${inspect(value, inspectOptions)})`;
+    }
+});
+exports.Ok = Ok;
+/**
+ * @param error Inner error
+ */
+const Err = (error) => ({
+    and() { return this; },
+    err() { return (0, option_1.Some)(error); },
+    expect(message) { throw Error(`${message}: ${error}`); },
+    is_err() { return true; },
+    is_err_and(predicate) { return predicate(error); },
+    is_ok() { return false; },
+    is_ok_and() { return false; },
+    map() { return this; },
+    map_err(fn) { return (0, exports.Err)(fn(error)); },
+    match(matcher_or_ok, err) {
+        if ("Err" in matcher_or_ok) {
+            return matcher_or_ok.Err(error);
+        }
+        return err(error);
+    },
+    ok() { return option_1.None; },
+    or(other) { return other; },
+    unwrap() { throw Error(`Called unwrap on an Err value: ${error}`); },
+    unwrap_or(default_value) { return default_value; },
+    unwrap_or_else(otherwise) { return otherwise(error); },
+    toString() { return `Err(${error})`; },
+    [nodeInspect](_depth, inspectOptions, inspect) {
+        const red = inspectOptions.colors ? `\x1b[${inspect.colors.red[0]}m` : "";
+        const reset = inspectOptions.colors ? `\x1b[${inspect.colors.reset[0]}m` : "";
+        return `${red}Err${reset}(${inspect(error, inspectOptions)})`;
+    }
+});
+exports.Err = Err;

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "rstypes",
+  "version": "1.0.0",
+  "description": "Type-safe implementation of Rust's Option and Result types",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/p2js/rstypes"
+  },
+  "homepage": "https://github.com/p2js/rstypes",
+  "exports": {
+    "./option": {
+      "default": "./lib/option.js",
+      "types": "./lib/option.d.ts"
+    },
+    "./result": {
+      "default": "./lib/result.js",
+      "types": "./lib/result.d.ts"
+    }
+  },
+  "files": [
+    "lib",
+    "readme.md"
+  ],
+  "keywords": [
+    "type-safe",
+    "typescript",
+    "types",
+    "option",
+    "result",
+    "rust",
+    "rust-types",
+    "error-handling"
+  ],
+  "author": "Alfio (https://github.com/p2js)",
+  "license": "ISC",
+  "scripts": {
+    "build": "tsc"
+  }
+}

package/readme.md

@@ -0,0 +1,218 @@
+# RSTypes
+
+Type-safe implementation of lightweight Option and Result types in TypeScript (and JavaScript).
+
+```ts
+import { Option, Some, None } from "rstypes/option";
+
+function index_in_array<T>(array: T[], search: T): Option<number> {
+    let index = array.indexOf(search);
+
+    if(index == -1) {
+        return None;
+    } else {
+        return Some(index);
+    }
+}
+
+let idx = index_in_array([1, 2, 3], 2);
+
+idx.match({
+    Some(value) { console.log("Found at index: ", value) },
+    None() { console.log("Could not find in array") }
+})
+```
+```ts
+import { Result, Ok, Err } from "rstypes/result";      // ESM
+const { Result, Ok, Err } = require("rstypes/result"); // CommonJS 
+
+function parse_int(str: string): Result<number, string> {
+    let maybe_number = parseInt(str);
+    if(isNaN(maybe_number)) return Err("Invalid string");
+    return Ok(maybe_number);
+}
+
+let result = parse_int("333");
+result.match({
+    Ok(num) { console.log("Parsed number: ", num) },
+    Err(msg) { console.log("Error parsing: ", msg) }
+});
+```
+
+## Table of contents
+
+- [Usage](#usage)
+  - [Basic type information](#basic-type-information)
+  - [Handling Option and Result values](#handling-option-and-result-values)
+    - [match](#match)
+    - [unwrap, expect](#unwrap-expect)
+    - [unwrap_or, unwrap_or_else](#unwrap_or-unwrap_or_else)
+    - [is_ok, is_err](#is_ok-is_err)
+    - [is_ok_and, is_err_and](#is_ok_and-is_err_and)
+    - [map, map_err](#map-map_err)
+    - [ok, err](#ok-err)
+    - [and, or](#and-or)
+  - [Converting standard functions](#converting-standard-functions)
+- [Developer considerations](#developer-considerations)
+
+## Usage
+
+You can install rstypes on [npm](https://npmjs.com/package/rstypes):
+
+```sh
+npm install rstypes
+```
+
+### Basic type information
+
+Use `Option<T>` to represent an optional value, for example:
+- An explicit optional parameter in a function.
+- An object that may or may not have a value in its field, but should always have that field.
+- A function that may or may not return a value.
+
+Use `Result<T, E>` to represent either a successful return value or an error that is expected and recoverable, for example:
+- A parsing function that can fail with malformed input.
+- A function that can error based on external state.
+- A function that can fail in multiple ways that should be handled separately.
+
+
+These types give you a type-safe alternative to returning `null` or `undefined` and throwing exceptions, in ways that can be handled more explicitly and are immediately clear from the function signature.
+
+### Handling Option and Result values
+
+`Option` and `Result` values can be handled almost identically (The examples below will focus on `Result` but will clarify differences with handling `Option`s).
+
+Consider an example `Result` variable:
+
+```ts
+let res: Result<number, string> = /* ... */
+```
+
+Where `number` is the `Ok` type and `string` is the `Err` type.
+
+#### match
+
+Matching on values is exhaustive, and can be done using a more verbose Rust-like syntax using an object, or simply two arrow functions for conciseness. This is considered the default way to handle values for its expressiveness and flexibility. 
+
+```ts
+res.match({
+    Ok(value) {  /* do something with value */ },
+    Err(error) { console.error(error); }
+})
+
+let x = res.match(
+    value => 2 * value,
+    error => { console.error("There was an error"); return 0; }
+);
+```
+
+> N.B. `Option` values match on the two functions `Some(value)` and `None()` instead, where the `None` case takes no arguments.
+
+#### unwrap, expect
+
+These two methods should **only** be used when you are sure that the value cannot be `Err`/`None` and just want immediate access to the inner value (ie. when the error case would violate a fundamental assumption of the program). These functions will hard error if called on `Err`/`None`, with `unwrap` throwing a generic error and `expect` throwing an error with the specified message:
+
+```ts
+let x: number = res.unwrap();
+let y: number = res.expect("Should never error with the given inputs");
+```
+
+#### unwrap_or, unwrap_or_else
+
+These two methods should be used when you don't care to handle the error case and want suitable default behaviour instead. 
+
+```ts
+let x: number = res.unwrap_or(0);
+let y: number = res.unwrap_or_else(() => Math.random()); // the function can also depend on the error value!
+```
+
+#### is_ok, is_err
+
+These two methods return true or false when the `Result` value is the appropriate variant. They can be used for more traditional/non-exhaustive handling, and TypeScript will automatically narrow the type to the respective variant within their blocks.
+
+```ts
+if(res.is_ok()) {
+    let x = res.unwrap(); // Guaranteed not to fail
+    // ...
+} else {
+    console.log("There was some error");
+}
+```
+> N.B. `Option` values have analogous predicates `is_some` and `is_none`.
+
+### is_ok_and, is_err_and
+
+These two methods return true when the result value is of the appropriate variant and a given predicate evaluates to `true` with the inner value, returning false otherwise. They can be used to check for a given property of contained values.
+
+```ts
+if(res.is_ok_and(n => n % 2 == 0)) {
+    let even = res.unwrap();
+    //...
+}
+```
+> N.B. `Option` values have equivalent `is_some_and` and `is_none_or`, with the latter returning true if the option is `None`, or `Some(value)` with the predicate being true for `value`.
+
+#### map, map_err
+
+These two methods can convert between `Result` values with a different `Ok` type and `Err` type respectively, propagating the alternate value otherwise. They can be used to perform transformations conditionally.
+
+```ts
+let s: Result<string, string> = res.map((n) => `number ${n}`);
+let e: Result<number, Error> = res.map_err((e) => Error(e));
+```
+> N.B. `Option` values only have `map` to translate between `Option<T>` and `Option<U>`.
+
+### ok, err
+
+These two methods convert a `Result<T,E>` into an `Option<T>` and `Option<E>` respectively, returning `Some(value)` if the variant matches the method called and `None` otherwise. They can be used to translate between the two types as needed.
+
+```ts
+let n: Option<number> = res.ok();
+let s: Option<number> = res.err();
+```
+> N.B. `Option` values have an equivalent `ok_or(error)` method to translate `Some(value)` into `Ok(value)` and `None` into `Err(error)`.
+
+### and, or
+
+These two methods can be used to perform logic on `Result` values, evaluating to the alternative given if the first result is `Ok` or `Err` respectively, or itself otherwise.
+
+```ts
+let res2: Result<number, string> = Err("something");
+
+let or = res2.or(res) // or == res
+let and = res2.and(res); // or == Err("something")
+```
+> N.B. `Option` values also have an `xor` method that performs similar logic, evaluating to `None` when both options are `Some` or `None` and the only `Some(value)` otherwise.
+
+### Converting standard functions
+
+This library also offers two wrappers to convert other JavaScript functions into these patterns:
+
+- `as_result` takes a function that can throw and outputs a function that returns a `Result`, with `Ok` if it returned and `Err` if it threw.
+
+```ts
+import { as_result } from "rstypes/result";
+let parse_json = as_result(JSON.parse);
+
+let parsed: Result<any, SyntaxError> = parse_json("{}");  // parsed = {}
+let error: Result<any, SyntaxError> = parse_json("abcd"); // error = Err(SyntaxError(...))
+
+```
+
+- `as_option` takes a function that can return `NaN`, `null` or `undefined` and outputs a function that returns an `Option`, with `None` if it returned one of those values or `Some` otherwise.
+
+```ts
+import { as_option } from "rstypes/option";
+let sqrt = as_option(Math.sqrt);
+
+let y1: Option<number> = sqrt(1);  // y1 = Some(1)
+let y2: Option<number> = sqrt(-1); // y2 = None
+```
+
+### Developer considerations
+
+For additional type safety (such as not being able to call `unwrap` on directly instantiated `Err` values), the outputs of `Ok(x: T)` and `Err(e: E)` are not considered to be values of `Result<T, E>` but rather of their own individual types: `Ok<T, unknown>` and `Err<unknown, E>`. This is also due to the impossibility of inferring a `T` type from a construction of `Err<unknown, E>` and vice versa, resulting in confusing type signatures when returning both from functions.
+
+Therefore, for best developer experience, take care to use explicit `Result<T, E>` type annotations where possible.
+
+> N.B. Holds analogously for `Some` and `None`.