@rotomeca/rop 0.0.2

package/.prettierc.json

@@ -0,0 +1,9 @@
+{
+	"tabWidth": 2,
+	"useTabs": true,
+	"semi": true,
+	"singleQuote": true,
+	"bracketSpacing": true,
+	"arrowParens": "avoid",
+	"quoteProps": "as-needed"
+}

package/README.md

@@ -0,0 +1,141 @@
+# 🚂 TS Railway Result
+
+A robust, lightweight, and type-safe implementation of **Railway Oriented Programming (ROP)** for TypeScript.
+Eliminate `try/catch` spaghetti code and handle errors elegantly using **Results** and **Decorators**.
+
+![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue)
+![License](https://img.shields.io/badge/License-MIT-green)
+
+## 📦 Installation
+
+```bash
+npm install @rotomeca/rop
+# or
+yarn add @rotomeca/rop
+```
+
+## 🚀 Quick Start
+
+Transform your risky operations into safe "Rails" using decorators.
+
+```typescript
+import { Risky, HappyPath, ErrorPath, Result } from '@rotomeca/rop';
+
+class UserService {
+  
+  @ErrorPath((err) => console.error(`[Admin Alert] Failed to create user: ${err.message}`))
+  @HappyPath((user) => console.log(`[Analytics] User created: ${user.name}`))
+  @Risky() // Automatically catches exceptions and converts return value to Result
+  async createUser(name: string, age: number): Promise<Result<{ name: string }>> {
+    
+    if (name.length < 3) {
+      throw new Error("Name too short"); // Will be converted to Fail(Error)
+    }
+
+    // Simulate DB call
+    return { name }; // Will be converted to Success({ name })
+  }
+}
+
+// Usage
+async function main() {
+  const service = new UserService();
+  
+  const result = await service.createUser("Alice", 25);
+
+  result.match({
+    Ok: (user) => console.log(`Welcome ${user.name}!`),
+    Err: (error) => console.log(`Oops: ${error.message}`)
+  });
+}
+```
+
+## ✨ Features
+
+* **🛡️ Type-Safe Error Handling**: No more guessing if a function throws. Returns `Result<T, E>`.
+* **✨ Powerful Decorators**:
+    * `@Risky`: Wraps methods to catch exceptions and return `Success` or `Fail`.
+    * `@HappyPath`: Execute side effects (logging, events) only on success.
+    * `@ErrorPath`: Execute side effects (monitoring, alerts) only on failure.
+* **⛓️ Fluent API**: Chain operations with `map`, `andThen` (flatMap), and `unwrapOr`.
+* **🔗 Sync & Async Support**: Works seamlessly with both synchronous functions and Promises.
+
+## 📖 Core Concepts
+
+### 1. The Result Object (`Result`)
+Instead of throwing exceptions, your functions return an `Result`. It has two states:
+* **`Success<T>`**: The operation succeeded and contains a value of type `T`.
+* **`Fail<E>`**: The operation failed and contains an error of type `E` (default is `Error`).
+
+```typescript
+import { Success, Fail, Result } from '@rotomeca/rop';
+
+function divide(a: number, b: number): Result<number> {
+  if (b === 0) {
+    return Fail.Create(new Error("Cannot divide by zero"));
+  }
+  return Success.Create(a / b);
+}
+```
+
+### 2. Matching (Pattern Matching)
+Force yourself to handle both success and failure cases.
+
+```typescript
+const result = divide(10, 2);
+
+const message = result.match({
+  Ok: (val) => `Result is ${val}`,
+  Err: (err) => `Calculation failed: ${err.message}`
+});
+```
+
+### 3. Decorators
+
+#### `@Risky()`
+Automatically wraps the method execution in a `try/catch` block.
+* If the method returns a value, it becomes `Success(value)`.
+* If the method throws, it becomes `Fail(error)`.
+* Works with `async/await` and synchronous code.
+
+#### `@HappyPath(fn)` & `@ErrorPath(fn)`
+Perfect for **Side Effects** (logging, notifications) without polluting your business logic. These decorators act as "Taps": they inspect the result but **do not** modify the return value.
+
+```typescript
+@ErrorPath((e) => Sentry.captureException(e)) // Only if fails
+@HappyPath((data) => Analytics.track('success', data)) // Only if success
+@Risky()
+saveData(data: any) { ... }
+```
+
+## 📚 API Reference
+
+### `Result<T, E>` Methods
+
+| Method | Description |
+| :--- | :--- |
+| **`match({ Ok, Err })`** | Executes `Ok` fn if success, `Err` fn if failure. Returns the result of the function. |
+| **`map(fn)`** | Transforms the inner value `T` to `U` only if Success. |
+| **`mapError(fn)`** | Transforms the inner error `E` to `NewError` only if Fail. |
+| **`andThen(fn)`** | Chains operations. `fn` must return a new `Result`. (Often called `flatMap`). |
+| **`unwrapOr(default)`** | Returns the value if Success, otherwise returns `default`. |
+| **`throwIfError()`** | Unsafe. Returns value if Success, throws the error if Fail. |
+| **`isSuccess() / isError()`** | Boolean checks for the state. |
+
+## 🧩 Advanced Usage: Chaining
+
+You can build complex pipelines that stop at the first error:
+
+```typescript
+const result = validateInput(input)           // returns Result<Input>
+  .andThen(parsed => processData(parsed))     // returns Result<Data>
+  .andThen(data => saveToDb(data))            // returns Result<Id>
+  .map(id => `Created object with ID: ${id}`); // returns Result<string>
+
+// If any step failed, 'result' is a Fail with the error of that step.
+// If all succeeded, 'result' is a Success with the final string.
+```
+
+## 📄 License
+
+MIT

package/index.ts

@@ -0,0 +1,14 @@
+// Décorateurs (API Publique principale)
+export * from './src/decorators/Risky';
+export * from './src/decorators/HappyPath';
+export * from './src/decorators/ErrorPath';
+
+// Classes & Abstractions (Pour le typage et création manuelle)
+export * from './src/classes/Fail';
+export * from './src/classes/Success';
+export {ATresult as Result} from './src/classes/abstracts/ATresult';
+
+// Types (Pour l'IntelliSense)
+export * from './src/types/resultsCallbacks'; 
+export * from './src/types/ResultMatch';
+

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@rotomeca/rop",
+  "version": "0.0.2",
+  "main": "index.ts",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "author": "Rotomeca",
+  "license": "ISC",
+  "description": "A robust, lightweight, and type-safe implementation of Railway Oriented Programming (ROP) for TypeScript.",
+  "devDependencies": {
+    "@typescript-eslint/parser": "^5.62.0",
+    "eslint": "^8.57.1",
+    "prettier": "^3.8.1",
+    "prettier-eslint": "^16.4.2",
+    "typescript": "^4.9.5"
+  }
+}

