@theateros/result 0.0.1

package/README.md

@@ -0,0 +1,201 @@
+# Theater OS - Result
+
+<p align="center">
+  <img src="../../.etc/assets/result-logo.webp" alt="Theater OS - Foundations - Result">
+</p>
+
+A type-safe Result type implementation for TypeScript that provides a functional approach to error handling without throwing exceptions and allows codebases to take care of their wrong path.
+
+## Why Result?
+
+Traditional error handling in JavaScript/TypeScript relies on exceptions, which have several limitations:
+
+- **No type safety**: You can't know at compile time if a function might throw
+- **Unpredictable control flow**: Exceptions can be thrown anywhere, making code flow hard to follow
+- **No explicit error types**: You don't know what errors a function might produce
+- **Hard to compose**: Chaining operations that might fail requires try-catch blocks everywhere
+
+`Result` addresses these issues by providing:
+
+- **Type-safe error handling**: The type system enforces handling both success and error cases
+- **Explicit error types**: Errors are part of the return type, making them visible and type-checked
+- **Composable operations**: Chain operations without nested try-catch blocks
+- **No exceptions**: Errors are values, not thrown exceptions
+- **Functional style**: Inspired by Rust's `Result<T, E>` type
+
+## Installation
+
+```bash
+npm install @theateros/result
+```
+
+## Getting Started
+
+### Basic Usage
+
+```typescript
+import { Result } from '@theateros/result'
+
+// Create a successful result
+const success = Result.ok('Operation completed')
+
+// Create an error result
+const failure = Result.err('Something went wrong')
+
+// Check the result
+if (Result.isOk(success)) {
+  console.log('Value:', success.value)
+}
+
+if (Result.isErr(failure)) {
+  console.log('Error:', failure.error)
+}
+```
+
+### Creating Results
+
+Results can represent either success (`Ok`) or failure (`Err`):
+
+```typescript
+import { Result } from '@theateros/result'
+
+// Success case
+const userResult = Result.ok({ id: 1, name: 'John' })
+
+// Error case
+const errorResult = Result.err('User not found')
+
+// Use type guards to narrow the type
+if (Result.isOk(userResult)) {
+  // TypeScript knows this is Ok<{ id: number, name: string }>
+  console.log(userResult.value.name)
+}
+
+if (Result.isErr(errorResult)) {
+  // TypeScript knows this is Err<string>
+  console.log(errorResult.error)
+}
+```
+
+### Type Guards
+
+Use type guards to safely check and narrow result types:
+
+```typescript
+import { Result } from '@theateros/result'
+
+function processResult<T, E>(result: Result<T, E>) {
+  if (Result.isOk(result)) {
+    // TypeScript knows result is Ok<T>
+    return result.value
+  }
+
+  if (Result.isErr(result)) {
+    // TypeScript knows result is Err<E>
+    return result.error
+  }
+}
+
+// Check if something is a Result
+const unknown: unknown = Result.ok(42)
+if (Result.is(unknown)) {
+  // Now we know it's a Result
+  if (Result.isOk(unknown)) {
+    console.log(unknown.value)
+  }
+}
+```
+
+### Unwrapping Results
+
+Safely extract values from results with optional default values:
+
+```typescript
+import { Result } from '@theateros/result'
+
+// Unwrap with default value
+const result = Result.err('Failed')
+const value = Result.unwrap(result, 'default value')
+// value === 'default value'
+
+// Unwrap without default (throws if Err)
+const okResult = Result.ok('success')
+const unwrapped = Result.unwrap(okResult)
+// unwrapped === 'success'
+
+// Throws if no default provided
+// (carrefull when using this method because you
+// can possibly break flows entierely).
+try {
+  Result.unwrap(Result.err('error'))
+} catch (error) {
+  // error === 'error'
+}
+```
+
+### Safe Function Wrapping
+
+Wrap functions that might throw to return Results instead:
+
+```typescript
+import { Result } from '@theateros/result'
+
+// Wrap a function that might throw
+const safeParse = Result.safe((json: string) => JSON.parse(json))
+
+// Now it returns a Result instead of throwing
+const result = safeParse('{"key": "value"}')
+
+if (Result.isOk(result)) {
+  console.log(result.value) // Parsed object
+} else {
+  console.log('Parse failed:', result.error)
+}
+
+// With error transformation
+const safeParseWithError = Result.safe(
+  (json: string) => JSON.parse(json),
+  error => `Parse error: ${String(error)}`
+)
+
+const result2 = safeParseWithError('invalid')
+if (Result.isErr(result2)) {
+  console.log(result2.error) // "Parse error: ..."
+}
+```
+
+## API Reference
+
+### `Result` Namespace
+
+The main namespace containing all Result utilities.
+
+#### Types
+
+- **`Ok<T>`**: Represents a successful result with value of type `T`
+- **`Err<E>`**: Represents a failed result with error of type `E`
+- **`Result<T, E>`**: Union type representing either `Ok<T>` or `Err<E>`
+
+#### Static Methods
+
+- **`Result.ok<T>(value: T): Ok<T>`**: Creates a new Ok result
+- **`Result.err<E>(error: E): Err<E>`**: Creates a new Err result
+- **`Result.is<T, E>(result: unknown): result is Result<T, E>`**: Type guard to check if a value is a Result
+- **`Result.isOk<T>(result: unknown): result is Ok<T>`**: Type guard to check if a result is Ok
+- **`Result.isErr<E>(result: unknown): result is Err<E>`**: Type guard to check if a result is Err
+- **`Result.unwrap<T, E>(result: Result<T, E>, defaultValue?: T): T`**: Unwraps a result, returning the value or default, or throwing the error
+- **`Result.safe<Fn, E>(fn: Fn, onError?: (error: unknown) => E)`**: Wraps a function to return Results instead of throwing
+
+#### Properties
+
+**Ok<T>**:
+- **`_type: symbol`**: Brand symbol for type checking
+- **`_kind: symbol`**: Brand symbol for Ok kind
+- **`value: T`**: The success value
+- **`error?: never`**: Always undefined for Ok results
+
+**Err<E>**:
+- **`_type: symbol`**: Brand symbol for type checking
+- **`_kind: symbol`**: Brand symbol for Err kind
+- **`error: E`**: The error value
+- **`value?: never`**: Always undefined for Err results

