@praha/byethrow 0.8.2 → 0.10.0

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/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 };

package/dist/esm/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/esm/functions/try.js

@@ -2,9 +2,9 @@ import { fail } from "./fail.js";
 import { succeed } from "./succeed.js";
 import { isPromise } from "../internals/helpers/is-promise.js";
 const try_ = (options)=>{
-    const fn = (...args)=>{
+    const fn = ()=>{
         try {
-            const output = options.try(...args);
+            const output = options.try();
             if (isPromise(output)) {
                 const promise = succeed(output);
                 if ('safe' in options && options.safe) return promise;
@@ -16,7 +16,6 @@ const try_ = (options)=>{
             return fail(options.catch(error));
         }
     };
-    if ('immediate' in options && options.immediate) return fn();
-    return fn;
+    return fn();
 };
 export { try_ as try };

package/dist/esm/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@praha/byethrow",
-  "version": "0.8.2",
+  "version": "0.10.0",
   "description": "A lightweight, tree-shakable Result type package with a simple, consistent API designed",
   "keywords": [
     "javascript",
@@ -44,12 +44,12 @@
     "@standard-schema/spec": "^1.0.0"
   },
   "devDependencies": {
-    "@rslib/core": "0.18.4",
-    "eslint": "9.39.1",
-    "typedoc": "0.28.15",
-    "typedoc-plugin-markdown": "4.9.0",
+    "@rslib/core": "0.19.5",
+    "eslint": "9.39.2",
+    "typedoc": "0.28.17",
+    "typedoc-plugin-markdown": "4.10.0",
     "typescript": "5.9.3",
-    "vitest": "4.0.15"
+    "vitest": "4.0.18"
   },
   "peerDependencies": {
     "typescript": ">=5.0.0"