package/src/classes/Fail.ts

@@ -0,0 +1,92 @@
+// type: class
+// description: Class representing a error result.
+
+import { ResultState, ITResult } from "../interfaces/ITResult";
+import { ResultMatch } from "../types/ResultMatch";
+import { ChainedCallback, SuccessMapCallback, ErrorMapCallback } from "../types/resultsCallbacks";
+import { ATresult } from "./abstracts/ATresult";
+
+/**
+ * Class representing a failed result.
+ * @template TSuccess - The type of the success value.
+ * @template TE - The type of the error value (default is Error).
+ */
+export class Fail<TSuccess, TE = Error> extends ATresult<TSuccess, TE> {
+    /**
+     * Creates an instance of Fail.
+     * @param error The error value.
+     */
+    constructor(public readonly error: TE) { super(); }
+
+    /**
+     * Returns the state of the result.
+     * @returns The state indicating failure.
+     */
+    state(): ResultState {
+        return ResultState.Error;
+    }
+    /**
+     * Matches the result with the provided matcher functions.
+     * @param matcher The matcher object containing functions for success and error cases.
+     * @returns The result of the matched function.
+     */
+    match<Result>(matcher: ResultMatch<TSuccess, TE, Result>): Result {
+        return matcher.Err(this.error);
+    }
+    /**
+     * Chains the result with another operation that returns a new result.
+     * @param fn The function to apply if the result is successful.
+     * @returns The result of the chained operation.
+     */
+    andThen<NewSuccess>(_: ChainedCallback<TSuccess, NewSuccess, TE>): ITResult<NewSuccess, TE> {
+        return new Fail<NewSuccess, TE>(this.error);
+    }
+    /**
+     * Maps the success value to a new value.
+     * @param fn The function to apply to the success value.
+     * @returns A new Success instance containing the mapped value.
+     */
+    map<NewSuccess>(_: SuccessMapCallback<TSuccess, NewSuccess>): ITResult<NewSuccess, TE> {
+        return new Fail<NewSuccess, TE>(this.error);
+    }
+    /**
+     * Maps the error value to a new error value.
+     * @param _ The function to apply to the error value.
+     * @returns A new Success instance containing the original success value.
+     */
+    mapError<NewError>(fn: ErrorMapCallback<TE, NewError>): ITResult<TSuccess, NewError> {
+        return new Fail<TSuccess, NewError>(fn(this.error));
+    }
+
+    /**
+     * Returns the success value or throws an error if the result is an error.
+     * @throws The error value if the result is an error.
+     * @returns The success value.
+     */
+    throwIfError(): TSuccess {
+        throw this.error;
+    }
+
+    /**
+     * Retrieves the success value or returns the provided default value if the result is an error.
+     * @param defaultValue The value to return if the result is an error.
+     * @returns The success value if the result is a success, otherwise the default value.
+     */
+    unwrapOr(defaultValue: TSuccess): TSuccess {
+        return defaultValue;
+    }
+
+    /**
+     * Creates a new Fail instance.
+     * @param error The error value.
+     * @returns A new Fail instance containing the error.
+     * 
+     * @template TSuccess - The type of the success value.
+     * @template TE - The type of the error value (default is Error).
+     * 
+     * @static
+     */
+    static Create<TSuccess, TE = Error>(error: TE): Fail<TSuccess, TE> {
+        return new Fail(error);
+    }
+}