package/dist/result.d.ts

@@ -0,0 +1,146 @@
+declare const resultSymbol: unique symbol;
+declare const okSymbol: unique symbol;
+declare const errSymbol: unique symbol;
+declare const unsetDefaultValueSymbol: unique symbol;
+/**
+ * The Ok type represents a successful result.
+ *
+ * @typeparam T - The value type.
+ */
+export type Ok<T> = {
+    /**
+     * The type of the result. Allows us to brand the type of the result and ensure that
+     * that is comming from the @theateros/result package.
+     */
+    _type: typeof resultSymbol;
+    /**
+     * The kind of the result. Allows us to brand the kind of the result and ensure that
+     * that is comming from the @theateros/result package.
+     */
+    _kind: typeof okSymbol;
+    /**
+     * The value of the result.
+     */
+    value: T;
+    /**
+     * The error of the result. Should be never because the result is OK.
+     */
+    error?: never;
+};
+/**
+ * The Err type represents a failed result.
+ *
+ * @typeparam E - The error type.
+ */
+export type Err<E> = {
+    /**
+     * The type of the result. Allows us to brand the type of the result and ensure that
+     * that is comming from the @theateros/result package.
+     */
+    _type: typeof resultSymbol;
+    /**
+     * The kind of the result. Allows us to brand the kind of the result and ensure that
+     * that is comming from the @theateros/result package.
+     */
+    _kind: typeof errSymbol;
+    /**
+     * The error of the result.
+     */
+    error: E;
+    /**
+     * The value of the result. Should be never because the result is an error.
+     */
+    value?: never;
+};
+/**
+ * The Result type represents a result of a computation.
+ *
+ * @typeparam T - The value type.
+ * @typeparam E - The error type.
+ */
+export type Result<T, E> = Ok<T> | Err<E>;
+export declare namespace Result {
+    /**
+     * Create a new Ok result.
+     *
+     * @typeparam T - The value type.
+     * @param value - The value of the result.
+     * @returns A new Ok result.
+     */
+    export function ok<T>(value: T): Ok<T>;
+    /**
+     * Create a new Err result.
+     *
+     * @typeparam E - The error type.
+     * @param error - The error of the result.
+     * @returns A new Err result.
+     */
+    export function err<E>(error: E): Err<E>;
+    /**
+     * Test if the given result is a result.
+     *
+     * @param result - The result to check.
+     *
+     * @typeparam T - The value type.
+     * @typeparam E - The error type.
+     *
+     * @returns True if the result is a result, false otherwise.
+     */
+    export function is<T = unknown, E = unknown>(result: unknown): result is Result<T, E>;
+    /**
+     * Test if the given result is an Ok result.
+     *
+     * @param result - The result to check.
+     *
+     * @typeparam T - The value type.
+     *
+     * @returns True if the result is an Ok result, false otherwise.
+     */
+    export function isOk<T = unknown>(result: unknown): result is Ok<T>;
+    /**
+     * Test if the given result is an Err result.
+     *
+     * @param result - The result to check.
+     *
+     * @typeparam E - The error type.
+     *
+     * @returns True if the result is an Err result, false otherwise.
+     */
+    export function isErr<E = unknown>(result: unknown): result is Err<E>;
+    /**
+     * Unwrap the value of the given result.
+     *
+     * @param result - The result to unwrap.
+     *
+     * @typeparam T - The value type.
+     * @typeparam E - The error type.
+     *
+     * @throws If the result is an Err result and the default value is the unset default value (default value
+     * is not provided), the error of the result is thrown.
+     *
+     * @returns The value of the result.
+     */
+    export function unwrap<T = unknown, E = unknown>(result: Result<T, E>, defaultValue?: T | typeof unsetDefaultValueSymbol): T;
+    /**
+     * A simple helper that represents any function.
+     *
+     * @typeparam Args - The arguments type.
+     * @typeparam Return - The return type.
+     */
+    type AnyFn = (...args: any[]) => any;
+    /**
+     * Safe wrap a function in a Result.
+     *
+     * @param fn - The function to safe wrap.
+     * @param onError - The function to handle the error.
+     *
+     * @typeparam T - The value type.
+     * @typeparam E - The error type.
+     *
+     * @returns A new function that wraps the given function in a Result.
+     */
+    export function safe<Fn extends AnyFn, E = unknown>(fn: Fn, onError?: (error: unknown) => E): (...args: Parameters<Fn>) => Result<ReturnType<Fn>, E>;
+    export {};
+}
+export {};
+//# sourceMappingURL=result.d.ts.map

