@praha/byethrow 0.0.1

package/dist/cjs/functions/try.d.ts

@@ -0,0 +1,84 @@
+import type { Result, ResultAsync } from '../result';
+/**
+ * Wraps a function execution (sync or async) in a {@link Result} or {@link ResultAsync} type,
+ * capturing errors and returning them in a structured way.
+ *
+ * You can use either a custom `catch` handler or rely on the `safe: true` option
+ * to assume the function cannot throw.
+ *
+ * @function
+ * @typeParam T - The function type to execute (sync or async).
+ * @typeParam E - The error type to return if `catch` is used.
+ *
+ * @example Sync Try-Catch
+ * ```ts
+ * import { Result } from '@praha/byethrow';
+ *
+ * const fn = Result.try({
+ *   try: (x: number) => {
+ *     if (x < 0) throw new Error('Negative!');
+ *     return x * 2;
+ *   },
+ *   catch: (error) => new Error('Oops!', { cause: error }),
+ * });
+ *
+ * const result = fn(5); // Result.Result<number, Error>
+ * ```
+ *
+ * @example Sync Safe
+ * ```ts
+ * import { Result } from '@praha/byethrow';
+ *
+ * const fn = Result.try({
+ *   safe: true,
+ *   try: (x: number) => x + 1,
+ * });
+ *
+ * const result = fn(1); // Result.Result<number, never>
+ * ```
+ *
+ * @example Async Try-Catch
+ * ```ts
+ * import { Result } from '@praha/byethrow';
+ *
+ * const fn = Result.try({
+ *   try: async (id: string) => await fetch(`/api/data/${id}`),
+ *   catch: (error) => new Error('Oops!', { cause: error }),
+ * });
+ *
+ * const result = await fn('abc'); // Result.ResultAsync<Response, Error>
+ * ```
+ *
+ * @example Async Safe
+ * ```ts
+ * import { Result } from '@praha/byethrow';
+ *
+ * const fn = Result.try({
+ *   safe: true,
+ *   try: async () => await Promise.resolve('ok'),
+ * });
+ *
+ * const result = await fn(); // Result.ResultAsync<string, never>
+ * ```
+ *
+ * @category Creators
+ */
+declare const try_: {
+    <T extends (...args: readonly any[]) => Promise<any>, E>(options: {
+        try: T;
+        catch: (error: unknown) => E;
+    }): (...args: Parameters<T>) => ResultAsync<Awaited<ReturnType<T>>, E>;
+    <T extends (...args: readonly any[]) => Promise<any>>(options: {
+        try: T;
+        safe: true;
+    }): (...args: Parameters<T>) => ResultAsync<Awaited<ReturnType<T>>, never>;
+    <T extends (...args: readonly any[]) => any, E>(options: {
+        try: T;
+        catch: (error: unknown) => E;
+    }): (...args: Parameters<T>) => Result<ReturnType<T>, E>;
+    <T extends (...args: readonly any[]) => any>(options: {
+        try: T;
+        safe: true;
+    }): (...args: Parameters<T>) => Result<ReturnType<T>, never>;
+};
+export { try_ as try };

package/dist/cjs/functions/unwrap-error.cjs