package/src/classes/Success.ts

@@ -0,0 +1,91 @@
+// type: class
+// description: Class representing a successful result.
+
+import { ResultState, ITResult } from "../interfaces/ITResult";
+import { ResultMatch } from "../types/ResultMatch";
+import { ChainedCallback, SuccessMapCallback, ErrorMapCallback } from "../types/resultsCallbacks";
+import { ATresult } from "./abstracts/ATresult";
+
+/**
+ * Class representing a successful result.
+ * @template TSuccess - The type of the success value.
+ * @template TE - The type of the error value (default is Error).
+ */
+export class Success<TSuccess, TE = Error> extends ATresult<TSuccess, TE> {
+    /**
+     * Creates an instance of Success.
+     * @param value The success value.
+     */
+    constructor(public readonly value: TSuccess) { super(); }
+
+    /**
+     * Returns the state of the result.
+     * @returns The state indicating success.
+     */
+    state(): ResultState {
+        return ResultState.Success;
+    }
+    /**
+     * Matches the result with the provided matcher functions.
+     * @param matcher The matcher object containing functions for success and error cases.
+     * @returns The result of the matched function.
+     */
+    match<Result>(matcher: ResultMatch<TSuccess, TE, Result>): Result {
+        return matcher.Ok(this.value);
+    }
+    /**
+     * Chains the result with another operation that returns a new result.
+     * @param fn The function to apply if the result is successful.
+     * @returns The result of the chained operation.
+     */
+    andThen<NewSuccess>(fn: ChainedCallback<TSuccess, NewSuccess, TE>): ITResult<NewSuccess, TE> {
+        return fn(this.value);
+    }
+    /**
+     * Maps the success value to a new value.
+     * @param fn The function to apply to the success value.
+     * @returns A new Success instance containing the mapped value.
+     */
+    map<NewSuccess>(fn: SuccessMapCallback<TSuccess, NewSuccess>): ITResult<NewSuccess, TE> {
+        return new Success(fn(this.value));
+    }
+    /**
+     * Maps the error value to a new error value.
+     * @param _ The function to apply to the error value.
+     * @returns A new Success instance containing the original success value.
+     */
+    mapError<NewError>(_: ErrorMapCallback<TE, NewError>): ITResult<TSuccess, NewError> {
+        return new Success<TSuccess, NewError>(this.value);
+    }
+
+    /**
+     * Returns the success value or throws an error if the result is an error.
+     * @returns The success value.
+     */
+    throwIfError(): TSuccess {
+        return this.value;
+    }
+
+    /**
+     * Retrieves the success value or returns the provided default value if the result is an error.
+     * @param _ The value to return if the result is an error.
+     * @returns The success value if the result is a success, otherwise the default value.
+     */
+    unwrapOr(_: TSuccess): TSuccess {
+        return this.value;
+    }
+
+    /**
+     * Creates a new Success instance.
+     * @param value The success value.
+     * @returns A new Success instance containing the value.
+     * 
+     * @template TSuccess - The type of the success value.
+     * @template TE - The type of the error value (default is Error).
+     * 
+     * @static
+     */
+    static Create<TSuccess, TE = Error>(value: TSuccess): Success<TSuccess, TE> {
+        return new Success(value);
+    }
+}