package/dist/result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../src/result.ts"],"names":[],"mappings":"AAAA,QAAA,MAAM,YAAY,EAAE,OAAO,MAAwC,CAAA;AACnE,QAAA,MAAM,QAAQ,EAAE,OAAO,MAA2C,CAAA;AAClE,QAAA,MAAM,SAAS,EAAE,OAAO,MAA4C,CAAA;AACpE,QAAA,MAAM,uBAAuB,EAAE,OAAO,MAA4D,CAAA;AAElG;;;;GAIG;AACH,MAAM,MAAM,EAAE,CAAC,CAAC,IAAI;IAClB;;;OAGG;IACH,KAAK,EAAE,OAAO,YAAY,CAAA;IAE1B;;;OAGG;IACH,KAAK,EAAE,OAAO,QAAQ,CAAA;IAEtB;;OAEG;IACH,KAAK,EAAE,CAAC,CAAA;IAER;;OAEG;IACH,KAAK,CAAC,EAAE,KAAK,CAAA;CACd,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,GAAG,CAAC,CAAC,IAAI;IACnB;;;OAGG;IACH,KAAK,EAAE,OAAO,YAAY,CAAA;IAE1B;;;OAGG;IACH,KAAK,EAAE,OAAO,SAAS,CAAA;IAEvB;;OAEG;IACH,KAAK,EAAE,CAAC,CAAA;IAER;;OAEG;IACH,KAAK,CAAC,EAAE,KAAK,CAAA;CACd,CAAA;AAED;;;;;GAKG;AACH,MAAM,MAAM,MAAM,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAA;AAEzC,yBAAiB,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,MAAM,UAAU,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAErC;IAED;;;;;;OAMG;IACH,MAAM,UAAU,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAEvC;IAED;;;;;;;;;OASG;IACH,MAAM,UAAU,EAAE,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAEpF;IAED;;;;;;;;OAQG;IACH,MAAM,UAAU,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI,EAAE,CAAC,CAAC,CAAC,CAMlE;IAED;;;;;;;;OAQG;IACH,MAAM,UAAU,KAAK,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,CAMpE;IAED;;;;;;;;;;;;OAYG;IACH,MAAM,UAAU,MAAM,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EAC7C,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,EACpB,YAAY,GAAE,CAAC,GAAG,OAAO,uBAAiD,GACzE,CAAC,CAUH;IAED;;;;;OAKG;IAEH,KAAK,KAAK,GAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAA;IAEpC;;;;;;;;;;OAUG;IACH,MAAM,UAAU,IAAI,CAAC,EAAE,SAAS,KAAK,EAAE,CAAC,GAAG,OAAO,EAAE,EAAE,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC,IACjF,GAAG,MAAM,UAAU,CAAC,EAAE,CAAC,KAAG,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAa5D;;CACF"}

