initial commit

Author: LockBlock-dev

.gitignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+package-lock.json
+pnpm-lock.yaml
+yarn.lock

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 LockBlock-dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,83 @@
+# PoC TypeScript Option and Result type
+
+This project implements basic versions of the `Option` and `Result` type, inspired by their counterparts in the Rust programming language, to demonstrate their benefits in TypeScript.
+
+## Motivation
+
+In Rust, the [`Option`](https://doc.rust-lang.org/stable/core/option/index.html) type is used to represent the presence or absence of a value. The [`Result`](https://doc.rust-lang.org/stable/core/result/index.html) type, on the other hand, is designed for error handling, avoiding exceptions by encouraging explicit handling of both success and failure.
+
+While TypeScript supports [truthiness narrowing](https://www.typescriptlang.org/docs/handbook/2/narrowing.html#truthiness-narrowing) to determine if a value is null or undefined, making the `Option` type less crucial, the `Result` type is particularly valuable. It allows developers to represent errors directly in the return type, promoting safer and more predictable error handling by leveraging TypeScript's type system to enforce explicit handling of both success and failure cases, rather than depending on unchecked exceptions.
+
+## Overview
+
+### [`Option<T>`](./lib/option.ts)
+
+The `Option` type represent an optional value, either `Some` (a value is present) or `None` (no value). It removes ambiguity and is safer than relying on `null` or `undefined`.
+
+**Example:**
+
+```ts
+import { type Option, Some, None } from "./option";
+
+interface User {
+    id: number;
+    name: string;
+    address?: string;
+}
+
+const users: User[] = [
+    { id: 1, name: "Alice", address: "123 Main St" },
+    { id: 2, name: "Bob" },
+    { id: 3, name: "Charlie", address: "456 Oak St" },
+];
+
+function getUserAddress(userId: number): Option<string> {
+    const user = users.find((u) => u.id === userId);
+    return user && user.address ? Some(user.address) : None;
+}
+
+const opt = getUserAddress(1);
+// const opt = getUserAddress(2);
+// const opt = getUserAddress(4);
+
+if (opt.isSome()) {
+    // infered string
+    console.log(opt.unwrap());
+} else {
+    // infered never
+    console.log("No value");
+}
+```
+
+### [`Result<T, E>`](./lib/result.ts)
+
+The `Result` type represents the outcome of an operation that can succeed or fail, either `Ok` (success with a value) or `Err` (failure with an error). It avoids throwing exceptions and provides a functional approach to error handling.
+
+**Example:**
+
+```ts
+import { type Result, Ok, Err } from "./result";
+
+function divide(dividend: number, divisor: number): Result<number, Error> {
+    if (divisor === 0) {
+        return Err(new Error("Cannot divide by zero"));
+    } else {
+        return Ok(dividend / divisor);
+    }
+}
+
+const res = divide(10, 2);
+// const res = divide(10, 0);
+
+if (res.isOk()) {
+    // infered number
+    console.log(res.unwrap());
+} else if (res.isErr()) {
+    // infered Error
+    console.error(res.unwrapErr().message);
+}
+```
+
+## License
+
+See the [LICENSE](./LICENSE).

lib/option.ts

@@ -0,0 +1,69 @@
+/**
+ * Represents an optional value.
+ */
+export interface Option<T> {
+    /**
+     * Returns the contained `Some` value.
+     */
+    unwrap(): T;
+    /**
+     * Returns the contained `Some` value or a default.
+     */
+    unwrapOr(defaultValue: T): T;
+    /**
+     * Returns `true` if the option is a `Some` value.
+     */
+    isSome(): this is SomeOption<T>;
+    /**
+     * Returns `true` if the option is a `None` value.
+     */
+    isNone(): this is NoneOption;
+}
+
+type SomeOption<T> = Option<T>;
+type NoneOption = Option<never>;
+
+class OptionImpl<T> implements Option<T> {
+    private constructor(private value?: T) {}
+
+    public unwrap(): T {
+        if (this.isSome()) return this.value as T;
+
+        throw new Error(`called \`unwrap()\` on a \`None\` value`);
+    }
+
+    public unwrapOr(defaultValue: T): T {
+        return this.isSome() ? (this.value as T) : defaultValue;
+    }
+
+    public isSome(): this is SomeOption<T> {
+        return this.value !== undefined;
+    }
+
+    public isNone(): this is NoneOption {
+        return this.value === undefined;
+    }
+
+    /**
+     * Creates a new `Some` option.
+     */
+    public static some<T>(value: T): SomeOption<T> {
+        return new OptionImpl(value);
+    }
+
+    /**
+     * Creates a new `None` option.
+     */
+    public static none(): NoneOption {
+        return new OptionImpl();
+    }
+}
+
+/**
+ * Creates a new `Some` option.
+ */
+export const Some = OptionImpl.some;
+/**
+ * Creates a new `None` option.
+ */
+export const None = OptionImpl.none();

lib/result.ts

@@ -0,0 +1,101 @@
+import { Option, Some, None } from "./option";
+
+/**
+ * Represents a value that can be either a success or a failure.
+ */
+export interface Result<T, E = Error> {
+    /**
+     * Returns the contained `Ok` value.
+     */
+    unwrap(): T;
+    /**
+     * Returns the contained `Ok` value or a default.
+     */
+    unwrapOr(defaultValue: T): T;
+    /**
+     * Returns the contained `Err` value.
+     */
+    unwrapErr(): E;
+    /**
+     * Returns `true` if the result is `Ok`.
+     */
+    isOk(): this is OkResult<T>;
+    /**
+     * Returns `true` if the result is `Err`.
+     */
+    isErr(): this is ErrResult<E>;
+    /**
+     * Converts from `Result<T, E>` to `Option<T>`.
+     */
+    ok(): Option<T>;
+    /**
+     * Converts from `Result<T, E>` to `Option<E>`.
+     */
+    err(): Option<E>;
+}
+
+type OkResult<T> = Result<T, never>;
+type ErrResult<E = Error> = Result<never, E>;
+
+class ResultImpl<T, E = Error> implements Result<T, E> {
+    private constructor(private value: T | E, private isError: boolean) {}
+
+    public unwrap(): T {
+        if (this.isOk()) return this.value as T;
+
+        throw new Error(
+            `called \`unwrap()\` on an \`Err\` value: ${this.value}`,
+        );
+    }
+
+    public unwrapOr(defaultValue: T): T {
+        return this.isOk() ? (this.value as T) : defaultValue;
+    }
+
+    public unwrapErr(): E {
+        if (this.isErr()) return this.value as E;
+
+        throw new Error(
+            `called \`unwrapErr()\` on an \`Ok\` value: ${this.value}`,
+        );
+    }
+
+    public isOk(): this is OkResult<T> {
+        return !this.isError;
+    }
+
+    public isErr(): this is ErrResult<E> {
+        return this.isError;
+    }
+
+    public ok(): Option<T> {
+        return this.isOk() ? Some(this.value as T) : None;
+    }
+
+    public err(): Option<E> {
+        return this.isErr() ? Some(this.value as E) : None;
+    }
+
+    /**
+     * Creates a new `Ok` result.
+     */
+    public static ok<T>(value: T): OkResult<T> {
+        return new ResultImpl<T, never>(value, false);
+    }
+
+    /**
+     * Creates a new `Err` result.
+     */
+    public static err<E = Error>(error: E): ErrResult<E> {
+        return new ResultImpl<never, E>(error, true);
+    }
+}
+
+/**
+ * Creates a new `Ok` result.
+ */
+export const Ok = ResultImpl.ok;
+/**
+ * Creates a new `Err` result.
+ */
+export const Err = ResultImpl.err;

package.json

@@ -0,0 +1,14 @@
+{
+    "name": "poc-ts-option-and-result-type",
+    "private": true,
+    "version": "1.0.0",
+    "author": "LockBlock-dev",
+    "license": "MIT",
+    "scripts": {
+        "build": "tsc",
+        "watch": "tsc -w"
+    },
+    "devDependencies": {
+        "typescript": "^5.7.2"
+    }
+}

tsconfig.json

@@ -0,0 +1,14 @@
+{
+    "compilerOptions": {
+        "target": "ESNext",
+        "module": "CommonJS",
+        "rootDir": "lib",
+        "moduleResolution": "node",
+        "outDir": "./dist",
+        "esModuleInterop": true,
+        "forceConsistentCasingInFileNames": true,
+
+        "strict": true,
+        "skipLibCheck": true
+    }
+}