package/src/classes/abstracts/ATresult.ts

@@ -0,0 +1,74 @@
+// type: class
+// description: Abstract class implementing the ITResult interface.
+
+import { ResultState, ITResult } from "../../interfaces/ITResult";
+import { ResultMatch } from "../../types/ResultMatch";
+import { ChainedCallback, ErrorMapCallback, SuccessMapCallback } from "../../types/resultsCallbacks";
+
+/**
+ * Abstract class representing a result that can be either a success or an error.
+ */
+export abstract class ATresult<Success, E = Error> implements ITResult<Success, E> {
+    /**
+     * Gets the current state of the result.
+     * 
+     * @returns The state of the result, either Success or Error.
+     */
+    abstract state(): ResultState;
+    /**
+     * Matches the result with the provided matcher functions.
+     * 
+     * @param matcher - An object containing callback functions for success and error cases.
+     * @returns The result of applying the appropriate matcher function.
+     */
+    abstract match<Result>(matcher: ResultMatch<Success, E, Result>): Result;
+    /**
+     * Chains the result with another operation that returns a new result.
+     * 
+     * @param fn - A callback function that takes the success value and returns a new result.
+     * @returns A new result after applying the chained operation.
+     */
+    abstract andThen<NewSuccess>(fn: ChainedCallback<Success, NewSuccess, E>): ITResult<NewSuccess, E>;
+    /**
+     * Maps the success value to a new value.
+     * 
+     * @param fn - A callback function that takes the success value and returns a new success value.
+     * @returns A new result with the mapped success value.
+     */
+    abstract map<NewSuccess>(fn: SuccessMapCallback<Success, NewSuccess>): ITResult<NewSuccess, E>;
+    /**
+     * Maps the error value to a new value.
+     * 
+     * @param fn - A callback function that takes the error value and returns a new error value.
+     * @returns A new result with the mapped error value.
+     */
+    abstract mapError<NewError>(fn: ErrorMapCallback<E, NewError>): ITResult<Success, NewError>;
+    /**
+     * Retrieves the success value or throws an error if the result is an error.
+     * @throws The error value if the result is an error.
+     * @returns The success value if the result is a success.
+     */
+    abstract throwIfError(): Success;
+    /**
+     * Retrieves the success value or returns the provided default value if the result is an error.
+     * @param defaultValue The value to return if the result is an error.
+     * @returns The success value if the result is a success, otherwise the default value.
+     */
+    abstract unwrapOr(defaultValue: Success): Success;
+    /**
+     * Checks if the result is a success.
+     * 
+     * @returns True if the result is a success, false otherwise.
+     */
+    isSuccess(): boolean {
+        return this.state() === ResultState.Success;
+    }
+    /**
+     * Checks if the result is an error.
+     * 
+     * @returns True if the result is an error, false otherwise.
+     */
+    isError(): boolean {
+        return this.state() === ResultState.Error;
+    }
+}

package/src/decorators/ErrorPath.internal/functions.ts

@@ -0,0 +1,37 @@
+//type: functions
+//description: Functions to handle error path operations by executing a callback on errored results.
+import { ATresult } from "../../classes/abstracts/ATresult";
+import { applyMatch } from "../../functions/applyMatch";
+import { ErrorCallback } from "../../types/resultsCallbacks";
+
+/**
+ * Handles the error path for synchronous functions by executing a callback on errored results.
+ * @param this The context in which the original function is called.
+ * @param original The original function to be wrapped.
+ * @param path The error callback to be executed on errored results.
+ * @param args Arguments to be passed to the original function.
+ * @returns The result of the original function or the result of the error callback.
+ */
+export function errorPathSync(this: any, original: Function, path: ErrorCallback<any, any>, ...args: any[]): any {
+    const result = original.call(this, ...args);
+
+    return result instanceof ATresult 
+                        ? applyMatch(result, undefined, path)
+                        : result;
+}
+
+/**
+ * Handles the error path for asynchronous functions by executing a callback on errored results.
+ * @param this The context in which the original function is called.
+ * @param original The original function to be wrapped.
+ * @param path The error callback to be executed on errored results.
+ * @param args Arguments to be passed to the original function.
+ * @returns The result of the original function or the result of the error callback.
+ */
+export async function errorPathAsync(this: any, original: Function, path: ErrorCallback<any, any>, ...args: any[]): any {
+    const result = await original.call(this, ...args);
+
+    return result instanceof ATresult 
+                        ? applyMatch(result, undefined, path)
+                        : result;
+}