package/dist/result.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Result = void 0;
+const resultSymbol = Symbol.for('@theateros/result');
+const okSymbol = Symbol.for('@theateros/result/ok');
+const errSymbol = Symbol.for('@theateros/result/err');
+const unsetDefaultValueSymbol = Symbol.for('@theateros/result/unset-default-value');
+var Result;
+(function (Result) {
+    /**
+     * Create a new Ok result.
+     *
+     * @typeparam T - The value type.
+     * @param value - The value of the result.
+     * @returns A new Ok result.
+     */
+    function ok(value) {
+        return { _type: resultSymbol, _kind: okSymbol, value };
+    }
+    Result.ok = ok;
+    /**
+     * Create a new Err result.
+     *
+     * @typeparam E - The error type.
+     * @param error - The error of the result.
+     * @returns A new Err result.
+     */
+    function err(error) {
+        return { _type: resultSymbol, _kind: errSymbol, error };
+    }
+    Result.err = err;
+    /**
+     * Test if the given result is a result.
+     *
+     * @param result - The result to check.
+     *
+     * @typeparam T - The value type.
+     * @typeparam E - The error type.
+     *
+     * @returns True if the result is a result, false otherwise.
+     */
+    function is(result) {
+        return result instanceof Object && '_type' in result && '_kind' in result && result._type === resultSymbol;
+    }
+    Result.is = is;
+    /**
+     * Test if the given result is an Ok result.
+     *
+     * @param result - The result to check.
+     *
+     * @typeparam T - The value type.
+     *
+     * @returns True if the result is an Ok result, false otherwise.
+     */
+    function isOk(result) {
+        if (is(result)) {
+            return result._kind === okSymbol;
+        }
+        return false;
+    }
+    Result.isOk = isOk;
+    /**
+     * Test if the given result is an Err result.
+     *
+     * @param result - The result to check.
+     *
+     * @typeparam E - The error type.
+     *
+     * @returns True if the result is an Err result, false otherwise.
+     */
+    function isErr(result) {
+        if (is(result)) {
+            return result._kind === errSymbol;
+        }
+        return false;
+    }
+    Result.isErr = isErr;
+    /**
+     * Unwrap the value of the given result.
+     *
+     * @param result - The result to unwrap.
+     *
+     * @typeparam T - The value type.
+     * @typeparam E - The error type.
+     *
+     * @throws If the result is an Err result and the default value is the unset default value (default value
+     * is not provided), the error of the result is thrown.
+     *
+     * @returns The value of the result.
+     */
+    function unwrap(result, defaultValue = unsetDefaultValueSymbol) {
+        if (isOk(result)) {
+            return result.value;
+        }
+        if (defaultValue === unsetDefaultValueSymbol) {
+            throw result.error;
+        }
+        return defaultValue;
+    }
+    Result.unwrap = unwrap;
+    /**
+     * Safe wrap a function in a Result.
+     *
+     * @param fn - The function to safe wrap.
+     * @param onError - The function to handle the error.
+     *
+     * @typeparam T - The value type.
+     * @typeparam E - The error type.
+     *
+     * @returns A new function that wraps the given function in a Result.
+     */
+    function safe(fn, onError) {
+        return (...args) => {
+            try {
+                const value = fn(...args);
+                return ok(value);
+            }
+            catch (error) {
+                if (onError) {
+                    return err(onError(error));
+                }
+                return err(error);
+            }
+        };
+    }
+    Result.safe = safe;
+})(Result || (exports.Result = Result = {}));
+//# sourceMappingURL=result.js.map

