@praha/byethrow 0.9.0 → 0.10.1

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

@@ -1,7 +1,6 @@
 import type { Result, ResultAsync } from '../result.js';
 /**
- * Wraps a function execution (sync or async) or a Promise in a {@link Result} or {@link ResultAsync} type,
- * capturing errors and returning them in a structured way.
+ * Executes a function that may throw and wraps the result in a {@link Result} or {@link ResultAsync}.
  *
  * You can use either a custom `catch` handler or rely on the `safe: true` option
  * to assume the function cannot throw.
@@ -9,28 +8,13 @@ import type { Result, ResultAsync } from '../result.js';
  * @function
  * @typeParam T - The function type to execute (sync or async) or a Promise type.
  * @typeParam E - The error type to return if `catch` is used.
+ * @returns A {@link Result} or {@link ResultAsync} wrapping the function's return value or the caught error.
  *
  * @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 try-catch with immediate execution
- * ```ts
- * import { Result } from '@praha/byethrow';
- *
  * const result = Result.try({
- *   immediate: true,
  *   try: () => {
  *     const x = Math.random() * 10 - 5;
  *     if (x < 0) throw new Error('Negative!');
@@ -46,21 +30,8 @@ import type { Result, ResultAsync } from '../result.js';
  * ```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 Sync safe with immediate execution
- * ```ts
- * import { Result } from '@praha/byethrow';
- *
  * const result = Result.try({
  *   safe: true,
- *   immediate: true,
  *   try: () => Math.random() + 1,
  * });
  *
@@ -71,20 +42,7 @@ import type { Result, ResultAsync } from '../result.js';
  * ```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 try-catch with immediate execution
- * ```ts
- * import { Result } from '@praha/byethrow';
- *
  * const result = Result.try({
- *   immediate: true,
  *   try: () => fetch('/api/data'),
  *   catch: (error) => new Error('Fetch failed', { cause: error }),
  * });
@@ -96,21 +54,8 @@ import type { Result, ResultAsync } from '../result.js';
  * ```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>
- * ```
- *
- * @example Async safe with immediate execution
- * ```ts
- * import { Result } from '@praha/byethrow';
- *
  * const result = Result.try({
  *   safe: true,
- *   immediate: true,
  *   try: () => Promise.resolve('ok'),
  * });
  *
@@ -120,40 +65,20 @@ import type { Result, ResultAsync } from '../result.js';
  * @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 () => Promise<any>, E>(options: {
-        immediate: true;
         try: T;
         catch: (error: unknown) => E;
     }): ResultAsync<Awaited<ReturnType<T>>, E>;
-    <T extends (...args: readonly any[]) => Promise<any>>(options: {
-        safe: true;
-        try: T;
-    }): (...args: Parameters<T>) => ResultAsync<Awaited<ReturnType<T>>, never>;
     <T extends () => Promise<any>>(options: {
         safe: true;
-        immediate: true;
         try: 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 () => any, E>(options: {
-        immediate: true;
         try: T;
         catch: (error: unknown) => E;
     }): Result<ReturnType<T>, E>;
-    <T extends (...args: readonly any[]) => any>(options: {
-        safe: true;
-        try: T;
-    }): (...args: Parameters<T>) => Result<ReturnType<T>, never>;
     <T extends () => any>(options: {
         safe: true;
-        immediate: true;
         try: T;
     }): Result<ReturnType<T>, never>;
 };

package/dist/cjs/index.d.ts

@@ -15,7 +15,7 @@
  *   return Result.succeed();
  * };
  *
- * const findUser = Result.try({
+ * const findUser = Result.fn({
  *   try: (id: string) => {
  *     return { id, name: 'John Doe' };
  *   },
@@ -44,7 +44,7 @@
  *   return R.succeed();
  * };
  *
- * const findUser = R.try({
+ * const findUser = R.fn({
  *   try: (id: string) => {
  *     return { id, name: 'John Doe' };
  *   },

package/dist/esm/exports.d.ts

@@ -7,6 +7,7 @@ export * from './functions/bind.js';
 export * from './functions/collect.js';
 export * from './functions/do.js';
 export * from './functions/fail.js';
+export * from './functions/fn.js';
 export * from './functions/inspect.js';
 export * from './functions/inspect-error.js';
 export * from './functions/is-failure.js';
@@ -15,6 +16,7 @@ export * from './functions/is-success.js';
 export * from './functions/map.js';
 export * from './functions/map-error.js';
 export * from './functions/or-else.js';
+export * from './functions/or-through.js';
 export * from './functions/parse.js';
 export * from './functions/pipe.js';
 export * from './functions/sequence.js';

package/dist/esm/exports.js

@@ -7,6 +7,7 @@ export * from "./functions/bind.js";
 export * from "./functions/collect.js";
 export * from "./functions/do.js";
 export * from "./functions/fail.js";
+export * from "./functions/fn.js";
 export * from "./functions/inspect.js";
 export * from "./functions/inspect-error.js";
 export * from "./functions/is-failure.js";
@@ -15,6 +16,7 @@ export * from "./functions/is-success.js";
 export * from "./functions/map.js";
 export * from "./functions/map-error.js";
 export * from "./functions/or-else.js";
+export * from "./functions/or-through.js";
 export * from "./functions/parse.js";
 export * from "./functions/pipe.js";
 export * from "./functions/sequence.js";

package/dist/esm/functions/assert-failure.d.ts

@@ -1,13 +1,17 @@
-import type { Failure, InferFailure, Result, ResultAsync } from '../result.js';
+import type { HasPromise } from '../internals/types/has-promise.js';
+import type { Failure, InferFailure, ResultMaybeAsync } from '../result.js';
 /**
  * Asserts that a {@link Result} or {@link ResultAsync} is a {@link Failure} and returns it.
- * If the result is a {@link Success}, throws an error.
+ * This function requires that the result's success type is `never`, meaning the result is
+ * guaranteed to be a {@link Failure} at the type level.
+ * If the result is a {@link Success} at runtime, throws an error.
  *
  * @function
- * @typeParam E - The type of the error value.
+ * @typeParam R - The result type that extends {@link ResultMaybeAsync} with `never` as the success type.
  * @param result - The {@link Result} or {@link ResultAsync} to assert as a {@link Failure}.
- * @returns The {@link Failure} result or a Promise of {@link Success} result.
- * @throws {Error} If the result is a {@link Success}.
+ *                 The success type must be `never`.
+ * @returns The {@link Failure} result or a Promise of {@link Failure} result.
+ * @throws {Error} If the result is a {@link Success} at runtime.
  *
  * @example
  * ```ts
@@ -18,24 +22,15 @@ import type { Failure, InferFailure, Result, ResultAsync } from '../result.js';
  * // failure: { type: 'Failure', error: 'error' }
  * ```
  *
- * @example Throws on Success
- * ```ts
- * // @errors: 2769
- * import { Result } from '@praha/byethrow';
- *
- * const result = Result.succeed(42);
- * Result.assertFailure(result); // throws Error
- * ```
- *
- * @example Safe unwrap with assertFailure
+ * @example Type-safe usage after narrowing success type
  * ```ts
  * import { Result } from '@praha/byethrow';
  *
  * const getResult = (): Result.Result<number, string> => Result.fail('error');
  * const value = Result.pipe(
  *   getResult(),
- *   Result.andThen(() => Result.fail('die')),
- *   Result.assertFailure,
+ *   Result.andThen(() => Result.fail('die')), // Success type becomes never
+ *   Result.assertFailure, // Type-safe: success type is now never
  *   Result.unwrapError(), // Safe unwrap after assertion
  * );
  * ```
@@ -44,7 +39,4 @@ import type { Failure, InferFailure, Result, ResultAsync } from '../result.js';
  *
  * @category Assertions
  */
