@clipboard-health/util-ts 2.8.7 → 2.9.0

package/src/lib/errors/serviceError.js

@@ -0,0 +1,180 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServiceError = exports.ERROR_CODES = void 0;
+const node_crypto_1 = require("node:crypto");
+const deepFreeze_1 = require("../deepFreeze");
+const isDefined_1 = require("../nullish/isDefined");
+const toError_1 = require("./toError");
+/**
+ * Standard error codes used across microservices.
+ */
+exports.ERROR_CODES = {
+    badRequest: "badRequest",
+    unauthorized: "unauthorized",
+    forbidden: "forbidden",
+    notFound: "notFound",
+    conflict: "conflict",
+    unprocessableEntity: "unprocessableEntity",
+    tooManyRequests: "tooManyRequests",
+    internal: "internal",
+};
+const ERROR_METADATA = {
+    badRequest: {
+        status: 400,
+        title: "Invalid or malformed request",
+    },
+    unauthorized: {
+        status: 401,
+        title: "Invalid or missing credentials",
+    },
+    forbidden: {
+        status: 403,
+        title: "Access to resource denied",
+    },
+    notFound: {
+        status: 404,
+        title: "Resource not found",
+    },
+    conflict: {
+        status: 409,
+        title: "Conflict with server state",
+    },
+    unprocessableEntity: {
+        status: 422,
+        title: "Request failed validation",
+    },
+    tooManyRequests: {
+        status: 429,
+        title: "Request limit exceeded",
+    },
+    internal: {
+        status: 500,
+        title: "Internal server error",
+    },
+};
+function isZodLike(value) {
+    const zodLike = value;
+    return ((0, isDefined_1.isDefined)(zodLike) &&
+        "issues" in zodLike &&
+        Array.isArray(zodLike.issues) &&
+        zodLike.issues.every((issue) => typeof issue === "object" &&
+            (0, isDefined_1.isDefined)(issue) &&
+            "path" in issue &&
+            Array.isArray(issue.path)));
+}
+/**
+ * Error class for service-level errors, convertible to JSON:API errors.
+ */
+class ServiceError extends Error {
+    /**
+     * Converts an error to a `ServiceError`.
+     *
+     * @param value - The value to convert, which can be any type
+     * @returns If the value is already a `ServiceError`, returns it unchanged. Otherwise, convert it
+     *          to a `ServiceError`.
+     */
+    static fromError(value) {
+        if (value instanceof ServiceError) {
+            return value;
+        }
+        const error = (0, toError_1.toError)(value);
+        return new ServiceError({
+            issues: [{ code: exports.ERROR_CODES.internal, message: error.message }],
+            cause: error,
+        });
+    }
+    /**
+     * Converts a Zod-like error to a `ServiceError`.
+     *
+     * @param value - An object with a Zod-like error structure containing issues
+     * @returns The converted `ServiceError`
+     * @throws {ServiceError} If the provided value does not match the expected Zod-like structure
+     */
+    static fromZodLike(value) {
+        if (!isZodLike(value)) {
+            throw new ServiceError({
+                issues: [{ code: exports.ERROR_CODES.internal, message: "Invalid ZodLike" }],
+                cause: value,
+            });
+        }
+        return new ServiceError({
+            issues: value.issues.map((issue) => ({
+                code: exports.ERROR_CODES.unprocessableEntity,
+                message: issue.message,
+                path: issue.path,
+            })),
+            cause: value,
+        });
+    }
+    id;
+    issues;
+    /**
+     * Creates a new `ServiceError`
+     * @param parameters - Issues contributing to the error or a message string
+     */
+    constructor(parameters) {
+        const params = typeof parameters === "string"
+            ? { issues: [toIssue({ message: parameters })] }
+            : { ...parameters, issues: parameters.issues.map(toIssue) };
+        super(createServiceErrorMessage(params.issues));
+        this.id = (0, node_crypto_1.randomUUID)();
+        this.issues = (0, deepFreeze_1.deepFreeze)(params.issues);
+        this.cause = "cause" in params ? params.cause : undefined;
+        this.name = this.constructor.name;
+        /**
+         * Maintain proper prototype chain in transpiled code
+         * @see {@link https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-2.html#support-for-newtarget}
+         */
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+    /**
+     * Return string representation of the error for logging.
+     */
+    toString() {
+        const cause = this.cause ? `; [cause]: ${(0, toError_1.toError)(this.cause).toString()}` : "";
+        return `${this.name}[${this.id}]: ${this.message}${cause}`;
+    }
+    /**
+     * Converts the error to JSON:API format
+     * @see {@link https://jsonapi.org/format/#error-objects}
+     * @returns Object conforming to JSON:API error format
+     */
+    toJsonApi() {
+        return {
+            errors: this.issues.map((issue) => ({
+                id: this.id,
+                status: String(ERROR_METADATA[issue.code].status),
+                code: issue.code,
+                title: issue.title,
+                ...(issue.message && { detail: issue.message }),
+                ...(issue.path && {
+                    source: {
+                        pointer: `/${issue.path.join("/")}`,
+                    },
+                }),
+            })),
+        };
+    }
+}
+exports.ServiceError = ServiceError;
+/**
+ * Creates a human-readable error message from an array of service issues
+ * @param issues - Array of issues to include in the message
+ * @returns Message string in format "[code1]: detail1; [code2]: detail2"
+ */
+function createServiceErrorMessage(issues) {
+    if (issues.length === 0) {
+        return "[unknown]";
+    }
+    return issues
+        .map((issue) => {
+        const message = issue.message ? `: ${issue.message}` : "";
+        return `[${issue.code}]${message}`;
+    })
+        .join("; ");
+}
+function toIssue(issue) {
+    const code = issue.code ?? exports.ERROR_CODES.internal;
+    return { ...issue, code, title: ERROR_METADATA[code].title };
+}
+//# sourceMappingURL=serviceError.js.map

package/src/lib/errors/serviceError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serviceError.js","sourceRoot":"","sources":["../../../../../../packages/util-ts/src/lib/errors/serviceError.ts"],"names":[],"mappings":"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"}

package/src/lib/errors/toError.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Converts an error-like value to an Error instance. If the input is already an Error, returns it
+ * directly. Otherwise, creates a new Error with an appropriate string representation of the input.
+ *
+ * @param value - The value to convert.
+ * @returns An Error instance containing a string representation of the input
+ */
+export declare function toError(value: unknown): Error;

package/src/lib/errors/toError.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toError = toError;
+const isString_1 = require("../strings/isString");
+const stringify_1 = require("../strings/stringify");
+const isError_1 = require("./isError");
+/**
+ * Converts an error-like value to an Error instance. If the input is already an Error, returns it
+ * directly. Otherwise, creates a new Error with an appropriate string representation of the input.
+ *
+ * @param value - The value to convert.
+ * @returns An Error instance containing a string representation of the input
+ */
+function toError(value) {
+    if ((0, isError_1.isError)(value)) {
+        return value;
+    }
+    if (value && typeof value === "object" && "message" in value) {
+        const error = new Error(String(value.message));
+        if ("stack" in value) {
+            error.stack = String(value.stack);
+        }
+        return error;
+    }
+    if (typeof value === "symbol") {
+        return new Error(String(value));
+    }
+    try {
+        return new Error((0, isString_1.isString)(value) ? value : (0, stringify_1.stringify)(value));
+    }
+    catch {
+        return new Error(String(value));
+    }
+}
+//# sourceMappingURL=toError.js.map

package/src/lib/errors/toError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toError.js","sourceRoot":"","sources":["../../../../../../packages/util-ts/src/lib/errors/toError.ts"],"names":[],"mappings":";;AAWA,0BAuBC;AAlCD,kDAA+C;AAC/C,oDAAiD;AACjD,uCAAoC;AAEpC;;;;;;GAMG;AACH,SAAgB,OAAO,CAAC,KAAc;IACpC,IAAI,IAAA,iBAAO,EAAC,KAAK,CAAC,EAAE,CAAC;QACnB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,SAAS,IAAI,KAAK,EAAE,CAAC;QAC7D,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QAC/C,IAAI,OAAO,IAAI,KAAK,EAAE,CAAC;YACrB,KAAK,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACpC,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAClC,CAAC;IAED,IAAI,CAAC;QACH,OAAO,IAAI,KAAK,CAAC,IAAA,mBAAQ,EAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAA,qBAAS,EAAC,KAAK,CAAC,CAAC,CAAC;IAC/D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAClC,CAAC;AACH,CAAC"}

package/src/lib/errors/toErrorMessage.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Converts any value to an Error instance and returns the message.
+ *
+ * @param value - The value to convert.
+ * @returns The Error instance's message field.
+ */
+export declare function toErrorMessage(value: unknown): string;

package/src/lib/errors/toErrorMessage.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toErrorMessage = toErrorMessage;
+const toError_1 = require("./toError");
+/**
+ * Converts any value to an Error instance and returns the message.
+ *
+ * @param value - The value to convert.
+ * @returns The Error instance's message field.
+ */
+function toErrorMessage(value) {
+    return (0, toError_1.toError)(value).message;
+}
+//# sourceMappingURL=toErrorMessage.js.map

package/src/lib/errors/toErrorMessage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toErrorMessage.js","sourceRoot":"","sources":["../../../../../../packages/util-ts/src/lib/errors/toErrorMessage.ts"],"names":[],"mappings":";;AAQA,wCAEC;AAVD,uCAAoC;AAEpC;;;;;GAKG;AACH,SAAgB,cAAc,CAAC,KAAc;IAC3C,OAAO,IAAA,iBAAO,EAAC,KAAK,CAAC,CAAC,OAAO,CAAC;AAChC,CAAC"}

package/src/lib/{force-cast.d.ts → forceCast.d.ts}

@@ -1,5 +1,6 @@
 /**
  * Force cast to the provided type.
+ *
+ * @deprecated Use type guards instead.
  */
 export declare function forceCast<T>(value: unknown): T;
-//# sourceMappingURL=force-cast.d.ts.map

package/src/lib/{force-cast.js → forceCast.js}

@@ -3,8 +3,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.forceCast = forceCast;
 /**
  * Force cast to the provided type.
+ *
+ * @deprecated Use type guards instead.
  */
 function forceCast(value) {
     return value;
 }
-//# sourceMappingURL=force-cast.js.map
+//# sourceMappingURL=forceCast.js.map

package/src/lib/forceCast.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"forceCast.js","sourceRoot":"","sources":["../../../../../packages/util-ts/src/lib/forceCast.ts"],"names":[],"mappings":";;AAKA,8BAEC;AAPD;;;;GAIG;AACH,SAAgB,SAAS,CAAI,KAAc;IACzC,OAAO,KAAU,CAAC;AACpB,CAAC"}