package/dist/result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.js","sourceRoot":"","sources":["../src/result.ts"],"names":[],"mappings":";;;AAAA,MAAM,YAAY,GAAkB,MAAM,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAA;AACnE,MAAM,QAAQ,GAAkB,MAAM,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAA;AAClE,MAAM,SAAS,GAAkB,MAAM,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAA;AACpE,MAAM,uBAAuB,GAAkB,MAAM,CAAC,GAAG,CAAC,uCAAuC,CAAC,CAAA;AAoElG,IAAiB,MAAM,CAsItB;AAtID,WAAiB,MAAM;IACrB;;;;;;OAMG;IACH,SAAgB,EAAE,CAAI,KAAQ;QAC5B,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAA;IACxD,CAAC;IAFe,SAAE,KAEjB,CAAA;IAED;;;;;;OAMG;IACH,SAAgB,GAAG,CAAI,KAAQ;QAC7B,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,CAAA;IACzD,CAAC;IAFe,UAAG,MAElB,CAAA;IAED;;;;;;;;;OASG;IACH,SAAgB,EAAE,CAA2B,MAAe;QAC1D,OAAO,MAAM,YAAY,MAAM,IAAI,OAAO,IAAI,MAAM,IAAI,OAAO,IAAI,MAAM,IAAI,MAAM,CAAC,KAAK,KAAK,YAAY,CAAA;IAC5G,CAAC;IAFe,SAAE,KAEjB,CAAA;IAED;;;;;;;;OAQG;IACH,SAAgB,IAAI,CAAc,MAAe;QAC/C,IAAI,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC;YACf,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,CAAA;QAClC,CAAC;QAED,OAAO,KAAK,CAAA;IACd,CAAC;IANe,WAAI,OAMnB,CAAA;IAED;;;;;;;;OAQG;IACH,SAAgB,KAAK,CAAc,MAAe;QAChD,IAAI,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC;YACf,OAAO,MAAM,CAAC,KAAK,KAAK,SAAS,CAAA;QACnC,CAAC;QAED,OAAO,KAAK,CAAA;IACd,CAAC;IANe,YAAK,QAMpB,CAAA;IAED;;;;;;;;;;;;OAYG;IACH,SAAgB,MAAM,CACpB,MAAoB,EACpB,eAAmD,uBAAuB;QAE1E,IAAI,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YACjB,OAAO,MAAM,CAAC,KAAK,CAAA;QACrB,CAAC;QAED,IAAI,YAAY,KAAK,uBAAuB,EAAE,CAAC;YAC7C,MAAM,MAAM,CAAC,KAAK,CAAA;QACpB,CAAC;QAED,OAAO,YAAY,CAAA;IACrB,CAAC;IAbe,aAAM,SAarB,CAAA;IAWD;;;;;;;;;;OAUG;IACH,SAAgB,IAAI,CAAgC,EAAM,EAAE,OAA+B;QACzF,OAAO,CAAC,GAAG,IAAoB,EAA6B,EAAE;YAC5D,IAAI,CAAC;gBACH,MAAM,KAAK,GAAG,EAAE,CAAC,GAAG,IAAI,CAAmB,CAAA;gBAE3C,OAAO,EAAE,CAAC,KAAK,CAAC,CAAA;YAClB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAI,OAAO,EAAE,CAAC;oBACZ,OAAO,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAA;gBAC5B,CAAC;gBAED,OAAO,GAAG,CAAC,KAAU,CAAC,CAAA;YACxB,CAAC;QACH,CAAC,CAAA;IACH,CAAC;IAde,WAAI,OAcnB,CAAA;AACH,CAAC,EAtIgB,MAAM,sBAAN,MAAM,QAsItB"}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@theateros/result",
+  "version": "0.0.1",
+  "module": "dist/result.js",
+  "type": "module",
+  "scripts": {
+    "lint": "biome check .",
+    "test": "bun test",
+    "build:dist": "tsc",
+    "release": "release-it"
+  },
+  "devDependencies": {
+    "@types/bun": "catalog:",
+    "typescript": "catalog:",
+    "release-it": "catalog:"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/result.d.ts",
+      "default": "./dist/result.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}