-export declare const assertFailure: {
-    <R extends ResultAsync<never, any>>(result: R): Promise<Failure<InferFailure<R>>>;
-    <R extends Result<never, any>>(result: R): Failure<InferFailure<R>>;
-};
+export declare const assertFailure: <R extends ResultMaybeAsync<never, any>>(result: R) => true extends HasPromise<R> ? Promise<Failure<InferFailure<R>>> : Failure<InferFailure<R>>;

package/dist/esm/functions/assert-success.d.ts

@@ -1,13 +1,17 @@
-import type { InferSuccess, Result, ResultAsync, Success } from '../result.js';
+import type { HasPromise } from '../internals/types/has-promise.js';
+import type { InferSuccess, ResultMaybeAsync, Success } from '../result.js';
 /**
  * Asserts that a {@link Result} or {@link ResultAsync} is a {@link Success} and returns it.
- * If the result is a {@link Failure}, throws an error.
+ * This function requires that the result's error type is `never`, meaning the result is
+ * guaranteed to be a {@link Success} at the type level.
+ * If the result is a {@link Failure} at runtime, throws an error.
  *
  * @function
- * @typeParam T - The type of the success value.
+ * @typeParam R - The result type that extends {@link ResultMaybeAsync} with `never` as the error type.
  * @param result - The {@link Result} or {@link ResultAsync} to assert as a {@link Success}.
+ *                 The error type must be `never`.
  * @returns The {@link Success} result or a Promise of {@link Success} result.
- * @throws {Error} If the result is a {@link Failure}.
+ * @throws {Error} If the result is a {@link Failure} at runtime.
  *
  * @example
  * ```ts
@@ -18,24 +22,15 @@ import type { InferSuccess, Result, ResultAsync, Success } from '../result.js';
  * // success: { type: 'Success', value: 42 }
  * ```
  *
- * @example Throws on Failure
- * ```ts
- * // @errors: 2769
- * import { Result } from '@praha/byethrow';
- *
- * const result = Result.fail('error');
- * Result.assertSuccess(result); // throws Error
- * ```
- *
- * @example Safe unwrap with assertSuccess
+ * @example Type-safe usage after narrowing error type
  * ```ts
  * import { Result } from '@praha/byethrow';
  *
  * const getResult = (): Result.Result<number, string> => Result.succeed(42);
  * const value = Result.pipe(
  *   getResult(),
- *   Result.orElse(() => Result.succeed('fallback')),
- *   Result.assertSuccess,
+ *   Result.orElse(() => Result.succeed(0)), // Error type becomes never
+ *   Result.assertSuccess, // Type-safe: error type is now never
  *   Result.unwrap(), // Safe unwrap after assertion
  * );
  * ```
@@ -44,7 +39,4 @@ import type { InferSuccess, Result, ResultAsync, Success } from '../result.js';
  *
  * @category Assertions
  */