package/src/lib/functional/cbhResponse.d.ts

@@ -0,0 +1,23 @@
+import { type Arrayable } from "type-fest";
+import { CbhError, type CbhIssue } from "../errors/cbhError";
+export type CbhResponse<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: CbhError;
+};
+/**
+ * @deprecated Use {@link failure} instead.
+ */
+export declare function toErrorCbhResponse(issues: Arrayable<CbhIssue>): {
+    success: false;
+    error: CbhError;
+};
+/**
+ * @deprecated Use {@link success} instead.
+ */
+export declare function toSuccessCbhResponse<T>(data: T): {
+    success: true;
+    data: T;
+};

package/src/lib/{cbh-response.js → functional/cbhResponse.js}

@@ -2,11 +2,17 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toErrorCbhResponse = toErrorCbhResponse;
 exports.toSuccessCbhResponse = toSuccessCbhResponse;
-const cbh_error_1 = require("./cbh-error");
+const cbhError_1 = require("../errors/cbhError");
+/**
+ * @deprecated Use {@link failure} instead.
+ */
 function toErrorCbhResponse(issues) {
-    return { success: false, error: new cbh_error_1.CbhError(issues) };
+    return { success: false, error: new cbhError_1.CbhError(issues) };
 }
+/**
+ * @deprecated Use {@link success} instead.
+ */
 function toSuccessCbhResponse(data) {
     return { success: true, data };
 }