package/src/decorators/ErrorPath.ts

@@ -0,0 +1,28 @@
+//type: decorator
+//description: Decorator to handle error path operations by executing a callback on errored results.
+
+import { ErrorCallback } from "../types/resultsCallbacks";
+import { errorPathAsync, errorPathSync } from "./ErrorPath.internal/functions";
+
+/**
+ * Decorator to handle error path operations by executing a callback on errored results.
+ * @param fn Error path callback to be executed on errored results.
+ * @returns A method decorator that wraps the original method with error path handling.
+ */
+export function ErrorPath<T>(fn: ErrorCallback<T, void>) {
+    return function (target: any, key: string, descriptor: PropertyDescriptor) {
+        const original = descriptor.value;
+        const isAsync = original.constructor.name === "AsyncFunction";
+
+        if (isAsync) {
+            descriptor.value = async function (this: any, ...args: any[]) {
+                return await errorPathAsync.call(this, original, fn, ...args);
+            };
+        } else {
+            descriptor.value = function (this: any, ...args: any[]) {
+                return errorPathSync.call(this, original, fn, ...args);
+            };
+        }
+        return descriptor;
+    };
+}

package/src/decorators/HappyPath.internal/functions.ts

@@ -0,0 +1,37 @@
+//type: functions
+//description: Functions to handle happy path operations by executing a callback on successful results.
+import { ATresult } from "../../classes/abstracts/ATresult";
+import { applyMatch } from "../../functions/applyMatch";
+import { SuccessCallback } from "../../types/resultsCallbacks";
+
+/**
+ * Handles the happy path for synchronous functions by executing a callback on successful results.
+ * @param this The context in which the original function is called.
+ * @param original The original function to be wrapped.
+ * @param path The success callback to be executed on successful results.
+ * @param args Arguments to be passed to the original function.
+ * @returns The result of the original function or the result of the success callback.
+ */
+export function happyPathSync(this: any, original: Function, path: SuccessCallback<any, any>, ...args: any[]): any {
+    const result = original.call(this, ...args);
+
+    return result instanceof ATresult 
+                        ? applyMatch(result, path, undefined)
+                        : result;
+}
+
+/**
+ * Handles the happy path for asynchronous functions by executing a callback on successful results.
+ * @param this The context in which the original function is called.
+ * @param original The original function to be wrapped.
+ * @param path The success callback to be executed on successful results.
+ * @param args Arguments to be passed to the original function.
+ * @returns The result of the original function or the result of the success callback.
+ */
+export async function happyPathASync(this: any, original: Function, path: SuccessCallback<any, any>, ...args: any[]): any {
+    const result = await original.call(this, ...args);
+
+    return result instanceof ATresult 
+                        ? applyMatch(result, path, undefined)
+                        : result;
+}

package/src/decorators/HappyPath.ts

@@ -0,0 +1,28 @@
+//type: decorator
+//description: Decorator to handle happy path operations by executing a callback on successful results.
+
+import { SuccessCallback } from "../types/resultsCallbacks";
+import { happyPathASync, happyPathSync } from "./HappyPath.internal/functions";
+
+/**
+ * Decorator to handle happy path operations by executing a callback on successful results.
+ * @param fn Happy path callback to be executed on successful results.
+ * @returns A method decorator that wraps the original method with happy path handling.
+ */
+export function HappyPath<T>(fn: SuccessCallback<T, void>) {
+    return function (target: any, key: string, descriptor: PropertyDescriptor) {
+        const original = descriptor.value;
+        const isAsync = original.constructor.name === "AsyncFunction";
+
+        if (isAsync) {
+            descriptor.value = async function (this: any, ...args: any[]) {
+                return await happyPathASync.call(this, original, fn, ...args);
+            };
+        } else {
+            descriptor.value = function (this: any, ...args: any[]) {
+                return happyPathSync.call(this, original, fn, ...args);
+            };
+        }
+        return descriptor;
+    };
+}

package/src/decorators/Risky.internal/functions.ts