-export declare const assertSuccess: {
-    <R extends ResultAsync<any, never>>(result: R): Promise<Success<InferSuccess<R>>>;
-    <R extends Result<any, never>>(result: R): Success<InferSuccess<R>>;
-};
+export declare const assertSuccess: <R extends ResultMaybeAsync<any, never>>(result: R) => true extends HasPromise<R> ? Promise<Success<InferSuccess<R>>> : Success<InferSuccess<R>>;

package/dist/esm/functions/fn.d.ts

@@ -0,0 +1,84 @@
+import type { Result, ResultAsync } from '../result.js';
+/**
+ * Wraps a function that may throw and returns a new function that returns a {@link Result} or {@link ResultAsync}.
+ *
+ * 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) or a Promise type.
+ * @typeParam E - The error type to return if `catch` is used.
+ * @returns A new function that returns a {@link Result} or {@link ResultAsync} wrapping the original function's return value or the caught error.
+ *
+ * @example Sync try-catch
+ * ```ts
+ * import { Result } from '@praha/byethrow';
+ *
+ * const fn = Result.fn({
+ *   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.fn({
+ *   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.fn({
+ *   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.fn({
+ *   safe: true,
+ *   try: async () => await Promise.resolve('ok'),
+ * });
+ *
+ * const result = await fn(); // Result.ResultAsync<string, never>
+ * ```
+ *
+ * @category Creators
+ */
+declare const fn: {
+    <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: {
+        safe: true;
+        try: T;
+    }): (...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: {
+        safe: true;
+        try: T;
+    }): (...args: Parameters<T>) => Result<ReturnType<T>, never>;
+};
+export { fn };

package/dist/esm/functions/fn.js

@@ -0,0 +1,21 @@
+import { fail } from "./fail.js";
+import { succeed } from "./succeed.js";
+import { isPromise } from "../internals/helpers/is-promise.js";
+const fn_fn = (options)=>{
+    const fn = (...args)=>{
+        try {
+            const output = options.try(...args);
+            if (isPromise(output)) {
+                const promise = succeed(output);
+                if ('safe' in options && options.safe) return promise;
+                return promise.catch((error)=>fail(options.catch(error)));
+            }
+            return succeed(output);
+        } catch (error) {
+            if ('safe' in options && options.safe) throw error;
+            return fail(options.catch(error));
+        }
+    };
+    return fn;
+};
+export { fn_fn as fn };

package/dist/esm/functions/is-failure.d.ts

@@ -1,9 +1,9 @@
-import type { Failure, Result } from '../result.js';
+import type { Result } from '../result.js';
 /**
  * Type guard to check if a {@link Result} is a {@link Failure}.
  *
  * @function
- * @typeParam E - The type of the error value.
+ * @typeParam R - The type of the result to check.
  * @param result - The {@link Result} to check.
  * @returns `true` if the result is a {@link Failure}, otherwise `false`.
  *
@@ -19,4 +19,6 @@ import type { Failure, Result } from '../result.js';
  *
  * @category Type Guards
  */