-//# sourceMappingURL=cbh-response.js.map
+//# sourceMappingURL=cbhResponse.js.map

package/src/lib/functional/cbhResponse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cbhResponse.js","sourceRoot":"","sources":["../../../../../../packages/util-ts/src/lib/functional/cbhResponse.ts"],"names":[],"mappings":";;AASA,gDAKC;AAKD,oDAEC;AAnBD,iDAA6D;AAI7D;;GAEG;AACH,SAAgB,kBAAkB,CAAC,MAA2B;IAI5D,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,mBAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;AACzD,CAAC;AAED;;GAEG;AACH,SAAgB,oBAAoB,CAAI,IAAO;IAC7C,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AACjC,CAAC"}

package/src/lib/functional/either.d.ts

@@ -0,0 +1,86 @@
+export type Left<E> = Readonly<{
+    isRight: false;
+    left: E;
+}>;
+export type Right<A> = Readonly<{
+    isRight: true;
+    right: A;
+}>;
+/**
+ * A value of `Either` type `Left<E>` or type `Right<A>`; a disjoint union.
+ *
+ * A common use case is as an alternative to {@link Option} where `Left<E>` contains useful
+ * information. Convention dictates that `Left<E>` is used for failure and `Right<A>` for success.
+ * To help remember, the success case is "right"; it's the result you want.
+ *
+ * @includeExample ./packages/util-ts/examples/either.ts
+ * @see [Usage example](../../util-ts/examples/either.ts)
+ */
+export type Either<E, A> = Left<E> | Right<A>;
+/**
+ * Constructs an `Either` holding a `Left<E>` value, usually representing a failure.
+ *
+ * @param left - The value to wrap in a `Left`
+ * @returns A `Left` containing the value
+ */
+export declare function left<E, A = never>(left: E): Either<E, A>;
+/**
+ * Constructs an `Either` holding a `Right<A>`, representing a success.
+ *
+ * @param value - The value to wrap in a `Right`
+ * @returns A `Right` containing the value
+ */
+export declare function right<A, E = never>(right: A): Either<E, A>;
+/**
+ * Type guard that checks if an either is `Left<E>`.
+ *
+ * @param either - The `Either` to check
+ * @returns `true` if the `Either` is `Left<E>`, `false` if it is `Right<A>`
+ */
+export declare function isLeft<E, A>(either: Either<E, A>): either is Left<E>;
+/**
+ * Type guard that checks if an either is `Right<A>`.
+ *
+ * @param either - The `Either` to check
+ * @returns `true` if the `Either` is `Right<A>`, `false` if it is `Left<E>`
+ */
+export declare function isRight<E, A>(either: Either<E, A>): either is Right<A>;
+/**
+ * Transforms the value inside an `Either` using the provided function. If the `Either` is
+ * `Right(value)`, returns `Right(f(value))`. If the `Either` is `Left(value)`, returns
+ * `Left(value)`.
+ *
+ * @param f - The function to apply to the `Right` value
+ * @returns A function that transforms `Either<E, A>` to `Either<E, B>`
+ */
+export declare function map<A, B>(f: (right: A) => B): <E>(either: Either<E, A>) => Either<E, B>;
+/**
+ * Transforms the value inside an `Either` using the provided function. If the `Either` is
+ * `Left(value)`, returns `Left(f(value))`. If the `Either` is `Right(value)`, returns
+ * `Right(value)`.
+ */
+export declare function mapLeft<E, G>(f: (left: E) => G): <A>(either: Either<E, A>) => Either<G, A>;
+/**
+ * Chains `Either` operations that return `Either`s. Unlike `map` which wraps the result in a new
+ * `Either`, `flatMap` prevents nested `Either`s like `Right(Right(value))`.
+ *
+ * @param f - A function that returns an `Either`
+ * @returns The `Either` returned by the function if the input is `Right`, `Left` otherwise
+ */
+export declare function flatMap<E, A, B>(f: (right: A) => Either<E, B>): (either: Either<E, A>) => Either<E, B>;
+/**
+ * Safely extracts the value from an `Either` with a fallback. Use this function when you need to
+ * convert an `Either<E, A>` to an `A`, providing a default value for the `Left` case.
+ *
+ * @param defaultValue - The value to return if the `Either` is `Left`
+ * @returns The contained value if `Right`, `defaultValue` if `Left`
+ */
+export declare function getOrElse<E, A>(onLeft: (left: E) => A): (either: Either<E, A>) => A;
+/**
+ * Pattern matches on an `Either`, handling both `Right` and `Left` cases.
+ *
+ * @param onLeft - Function to handle the `Left` case
+ * @param onRight - Function to handle the `Right` case
+ * @returns The result of `Either` `onLeft` or `onRight` based on the `Either` state
+ */
+export declare function match<E, A, B>(onLeft: (left: E) => B, onRight: (right: A) => B): (either: Either<E, A>) => B;