@@ -0,0 +1,40 @@
+// type: functions
+// description: Functions to handle risky operations by converting exceptions into Result types.
+
+import { ATresult } from "../../classes/abstracts/ATresult";
+import { Fail } from "../../classes/Fail";
+import { Success } from "../../classes/Success";
+
+/**
+ * Handles synchronous risky operations by converting exceptions into Result types.
+ * @param this The context in which the original function is called.
+ * @param original The original function to be executed.
+ * @param args Arguments to be passed to the original function.
+ * @returns An ATresult representing success or failure.
+ */
+export function riskySync(this: any, original: Function, ...args: any[]): ATresult<any> {
+    try {
+        const result = original.apply(this, args);
+
+        return result instanceof ATresult ? result : Success.Create(result);
+    } catch (error) {
+        return error instanceof ATresult ? error : Fail.Create(error as Error);
+    }
+}
+
+/**
+ * Handles asynchronous risky operations by converting exceptions into Result types.
+ * @param this The context in which the original function is called.
+ * @param original The original function to be executed.
+ * @param args Arguments to be passed to the original function.
+ * @returns A Promise that resolves to an ATresult representing success or failure.
+ */
+export async function riskyAsync(this: any, original: Function, ...args: any[]): Promise<ATresult<any>> {
+    try {
+        const result = await original.apply(this, args);
+
+        return result instanceof ATresult ? result : Success.Create(result);
+    } catch (error) {
+        return error instanceof ATresult ? error : Fail.Create(error as Error);
+    }
+}

package/src/decorators/Risky.ts

@@ -0,0 +1,27 @@
+// type: decorator
+// description: Decorator to handle risky operations by converting exceptions into Result types.
+import { riskyAsync, riskySync } from "./Risky.internal/functions";
+
+/**
+ * Decorator to handle risky operations by converting exceptions into Result types.
+ * @returns A method decorator that wraps the original method with error handling.
+ */
+export function Risky() {
+    return function (target: any, key: string, descriptor: PropertyDescriptor) {
+        const original = descriptor.value;
+
+        const isAsync = original.constructor.name === "AsyncFunction";
+
+        if (isAsync) {
+            descriptor.value = async function (this: any, ...args: any[]) {
+                return riskyAsync.call(this, original, ...args);
+            };
+        } else {
+            descriptor.value = function (this: any, ...args: any[]) {
+                return riskySync.call(this, original, ...args);
+            };
+        }
+
+        return descriptor;
+    }
+}

package/src/functions/applyMatch.ts

@@ -0,0 +1,29 @@
+//type: function
+//description: Function to apply match on a result with optional callbacks.
+
+import { ATresult } from "../classes/abstracts/ATresult";
+import { SuccessCallback, ErrorCallback } from "../types/resultsCallbacks";
+
+/**
+ * Applies match on the given result with optional success and error callbacks.
+ * @param result Result to apply match on.
+ * @param onSuccess Additional callback for success case.
+ * @param onError Additional callback for error case.
+ * @returns Returns the original result after applying the match.
+ */
+export function applyMatch(
+    result: ATresult<any>, 
+    onSuccess?: SuccessCallback<any, any>, 
+    onError?: ErrorCallback<any, any>
+): ATresult<any> {
+    return result.match({
+        Ok: (val) => {
+            if (onSuccess) onSuccess(val);
+            return result;
+        },
+        Err: (err) => {
+            if (onError) onError(err);
+            return result;
+        }
+    });
+}

package/src/interfaces/ITResult.ts