-export declare const isFailure: <E>(result: Result<unknown, E>) => result is Failure<E>;
+export declare const isFailure: <R extends Result<unknown, unknown>>(result: R) => result is Extract<R, {
+    readonly type: "Failure";
+}>;

package/dist/esm/functions/is-success.d.ts

@@ -1,9 +1,9 @@
-import type { Result, Success } from '../result.js';
+import type { Result } from '../result.js';
 /**
  * Type guard to check if a {@link Result} is a {@link Success}.
  *
  * @function
- * @typeParam T - The type of the success value.
+ * @typeParam R - The type of the result to check.
  * @param result - The {@link Result} to check.
  * @returns `true` if the result is a {@link Success}, otherwise `false`.
  *
@@ -19,4 +19,6 @@ import type { Result, Success } from '../result.js';
  *
  * @category Type Guards
  */
-export declare const isSuccess: <T>(result: Result<T, unknown>) => result is Success<T>;
+export declare const isSuccess: <R extends Result<unknown, unknown>>(result: R) => result is Extract<R, {
+    readonly type: "Success";
+}>;

package/dist/esm/functions/or-through.d.ts

@@ -0,0 +1,64 @@
+import type { InferFailure, InferSuccess, ResultFor, ResultMaybeAsync } from '../result.js';
+/**
+ * Runs an additional computation using the error value of a {@link Result} or {@link ResultAsync},
+ * but **returns the original failure** if the additional computation is successful.
+ *
+ * If the original result is a {@link Success}, it is returned immediately without running the function.
+ * If the original result is a {@link Failure}, the function is executed with the error value.
+ * If the function returns a {@link Success}, the original failure is returned.
+ * If the function returns a {@link Failure}, that new failure is returned.
+ *
+ * Useful for running error recovery or fallback logic while preserving the original error on success.
+ *
+ * @function
+ * @typeParam R1 - The input {@link Result} or {@link ResultAsync}.
+ * @typeParam R2 - The result type returned by `fn`.
+ *
+ * @example Success Case
+ * ```ts
+ * import { Result } from '@praha/byethrow';
+ *
+ * const result = Result.pipe(
+ *   Result.succeed(5),
+ *   Result.orThrough((error) => {
+ *     return Result.succeed(null);
+ *   }),
+ * );
+ * // { type: 'Success', value: 5 }
+ * ```
+ *
+ * @example Failure Case (function returns a Success)
+ * ```ts
+ * import { Result } from '@praha/byethrow';
+ *
+ * const result = Result.pipe(
+ *   Result.fail('error'),
+ *   Result.orThrough((error) => {
+ *     console.log('Logging error:', error);
+ *     return Result.succeed(null);
+ *   }),
+ * );
+ * // { type: 'Failure', error: 'error' }
+ * ```
+ *
+ * @example Failure Case (function returns a Failure)
+ * ```ts
+ * import { Result } from '@praha/byethrow';
+ *
+ * const result = Result.pipe(
+ *   Result.fail('original error'),
+ *   Result.orThrough((error) => {
+ *     return Result.fail('new error');
+ *   }),
+ * );
+ * // { type: 'Failure', error: 'new error' }
+ * ```
+ *
+ * @see {@link pipe} - It is recommended to use this function with the {@link pipe} function for better readability and composability.
+ *
+ * @category Combinators
+ */
+export declare const orThrough: {
+    <R1 extends ResultMaybeAsync<any, any>, R2 extends ResultMaybeAsync<any, any>>(fn: (a: InferFailure<R1>) => R2): (result: R1) => ResultFor<R1 | R2, InferSuccess<R1>, InferFailure<R1> | InferFailure<R2>>;
+    <F extends (a: any) => ResultMaybeAsync<any, any>>(fn: F): <R1 extends ResultMaybeAsync<any, Parameters<F>[0]>>(result: R1) => ResultFor<R1 | ReturnType<F>, InferSuccess<R1>, InferFailure<R1> | InferFailure<F>>;
+};

package/dist/esm/functions/or-through.js

@@ -0,0 +1,16 @@
+import { isSuccess } from "./is-success.js";
+import { isPromise } from "../internals/helpers/is-promise.js";
+const orThrough = (fn)=>(result)=>{
+        const apply = (r)=>{
+            if (isSuccess(r)) return r;
+            const next = fn(r.error);
+            if (isPromise(next)) return next.then((n)=>{
+                if (isSuccess(n)) return r;
+                return n;
+            });
+            if (isSuccess(next)) return r;
+            return next;
+        };
+        return isPromise(result) ? result.then(apply) : apply(result);
+    };
+export { orThrough };