package/src/lib/functional/either.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.left = left;
+exports.right = right;
+exports.isLeft = isLeft;
+exports.isRight = isRight;
+exports.map = map;
+exports.mapLeft = mapLeft;
+exports.flatMap = flatMap;
+exports.getOrElse = getOrElse;
+exports.match = match;
+/**
+ * Constructs an `Either` holding a `Left<E>` value, usually representing a failure.
+ *
+ * @param left - The value to wrap in a `Left`
+ * @returns A `Left` containing the value
+ */
+function left(left) {
+    return { isRight: false, left };
+}
+/**
+ * Constructs an `Either` holding a `Right<A>`, representing a success.
+ *
+ * @param value - The value to wrap in a `Right`
+ * @returns A `Right` containing the value
+ */
+function right(right) {
+    return { isRight: true, right };
+}
+/**
+ * Type guard that checks if an either is `Left<E>`.
+ *
+ * @param either - The `Either` to check
+ * @returns `true` if the `Either` is `Left<E>`, `false` if it is `Right<A>`
+ */
+function isLeft(either) {
+    return !either.isRight;
+}
+/**
+ * Type guard that checks if an either is `Right<A>`.
+ *
+ * @param either - The `Either` to check
+ * @returns `true` if the `Either` is `Right<A>`, `false` if it is `Left<E>`
+ */
+function isRight(either) {
+    return either.isRight;
+}
+/**
+ * Transforms the value inside an `Either` using the provided function. If the `Either` is
+ * `Right(value)`, returns `Right(f(value))`. If the `Either` is `Left(value)`, returns
+ * `Left(value)`.
+ *
+ * @param f - The function to apply to the `Right` value
+ * @returns A function that transforms `Either<E, A>` to `Either<E, B>`
+ */
+function map(f) {
+    return (either) => (isRight(either) ? right(f(either.right)) : either);
+}
+/**
+ * Transforms the value inside an `Either` using the provided function. If the `Either` is
+ * `Left(value)`, returns `Left(f(value))`. If the `Either` is `Right(value)`, returns
+ * `Right(value)`.
+ */
+function mapLeft(f) {
+    return (either) => (isLeft(either) ? left(f(either.left)) : either);
+}
+/**
+ * Chains `Either` operations that return `Either`s. Unlike `map` which wraps the result in a new
+ * `Either`, `flatMap` prevents nested `Either`s like `Right(Right(value))`.
+ *
+ * @param f - A function that returns an `Either`
+ * @returns The `Either` returned by the function if the input is `Right`, `Left` otherwise
+ */
+function flatMap(f) {
+    return (either) => (isRight(either) ? f(either.right) : either);
+}
+/**
+ * Safely extracts the value from an `Either` with a fallback. Use this function when you need to
+ * convert an `Either<E, A>` to an `A`, providing a default value for the `Left` case.
+ *
+ * @param defaultValue - The value to return if the `Either` is `Left`
+ * @returns The contained value if `Right`, `defaultValue` if `Left`
+ */
+function getOrElse(onLeft) {
+    return (either) => (isRight(either) ? either.right : onLeft(either.left));
+}
+/**
+ * Pattern matches on an `Either`, handling both `Right` and `Left` cases.
+ *
+ * @param onLeft - Function to handle the `Left` case
+ * @param onRight - Function to handle the `Right` case
+ * @returns The result of `Either` `onLeft` or `onRight` based on the `Either` state
+ */
+function match(onLeft, onRight) {
+    return (either) => (isRight(either) ? onRight(either.right) : onLeft(either.left));
+}
+//# sourceMappingURL=either.js.map