@@ -0,0 +1,86 @@
+// type: interface
+// description: Interface for a result type that can represent either a success or an error.
+
+import { ResultMatch } from "../types/ResultMatch";
+import { ChainedCallback, ErrorMapCallback, SuccessMapCallback } from "../types/resultsCallbacks";
+
+/**
+ * Enumeration representing the state of the result.
+ */
+export enum ResultState {
+    /**
+     * The result represents a successful outcome.
+     */
+    Success, 
+    /**
+     * The result represents an error outcome.
+     */
+    Error
+}
+
+/**
+ * Interface representing a result that can be either a success or an error.
+ * 
+ * @template Success - The type of the success value.
+ * @template Error - The type of the error value.
+ */
+export declare interface ITResult<Success, Error> {
+    /**
+     * Gets the current state of the result.
+     * 
+     * @returns The state of the result, either Success or Error.
+     */
+    state(): ResultState;
+    /**
+     * Checks if the result is a success.
+     * 
+     * @returns True if the result is a success, false otherwise.
+     */
+    isSuccess(): boolean;
+    /**
+     * Checks if the result is an error.
+     * 
+     * @returns True if the result is an error, false otherwise.
+     */
+    isError(): boolean;
+    /**
+     * Matches the result with the provided matcher functions.
+     * 
+     * @param matcher An object containing functions to handle success and error cases.
+     * @returns The result of applying the appropriate matcher function.
+     */
+    match<Result>(matcher: ResultMatch<Success, Error, Result>): Result;
+    /**
+     * Chains another result-producing function to be executed if this result is a success.
+     * 
+     * @param fn A function that takes the success value and returns a new result.
+     * @returns The new result produced by the function, or the current error result.
+     */
+    andThen<NewSuccess>(fn: ChainedCallback<Success, NewSuccess, Error>): ITResult<NewSuccess, Error>;
+    /**
+     * Transforms the success value using the provided function.
+     * 
+     * @param fn A function that takes the success value and returns a new success value.
+     * @returns A new result with the transformed success value, or the current error result.
+     */
+    map<NewSuccess>(fn: SuccessMapCallback<Success, NewSuccess>): ITResult<NewSuccess, Error>;
+    /**
+     * Transforms the error value using the provided function.
+     * 
+     * @param fn A function that takes the error value and returns a new error value.
+     * @returns A new result with the transformed error value, or the current success result.
+     */
+    mapError<NewError>(fn: ErrorMapCallback<Error, NewError>): ITResult<Success, NewError>;
+    /**
+     * Retrieves the success value or throws an error if the result is an error.
+     * @throws The error value if the result is an error.
+     * @returns The success value if the result is a success.
+     */
+    throwIfError(): Success;
+    /**
+     * Retrieves the success value or returns the provided default value if the result is an error.
+     * @param defaultValue The value to return if the result is an error.
+     * @returns The success value if the result is a success, otherwise the default value.
+     */
+    unwrapOr(defaultValue: Success): Success;
+}

package/src/types/ResultMatch.ts

@@ -0,0 +1,23 @@
+// type: type
+// description: Type representing the matcher functions for a result type.
+
+import { ErrorCallback, SuccessCallback } from "./resultsCallbacks";
+
+/**
+ * Type representing the matcher functions for a result type.
+ * 
+ * @template Success - The type of the success value.
+ * @template Error - The type of the error value.
+ * @template Result - The type of the result produced by the matcher functions.
+ */
+export type ResultMatch<Success, Error, Result> = {
+    /**
+     * Callback function to handle the success case.
+     */
+    Ok: SuccessCallback<Success, Result>;
+    /**
+     * Callback function to handle the error case.
+     */
+    Err: ErrorCallback<Error, Result>;
+}
+

package/src/types/resultsCallbacks.ts

@@ -0,0 +1,41 @@
+// type: types
+// description: Callback types for handling results in a functional way.
+
+import { ITResult } from "../interfaces/ITResult";
+
+/**
+ * Callback type for handling success values.
+ * 
+ * @template Success - The type of the success value.
+ * @template Result - The type of the result produced by the callback.
+ */
+export declare type SuccessCallback<Success, Result> = (value: Success) => Result;
+/**
+ * Callback type for handling error values.
+ * 
+ * @template Error - The type of the error value.
+ * @template Result - The type of the result produced by the callback.
+ */
+export declare type ErrorCallback<Error, Result> = (error: Error) => Result;
+/**
+ * Callback type for chaining result-producing functions.
+ * 
+ * @template Success - The type of the success value.
+ * @template NewSuccess - The type of the new success value produced by the chained function.
+ * @template Error - The type of the error value.
+ */
+export declare type ChainedCallback<Success, NewSuccess, Error> = (value: Success) => ITResult<NewSuccess, Error>;
+/**
+ * Callback type for transforming success values.
+ * 
+ * @template Success - The type of the success value.
+ * @template NewSuccess - The type of the new success value after transformation.
+ */
+export declare type SuccessMapCallback<Success, NewSuccess> = (value: Success) => NewSuccess
+/**
+ * Callback type for transforming error values.
+ * 
+ * @template Error - The type of the error value.
+ * @template NewError - The type of the new error value after transformation.
+ */
+export declare type ErrorMapCallback<Error, NewError> = (value: Error) => NewError