@@ -0,0 +1,40 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.d = (exports1, definition)=>{
+        for(var key in definition)if (__webpack_require__.o(definition, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
+            enumerable: true,
+            get: definition[key]
+        });
+    };
+})();
+(()=>{
+    __webpack_require__.o = (obj, prop)=>Object.prototype.hasOwnProperty.call(obj, prop);
+})();
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ('undefined' != typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+__webpack_require__.d(__webpack_exports__, {
+    unwrapError: ()=>unwrapError
+});
+const external_is_success_cjs_namespaceObject = require("./is-success.cjs");
+const unwrapError = (result)=>{
+    if ((0, external_is_success_cjs_namespaceObject.isSuccess)(result)) throw result.value;
+    return result.error;
+};
+exports.unwrapError = __webpack_exports__.unwrapError;
+for(var __webpack_i__ in __webpack_exports__)if (-1 === [
+    "unwrapError"
+].indexOf(__webpack_i__)) exports[__webpack_i__] = __webpack_exports__[__webpack_i__];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/cjs/functions/unwrap-error.d.ts

@@ -0,0 +1,31 @@
+import type { Result } from '../result';
+/**
+ * Extracts the error value from a {@link Result}.
+ *
+ * If the result is a {@link Success}, it throws the success value (this is rare but symmetric to `unwrap`).
+ *
+ * @function
+ * @typeParam E - The type of the error value.
+ * @param result - The {@link Result} to unwrap the error from.
+ * @returns The error value.
+ * @throws The success value if the result is a {@link Success}.
+ *
+ * @example Failure Case
+ * ```ts
+ * import { Result } from '@praha/byethrow';
+ *
+ * const result: Result.Result<number, string> = { type: 'Failure', error: 'Something went wrong' };
+ * const error = Result.unwrapError(result); // 'Something went wrong'
+ * ```
+ *
+ * @example Success Case
+ * ```ts
+ * import { Result } from '@praha/byethrow';
+ *
+ * const result: Result.Result<number, string> = { type: 'Success', value: 123 };
+ * const error = Result.unwrapError(result); // throws 123
+ * ```
+ *
+ * @category Unwraps
+ */
+export declare const unwrapError: <E>(result: Result<unknown, E>) => E;

package/dist/cjs/functions/unwrap.cjs

@@ -0,0 +1,40 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.d = (exports1, definition)=>{
+        for(var key in definition)if (__webpack_require__.o(definition, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
+            enumerable: true,
+            get: definition[key]
+        });
+    };
+})();
+(()=>{
+    __webpack_require__.o = (obj, prop)=>Object.prototype.hasOwnProperty.call(obj, prop);
+})();
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ('undefined' != typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+__webpack_require__.d(__webpack_exports__, {
+    unwrap: ()=>unwrap
+});
+const external_is_failure_cjs_namespaceObject = require("./is-failure.cjs");
+const unwrap = (result)=>{
+    if ((0, external_is_failure_cjs_namespaceObject.isFailure)(result)) throw result.error;
+    return result.value;
+};
+exports.unwrap = __webpack_exports__.unwrap;
+for(var __webpack_i__ in __webpack_exports__)if (-1 === [
+    "unwrap"
+].indexOf(__webpack_i__)) exports[__webpack_i__] = __webpack_exports__[__webpack_i__];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/cjs/functions/unwrap.d.ts

@@ -0,0 +1,31 @@
+import type { Result } from '../result';
+/**
+ * Extracts the success value from a {@link Result}.
+ *
+ * If the result is a {@link Failure}, it throws the contained error.
+ *
+ * @function
+ * @typeParam T - The type of the success value.
+ * @param result - The {@link Result} to unwrap.
+ * @returns The success value.
+ * @throws The error value if the result is a {@link Failure}.
+ *
+ * @example Success Case
+ * ```ts
+ * import { Result } from '@praha/byethrow';
+ *
+ * const result: Result.Result<number, string> = { type: 'Success', value: 100 };
+ * const value = Result.unwrap(result); // 100
+ * ```
+ *
+ * @example Failure Case
+ * ```ts
+ * import { Result } from '@praha/byethrow';
+ *
+ * const result: Result.Result<number, string> = { type: 'Failure', error: 'Oops' };
+ * const value = Result.unwrap(result); // throws 'Oops'
+ * ```
+ *
+ * @category Unwraps
+ */
+export declare const unwrap: <T>(result: Result<T, unknown>) => T;

package/dist/cjs/index.cjs

@@ -0,0 +1,39 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.d = (exports1, definition)=>{
+        for(var key in definition)if (__webpack_require__.o(definition, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
+            enumerable: true,
+            get: definition[key]
+        });
+    };
+})();
+(()=>{
+    __webpack_require__.o = (obj, prop)=>Object.prototype.hasOwnProperty.call(obj, prop);
+})();
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ('undefined' != typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+__webpack_require__.d(__webpack_exports__, {
+    R: ()=>external_exports_cjs_namespaceObject,
+    Result: ()=>external_exports_cjs_namespaceObject
+});
+const external_exports_cjs_namespaceObject = require("./exports.cjs");
+exports.R = __webpack_exports__.R;
+exports.Result = __webpack_exports__.Result;
+for(var __webpack_i__ in __webpack_exports__)if (-1 === [
+    "R",
+    "Result"
+].indexOf(__webpack_i__)) exports[__webpack_i__] = __webpack_exports__[__webpack_i__];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/cjs/index.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Re-exports core Result-handling utilities under two convenient namespaces:
+ *
+ * - `Result`: Verbose and explicit usage
+ * - `R`: Shorthand alias for more concise code
+ *
+ * @example Basic Usage
+ * ```ts
+ * import { Result } from '@praha/byethrow';
+ *
+ * const validateId = (id: string) => {
+ *   if (!id.startsWith('u')) {
+ *     return Result.fail(new Error('Invalid ID format'));
+ *   }
+ *   return Result.succeed();
+ * };
+ *
+ * const findUser = Result.try({
+ *   try: (id: string) => {
+ *     return { id, name: 'John Doe' };
+ *   },
+ *   catch: (error) => new Error('Failed to find user', { cause: error }),
+ * });
+ *
+ * const result = Result.pipe(
+ *   Result.succeed('u123'),
+ *   Result.andThrough(validateId),
+ *   Result.andThen(findUser),
+ * );
+ *
+ * if (Result.isSuccess(result)) {
+ *   console.log(result.value); // User found: John Doe
+ * }
+ * ```
+ *
+ * @example Shorthand Usage
+ * ```ts
+ * import { R } from '@praha/byethrow';
+ *
+ * const validateId = (id: string) => {
+ *   if (!id.startsWith('u')) {
+ *     return R.fail(new Error('Invalid ID format'));
+ *   }
+ *   return R.succeed();
+ * };
+ *
+ * const findUser = R.try({
+ *   try: (id: string) => {
+ *     return { id, name: 'John Doe' };
+ *   },
+ *   catch: (error) => new Error('Failed to find user', { cause: error }),
+ * });
+ *
+ * const result = R.pipe(
+ *   R.succeed('u123'),
+ *   R.andThrough(validateId),
+ *   R.andThen(findUser),
+ * );
+ *
+ * if (R.isSuccess(result)) {
+ *   console.log(result.value); // User found: John Doe
+ * }
+ * ```
+ */
+export * as Result from './exports';
+/**
+ * Shorthand alias for {@link Result}.
+ */
+export * as R from './exports';

package/dist/cjs/internals/helpers/is-promise.cjs

@@ -0,0 +1,36 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.d = (exports1, definition)=>{
+        for(var key in definition)if (__webpack_require__.o(definition, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
+            enumerable: true,
+            get: definition[key]
+        });
+    };
+})();
+(()=>{
+    __webpack_require__.o = (obj, prop)=>Object.prototype.hasOwnProperty.call(obj, prop);
+})();
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ('undefined' != typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+__webpack_require__.d(__webpack_exports__, {
+    isPromise: ()=>isPromise
+});
+const isPromise = (value)=>'object' == typeof value && null !== value && 'then' in value && 'function' == typeof value.then && 'catch' in value && 'function' == typeof value.catch;
+exports.isPromise = __webpack_exports__.isPromise;
+for(var __webpack_i__ in __webpack_exports__)if (-1 === [
+    "isPromise"
+].indexOf(__webpack_i__)) exports[__webpack_i__] = __webpack_exports__[__webpack_i__];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/cjs/internals/helpers/is-promise.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Determines whether a given value is a `Promise`.
+ *
+ * @typeParam T - The value type.
+ *
+ * @param value - A value that might be a `Promise`.
+ * @returns `true` if the value is a `Promise`, otherwise `false`.
+ */
+export declare const isPromise: <T>(value: T | Promise<T>) => value is Promise<T>;

package/dist/cjs/internals/types/has-promise.cjs

@@ -0,0 +1,18 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ('undefined' != typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+for(var __webpack_i__ in __webpack_exports__)exports[__webpack_i__] = __webpack_exports__[__webpack_i__];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/cjs/internals/types/has-promise.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Determines whether the given type `T` is a `Promise`.
+ *
+ * Returns `true` if `T` extends `Promise<unknown>`, otherwise `false`.
+ *
+ * @typeParam T - The type to test.
+ *
+ * @example
+ * ```ts
+ * type A = HasPromise<Promise<number>>; // true
+ * type B = HasPromise<Promise<string> | number>; // true
+ * type C = HasPromise<number>; // false
+ * type D = HasPromise<{}>; // false
+ * type E = HasPromise<[]>; // true
+ * ```
+ */
+export type HasPromise<T> = object extends T ? false : Promise<any> extends T ? true : false;

package/dist/cjs/result.cjs

@@ -0,0 +1,18 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ('undefined' != typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+for(var __webpack_i__ in __webpack_exports__)exports[__webpack_i__] = __webpack_exports__[__webpack_i__];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/cjs/result.d.ts

@@ -0,0 +1,193 @@
+import type { HasPromise } from './internals/types/has-promise';
+/**
+ * Represents a successful result.
+ *
+ * @typeParam T - The type of the successful value.
+ *
+ * @example
+ * ```ts
+ * import { Result } from '@praha/byethrow';
+ *
+ * const success: Result.Success<number> = {
+ *   type: 'Success',
+ *   value: 42,
+ * };
+ * ```
+ *
+ * @category Core Types
+ */
+export type Success<T> = {
+    readonly type: 'Success';
+    readonly value: T;
+};
+/**
+ * Represents a failed result.
+ *
+ * @typeParam E - The type of the error.
+ *
+ * @example
+ * ```ts
+ * import { Result } from '@praha/byethrow';
+ *
+ * const failure: Result.Failure<string> = {
+ *   type: 'Failure',
+ *   error: 'Something went wrong',
+ * };
+ * ```
+ *
+ * @category Core Types
+ */
+export type Failure<E> = {
+    readonly type: 'Failure';
+    readonly error: E;
+};
+/**
+ * A union type representing either a success or a failure.
+ *
+ * @typeParam T - The type of the {@link Success} value.
+ * @typeParam E - The type of the {@link Failure} value.
+ *
+ * @example
+ * ```ts
+ * import { Result } from '@praha/byethrow';
+ *
+ * const doSomething = (): Result.Result<number, string> => {
+ *   return Math.random() > 0.5
+ *     ? { type: 'Success', value: 10 }
+ *     : { type: 'Failure', error: 'Oops' };
+ * };
+ * ```
+ *
+ * @category Core Types
+ */
+export type Result<T, E> = Success<T> | Failure<E>;
+/**
+ * An asynchronous variant of {@link Result}, wrapped in a `Promise`.
+ *
+ * @typeParam T - The type of the {@link Success} value.
+ * @typeParam E - The type of the {@link Failure} value.
+ *
+ * @example
+ * ```ts
+ * import { Result } from '@praha/byethrow';
+ *
+ * const fetchData = async (): Result.ResultAsync<string, Error> => {
+ *   try {
+ *     const data = await fetch('...');
+ *     return { type: 'Success', value: await data.text() };
+ *   } catch (err) {
+ *     return { type: 'Failure', error: err as Error };
+ *   }
+ * };
+ * ```
+ *
+ * @category Core Types
+ */
+export type ResultAsync<T, E> = Promise<Result<T, E>>;
+/**
+ * A result that may be either synchronous or asynchronous.
+ *
+ * @typeParam T - The type of the {@link Success} value.
+ * @typeParam E - The type of the {@link Failure} value.
+ *
+ * @example Synchronous Case
+ * ```ts
+ * import { Result } from '@praha/byethrow';
+ *
+ * const result: Result.ResultMaybeAsync<number, string> = { type: 'Success', value: 10 };
+ * ```
+ *
+ * @example Asynchronous Case
+ * ```ts
+ * import { Result } from '@praha/byethrow';
+ *
+ * const result: Result.ResultMaybeAsync<number, string> = Promise.resolve({ type: 'Failure', error: 'error' });
+ * ```
+ *
+ * @category Core Types
+ */
+export type ResultMaybeAsync<T, E> = Result<T, E> | Promise<Result<T, E>>;
+/**
+ * Resolves to the appropriate Result type (sync or async) based on the input type.
+ *
+ * Typically used to conditionally infer return types based on whether the original computation was async.
+ *
+ * @typeParam R - The reference type to inspect for a Promise.
+ * @typeParam T - The type of the {@link Success} value.
+ * @typeParam E - The type of the {@link Failure} value.
+ *
+ * @example With a Promise-returning function
+ * ```ts
+ * import { Result } from '@praha/byethrow';
+ *
+ * type R = Result.ResultAsync<number, string>;
+ * type Output = Result.ResultFor<R, number, string>; // Result.ResultAsync<number, string>
+ * ```
+ *
+ * @example With a non-Promise-returning function
+ * ```ts
+ * import { Result } from '@praha/byethrow';
+ *
+ * type R = Result.Result<number, string>;
+ * type Output = Result.ResultFor<R, number, string>; // Result.Result<number, string>
+ * ```
+ *
+ * @category Core Types
+ */
+export type ResultFor<R, T, E> = true extends HasPromise<R> ? ResultAsync<T, E> : Result<T, E>;
+/**
+ * Infers the {@link Success} value type `T` from a Result or a function returning a Result.
+ *
+ * @typeParam T - A {@link ResultMaybeAsync} type or a function returning it.
+ *
+ * @example From a result object
+ * ```ts
+ * import { Result } from '@praha/byethrow';
+ *
+ * type R = Result.Result<number, string>;
+ * type SuccessValue = Result.InferSuccess<R>; // number
+ * ```
+ *
+ * @example From a function
+ * ```ts
+ * import { Result } from '@praha/byethrow';
+ *
+ * const fn = () => Promise.resolve({ type: 'Success', value: 123 } as const);
+ * type SuccessValue = Result.InferSuccess<typeof fn>; // number
+ * ```
+ *
+ * @category Infer Types
+ */
+export type InferSuccess<T> = [
+    T
+] extends [(...args: any[]) => ResultMaybeAsync<infer U, any>] ? U : [
+    T
+] extends [ResultMaybeAsync<infer U, any>] ? U : never;
+/**
+ * Infers the {@link Failure} value type `E` from a Result or a function returning a Result.
+ *
+ * @typeParam T - A {@link ResultMaybeAsync} type or a function returning it.
+ *
+ * @example From a result object
+ * ```ts
+ * import { Result } from '@praha/byethrow';
+ *
+ * type R = Result.Result<number, string>;
+ * type ErrorValue = Result.InferFailure<R>; // string
+ * ```
+ *
+ * @example From a function
+ * ```ts
+ * import { Result } from '@praha/byethrow';
+ *
+ * const fn = () => Promise.resolve({ type: 'Failure', error: new Error() } as const);
+ * type ErrorValue = Result.InferFailure<typeof fn>; // Error
+ * ```
+ *
+ * @category Infer Types
+ */
+export type InferFailure<T> = [
+    T
+] extends [(...args: any[]) => ResultMaybeAsync<any, infer U>] ? U : [
+    T
+] extends [ResultMaybeAsync<any, infer U>] ? U : never;

package/dist/esm/exports.d.ts

@@ -0,0 +1,15 @@
+export * from './result';
+export * from './functions/and-then';
+export * from './functions/and-through';
+export * from './functions/bind';
+export * from './functions/do';
+export * from './functions/fail';
+export * from './functions/is-failure';
+export * from './functions/is-success';
+export * from './functions/map';
+export * from './functions/map-error';
+export * from './functions/pipe';
+export * from './functions/succeed';
+export * from './functions/try';
+export * from './functions/unwrap';
+export * from './functions/unwrap-error';

package/dist/esm/exports.js

@@ -0,0 +1,15 @@
+export * from "./result.js";
+export * from "./functions/and-then.js";
+export * from "./functions/and-through.js";
+export * from "./functions/bind.js";
+export * from "./functions/do.js";
+export * from "./functions/fail.js";
+export * from "./functions/is-failure.js";
+export * from "./functions/is-success.js";
+export * from "./functions/map.js";
+export * from "./functions/map-error.js";
+export * from "./functions/pipe.js";
+export * from "./functions/succeed.js";
+export * from "./functions/try.js";
+export * from "./functions/unwrap.js";
+export * from "./functions/unwrap-error.js";