package/src/lib/functional/either.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"either.js","sourceRoot":"","sources":["../../../../../../packages/util-ts/src/lib/functional/either.ts"],"names":[],"mappings":";;AA4BA,oBAEC;AAQD,sBAEC;AAQD,wBAEC;AAQD,0BAEC;AAUD,kBAEC;AAOD,0BAEC;AASD,0BAIC;AASD,8BAEC;AASD,sBAKC;AAjGD;;;;;GAKG;AACH,SAAgB,IAAI,CAAe,IAAO;IACxC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AAClC,CAAC;AAED;;;;;GAKG;AACH,SAAgB,KAAK,CAAe,KAAQ;IAC1C,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AAClC,CAAC;AAED;;;;;GAKG;AACH,SAAgB,MAAM,CAAO,MAAoB;IAC/C,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC;AACzB,CAAC;AAED;;;;;GAKG;AACH,SAAgB,OAAO,CAAO,MAAoB;IAChD,OAAO,MAAM,CAAC,OAAO,CAAC;AACxB,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,GAAG,CAAO,CAAkB;IAC1C,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;AACzE,CAAC;AAED;;;;GAIG;AACH,SAAgB,OAAO,CAAO,CAAiB;IAC7C,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;AACtE,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,OAAO,CACrB,CAA6B;IAE7B,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;AAClE,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,SAAS,CAAO,MAAsB;IACpD,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;AAC5E,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,KAAK,CACnB,MAAsB,EACtB,OAAwB;IAExB,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;AACrF,CAAC"}

package/src/lib/functional/option.d.ts

@@ -0,0 +1,71 @@
+export type None = Readonly<{
+    isSome: false;
+}>;
+export type Some<A> = Readonly<{
+    isSome: true;
+    value: A;
+}>;
+/**
+ * An optional value. If the value exists, it's of type `Some<A>`, otherwise it's of type `None`.
+ *
+ * @includeExample ./packages/util-ts/examples/option.ts
+ * @see [Usage example](../../util-ts/examples/option.ts)
+ */
+export type Option<A> = None | Some<A>;
+/**
+ * Constructs an `Option` of `None`, representing a missing value.
+ */
+export declare const none: None;
+/**
+ * Constructs an `Option` holding a `Some<A>`, representing an optional value that exists.
+ *
+ * @param value - The value to wrap in a `Some`
+ * @returns A `Some` containing the value
+ */
+export declare function some<A>(value: A): Some<A>;
+/**
+ * Type guard that checks if an `Option` is `None`.
+ *
+ * @param option - The `Option` to check
+ * @returns `true` if the `Option` is `None`, `false` if it is `Some<A>`
+ */
+export declare function isNone<A>(option: Option<A>): option is None;
+/**
+ * Type guard that checks if an `Option` is `Some<A>`.
+ *
+ * @param option - The `Option` to check
+ * @returns `true` if the `Option` is `Some<A>`, `false` if it is `None`
+ */
+export declare function isSome<A>(option: Option<A>): option is Some<A>;
+/**
+ * Transforms the value inside an `Option` using the provided function. If the `Option` is
+ * `Some(value)`, returns `Some(f(value))`. If the `Option` is `None`, returns `None`.
+ *
+ * @param f - The function to apply to the value if it exists
+ * @returns A new `Option` containing the transformed value
+ */
+export declare function map<A, B>(f: (a: A) => B): (option: Option<A>) => Option<B>;
+/**
+ * Chains `Option` operations that return `Option`s. Unlike `map` which wraps the result in a new
+ * `Option`, `flatMap` prevents nested `Option`s like `Some(Some(value))`.
+ *
+ * @param f - A function that returns an `Option`
+ * @returns The `Option` returned by the function if the input is `Some`, `None` otherwise
+ */
+export declare function flatMap<A, B>(f: (a: A) => Option<B>): (option: Option<A>) => Option<B>;
+/**
+ * Safely extracts the value from an `Option` with a fallback. Use this function when you need to
+ * convert an `Option<A>` to an `A`, providing a default value for the `None` case.
+ *
+ * @param defaultValue - The value to return if the `Option` is `None`
+ * @returns The contained value if `Some`, `defaultValue` if `None`
+ */
+export declare function getOrElse<A>(defaultValue: A): (option: Option<A>) => A;
+/**
+ * Pattern matches on an `Option`, handling both `Some` and `None` cases.
+ *
+ * @param onNone - Function to handle the `None` case
+ * @param onSome - Function to handle the `Some` case
+ * @returns The result of either `onNone` or `onSome` based on the `Option` state
+ */
+export declare function match<A, B>(onNone: () => B, onSome: (value: A) => B): (option: Option<A>) => B;