runtry 0.1.0 → 0.2.1

package/LICENSE

@@ -1,6 +1,21 @@
-Copyright 2026 sebastiansala
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+MIT License
 
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+Copyright (c) 2026 Sebastian Sala
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,15 +1,173 @@
-# trycatchfinally
+# runtry
 
-To install dependencies:
+Run async functions and return a typed `Result` **instead of throwing**.
+
+- ✅ No repetitive `try/catch` in UI code
+- ✅ Typed success/error handling
+- ✅ Pluggable error normalization (matchers / adapters)
+
+---
+
+## Install
 
 ```bash
-bun install
+npm i runtry
+# or
+bun add runtry
+# or
+pnpm add runtry
 ```
 
-To run:
+---
 
-```bash
-bun run index.ts
+## Quick start
+
+```ts
+import { run } from "runtry";
+
+const result = await run(async () => {
+  // any async work
+  return 42;
+});
+
+if (result.ok) {
+  console.log("data:", result.data);
+} else {
+  console.error("error:", result.error.code, result.error.message);
+}
 ```
 
-This project was created using `bun init` in bun v1.2.9. [Bun](https://bun.sh) is a fast all-in-one JavaScript runtime.
+---
+
+## API
+
+### `run(fn, options?)`
+
+```ts
+import type { AppError, RunOptions, RunResult } from "runtry";
+
+declare function run<T, E extends AppError = AppError>(
+  fn: () => Promise<T>,
+  options?: RunOptions<T, E>
+): Promise<RunResult<T, E>>;
+```
+
+- Returns `{ ok: true, data, error: null }` on success
+- Returns `{ ok: false, data: null, error }` on failure
+- Never throws (unless your callbacks throw)
+
+---
+
+## Normalizing errors (matchers)
+
+`runtry` can normalize unknown thrown values (`unknown`) into a consistent `AppError` shape.
+
+### 1) Create matchers (adapters)
+
+```ts
+import {
+  createNormalizer,
+  abortMatcher,
+  instanceOfMatcher,
+  defaultFallback,
+} from "runtry";
+import type { AppError } from "runtry";
+import { HttpError } from "./http-error"; // your app error class
+
+type MyMeta = { url?: string; body?: unknown };
+
+const httpMatcher = instanceOfMatcher(HttpError, (e) => ({
+  code: "HTTP",
+  message: e.message,
+  status: e.status,
+  meta: { url: e.url, body: e.body } as MyMeta,
+  cause: e,
+}));
+
+const toError = createNormalizer<AppError<MyMeta>>(
+  [abortMatcher, httpMatcher],
+  (e) => defaultFallback(e) as AppError<MyMeta>
+);
+```
+
+### 2) Use the normalizer in `run`
+
+```ts
+import { run } from "runtry";
+
+const res = await run(getDocuments, {
+  toError,
+  onError: (e) => console.log(e.status, e.message),
+});
+```
+
+---
+
+## `createClient()` (configure once, reuse everywhere)
+
+If you don't want to pass `toError` every time, create a client:
+
+```ts
+import {
+  createClient,
+  abortMatcher,
+  instanceOfMatcher,
+  defaultFallback,
+} from "runtry";
+import { HttpError } from "./http-error";
+
+const client = createClient({
+  matchers: [
+    abortMatcher,
+    instanceOfMatcher(HttpError, (e) => ({
+      code: "HTTP",
+      message: e.message,
+      status: e.status,
+      meta: { url: e.url, body: e.body },
+      cause: e,
+    })),
+  ],
+  fallback: defaultFallback,
+  ignoreAbort: true, // default
+});
+
+const result = await client.run(getDocuments, {
+  onError: (e) => console.log(e.code, e.message),
+});
+```
+
+---
+
+## React example (loading + toast, no try/catch)
+
+```ts
+import { createClient, abortMatcher, defaultFallback } from "runtry";
+
+const client = createClient({
+  matchers: [abortMatcher],
+  fallback: defaultFallback,
+});
+
+useEffect(() => {
+  let cancelled = false;
+  setIsLoading(true);
+
+  client.run(getDocuments, {
+    onSuccess: (docs) => {
+      if (cancelled) return;
+      setUploadedFiles(docs.map(mapper));
+    },
+    onError: (e) => {
+      if (e.code === "ABORTED") return;
+      toast.error(e.message);
+    },
+    onFinally: () => {
+      if (!cancelled) setIsLoading(false);
+    },
+  });
+
+  return () => {
+    cancelled = true;
+  };
+}, []);
+```

package/dist/client.d.ts

@@ -0,0 +1,20 @@
+import type { AppError } from "./error/types";
+import type { Matcher } from "./error/normalize";
+import type { RunOptions, RunResult } from "./types";
+export type CreateClientOptions<E extends AppError = AppError> = {
+    matchers?: Matcher<E>[];
+    fallback?: (err: unknown) => E;
+    /**
+     * If you want a completely custom normalizer, you can provide it directly.
+     * If set, `matchers` and `fallback` are ignored.
+     */
+    toError?: (err: unknown) => E;
+    /** Default for run options */
+    ignoreAbort?: boolean;
+    /** Optional default mapper for all runs */
+    mapError?: (error: E) => E;
+};
+export declare function createClient<E extends AppError = AppError>(opts?: CreateClientOptions<E>): {
+    run<T>(fn: () => Promise<T>, options?: RunOptions<T, E>): Promise<RunResult<T, E>>;
+};
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAOjD,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAErD,MAAM,MAAM,mBAAmB,CAAC,CAAC,SAAS,QAAQ,GAAG,QAAQ,IAAI;IAC/D,QAAQ,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;IACxB,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,CAAC,CAAC;IAC/B;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,CAAC,CAAC;IAE9B,8BAA8B;IAC9B,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC;CAC5B,CAAC;AAEF,wBAAgB,YAAY,CAAC,CAAC,SAAS,QAAQ,GAAG,QAAQ,EACxD,IAAI,GAAE,mBAAmB,CAAC,CAAC,CAAM;QAiB3B,CAAC,MACC,MAAM,OAAO,CAAC,CAAC,CAAC,YACX,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,GACxB,OAAO,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;EAgB9B"}

package/dist/client.js

@@ -0,0 +1,26 @@
+import { createNormalizer, defaultFallback, toAppError, } from "./error/normalize";
+import { run as baseRun } from "./run";
+export function createClient(opts = {}) {
+    const { matchers = [], fallback = (e) => defaultFallback(e), toError: customToError, ignoreAbort = true, mapError: defaultMapError, } = opts;
+    const toError = customToError ??
+        (matchers.length > 0
+            ? createNormalizer(matchers, fallback)
+            : toAppError);
+    return {
+        run(fn, options = {}) {
+            return baseRun(fn, {
+                toError,
+                ignoreAbort,
+                mapError: (err) => options.mapError
+                    ? options.mapError(defaultMapError ? defaultMapError(err) : err)
+                    : defaultMapError
+                        ? defaultMapError(err)
+                        : err,
+                onError: options.onError,
+                onSuccess: options.onSuccess,
+                onFinally: options.onFinally,
+            });
+        },
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,UAAU,GACX,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,GAAG,IAAI,OAAO,EAAE,MAAM,OAAO,CAAC;AAmBvC,MAAM,UAAU,YAAY,CAC1B,OAA+B,EAAE;IAEjC,MAAM,EACJ,QAAQ,GAAG,EAAE,EACb,QAAQ,GAAG,CAAC,CAAU,EAAE,EAAE,CAAC,eAAe,CAAC,CAAC,CAAiB,EAC7D,OAAO,EAAE,aAAa,EACtB,WAAW,GAAG,IAAI,EAClB,QAAQ,EAAE,eAAe,GAC1B,GAAG,IAAI,CAAC;IAET,MAAM,OAAO,GACX,aAAa;QACb,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC;YAClB,CAAC,CAAC,gBAAgB,CAAI,QAAQ,EAAE,QAAQ,CAAC;YACzC,CAAC,CAAE,UAA2C,CAAC,CAAC;IAEpD,OAAO;QACL,GAAG,CACD,EAAoB,EACpB,UAA4B,EAAE;YAE9B,OAAO,OAAO,CAAC,EAAE,EAAE;gBACjB,OAAO;gBACP,WAAW;gBACX,QAAQ,EAAE,CAAC,GAAG,EAAE,EAAE,CAChB,OAAO,CAAC,QAAQ;oBACd,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;oBAChE,CAAC,CAAC,eAAe;wBACjB,CAAC,CAAC,eAAe,CAAC,GAAG,CAAC;wBACtB,CAAC,CAAC,GAAG;gBACT,OAAO,EAAE,OAAO,CAAC,OAAO;gBACxB,SAAS,EAAE,OAAO,CAAC,SAAS;gBAC5B,SAAS,EAAE,OAAO,CAAC,SAAS;aAC7B,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/error/matchers.d.ts

@@ -0,0 +1,6 @@
+import type { AppError } from "./types";
+import type { Matcher } from "./normalize";
+export declare const abortMatcher: Matcher;
+export declare const timeoutMatcher: Matcher;
+export declare function instanceOfMatcher<T extends Error, Meta = unknown>(ErrorCtor: new (...args: any[]) => T, map: (e: T) => AppError<Meta>): Matcher<AppError<Meta>>;
+//# sourceMappingURL=matchers.d.ts.map

package/dist/error/matchers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matchers.d.ts","sourceRoot":"","sources":["../../src/error/matchers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAG3C,eAAO,MAAM,YAAY,EAAE,OAK1B,CAAC;AAGF,eAAO,MAAM,cAAc,EAAE,OAS5B,CAAC;AAGF,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,KAAK,EAAE,IAAI,GAAG,OAAO,EAC/D,SAAS,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,EACpC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,QAAQ,CAAC,IAAI,CAAC,GAC5B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAEzB"}

package/dist/error/matchers.js

@@ -0,0 +1,23 @@
+// Matcher genérico para AbortError (por si no quieres usar toAppError)
+export const abortMatcher = (err) => {
+    if (err instanceof DOMException && err.name === "AbortError") {
+        return { code: "ABORTED", message: "Request cancelled", cause: err };
+    }
+    return null;
+};
+// Matcher para "timeout" (si el user usa AbortSignal.timeout o libs que tiran ese name)
+export const timeoutMatcher = (err) => {
+    if (err instanceof DOMException && err.name === "TimeoutError") {
+        return { code: "TIMEOUT", message: "Request timed out", cause: err };
+    }
+    // algunas libs tiran Error con name = "TimeoutError"
+    if (err instanceof Error && err.name === "TimeoutError") {
+        return { code: "TIMEOUT", message: err.message || "Request timed out", cause: err };
+    }
+    return null;
+};
+// Helper para crear matcher basado en "instanceof" (plugin-friendly)
+export function instanceOfMatcher(ErrorCtor, map) {
+    return (err) => (err instanceof ErrorCtor ? map(err) : null);
+}
+//# sourceMappingURL=matchers.js.map

package/dist/error/matchers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"matchers.js","sourceRoot":"","sources":["../../src/error/matchers.ts"],"names":[],"mappings":"AAGA,uEAAuE;AACvE,MAAM,CAAC,MAAM,YAAY,GAAY,CAAC,GAAG,EAAE,EAAE;IAC3C,IAAI,GAAG,YAAY,YAAY,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;QAC7D,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,mBAAmB,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;IACvE,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC,CAAC;AAEF,wFAAwF;AACxF,MAAM,CAAC,MAAM,cAAc,GAAY,CAAC,GAAG,EAAE,EAAE;IAC7C,IAAI,GAAG,YAAY,YAAY,IAAI,GAAG,CAAC,IAAI,KAAK,cAAc,EAAE,CAAC;QAC/D,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,mBAAmB,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;IACvE,CAAC;IACD,qDAAqD;IACrD,IAAI,GAAG,YAAY,KAAK,IAAI,GAAG,CAAC,IAAI,KAAK,cAAc,EAAE,CAAC;QACxD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,IAAI,mBAAmB,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;IACtF,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC,CAAC;AAEF,qEAAqE;AACrE,MAAM,UAAU,iBAAiB,CAC/B,SAAoC,EACpC,GAA6B;IAE7B,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,YAAY,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AAC/D,CAAC"}

package/dist/error/normalize.d.ts

@@ -0,0 +1,6 @@
+import type { AppError } from "./types";
+export type Matcher<E extends AppError = AppError> = (err: unknown) => E | null;
+export declare function createNormalizer<E extends AppError>(matchers: Matcher<E>[], fallback: (err: unknown) => E): (err: unknown) => E;
+export declare function defaultFallback(err: unknown): AppError;
+export declare function toAppError(err: unknown): AppError;
+//# sourceMappingURL=normalize.d.ts.map

package/dist/error/normalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../src/error/normalize.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAExC,MAAM,MAAM,OAAO,CAAC,CAAC,SAAS,QAAQ,GAAG,QAAQ,IAAI,CAAC,GAAG,EAAE,OAAO,KAAK,CAAC,GAAG,IAAI,CAAC;AAEhF,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,QAAQ,EACjD,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,EACtB,QAAQ,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,CAAC,IAErB,KAAK,OAAO,KAAG,CAAC,CAOzB;AAGD,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,QAAQ,CAQtD;AAGD,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,QAAQ,CAMjD"}

package/dist/error/normalize.js

@@ -0,0 +1,29 @@
+export function createNormalizer(matchers, fallback) {
+    return (err) => {
+        for (const m of matchers) {
+            const out = m(err);
+            if (out)
+                return out;
+        }
+        return fallback(err);
+    };
+}
+// Fallback general (sin depender de fetch / http)
+export function defaultFallback(err) {
+    if (err instanceof Error) {
+        // En browsers, errores de red a veces caen como TypeError (fetch),
+        // pero esto no es 100% universal; lo tratamos como best-effort.
+        const code = err.name === "TypeError" ? "NETWORK" : "UNKNOWN";
+        return { code, message: err.message || "Something went wrong", cause: err };
+    }
+    return { code: "UNKNOWN", message: "Something went wrong", cause: err };
+}
+// Normalizador "default" que incluye matcher de abort (muy útil en UI)
+export function toAppError(err) {
+    // AbortError (browser / fetch / AbortController)
+    if (err instanceof DOMException && err.name === "AbortError") {
+        return { code: "ABORTED", message: "Request cancelled", cause: err };
+    }
+    return defaultFallback(err);
+}
+//# sourceMappingURL=normalize.js.map

package/dist/error/normalize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.js","sourceRoot":"","sources":["../../src/error/normalize.ts"],"names":[],"mappings":"AAIA,MAAM,UAAU,gBAAgB,CAC9B,QAAsB,EACtB,QAA6B;IAE7B,OAAO,CAAC,GAAY,EAAK,EAAE;QACzB,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;YACzB,MAAM,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;YACnB,IAAI,GAAG;gBAAE,OAAO,GAAG,CAAC;QACtB,CAAC;QACD,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC;IACvB,CAAC,CAAC;AACJ,CAAC;AAED,kDAAkD;AAClD,MAAM,UAAU,eAAe,CAAC,GAAY;IAC1C,IAAI,GAAG,YAAY,KAAK,EAAE,CAAC;QACzB,mEAAmE;QACnE,gEAAgE;QAChE,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,KAAK,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;QAC9D,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,IAAI,sBAAsB,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;IAC9E,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,sBAAsB,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;AAC1E,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,UAAU,CAAC,GAAY;IACrC,iDAAiD;IACjD,IAAI,GAAG,YAAY,YAAY,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;QAC7D,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,mBAAmB,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;IACvE,CAAC;IACD,OAAO,eAAe,CAAC,GAAG,CAAC,CAAC;AAC9B,CAAC"}

package/dist/error/types.d.ts

@@ -0,0 +1,18 @@
+export type AppErrorCode = "ABORTED" | "NETWORK" | "TIMEOUT" | "VALIDATION" | "HTTP" | "UNKNOWN";
+/**
+* A normalized error shape returned by `run()`.
+*
+* - `code`: A stable identifier you can switch on (e.g. "HTTP", "VALIDATION").
+* - `message`: User-facing or log-friendly message.
+* - `status`: Optional numeric status (commonly HTTP status).
+* - `meta`: Optional payload with extra context (response body, validation fields, etc.).
+* - `cause`: The original thrown value for debugging.
+*/
+export type AppError<Meta = unknown> = {
+    code: AppErrorCode | (string & {});
+    message: string;
+    status?: number;
+    meta?: Meta;
+    cause?: unknown;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/error/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/error/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GACpB,SAAS,GACT,SAAS,GACT,SAAS,GACT,YAAY,GACZ,MAAM,GACN,SAAS,CAAC;AAEZ;;;;;;;;EAQC;AACH,MAAM,MAAM,QAAQ,CAAC,IAAI,GAAG,OAAO,IAAI;IACrC,IAAI,EAAE,YAAY,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC"}

package/dist/error/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/error/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/error/types.ts"],"names":[],"mappings":""}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { run } from "./run";
+export type { RunOptions, RunResult } from "./types";
+export type { AppError, AppErrorCode } from "./error/types";
+export { toAppError, defaultFallback, createNormalizer, } from "./error/normalize";
+export { abortMatcher, timeoutMatcher, instanceOfMatcher, } from "./error/matchers";
+export { createClient } from "./client";
+export type { CreateClientOptions } from "./client";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAC5B,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAErD,YAAY,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC5D,OAAO,EACL,UAAU,EACV,eAAe,EACf,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,YAAY,EACZ,cAAc,EACd,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,YAAY,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { run } from "./run";
+export { toAppError, defaultFallback, createNormalizer, } from "./error/normalize";
+export { abortMatcher, timeoutMatcher, instanceOfMatcher, } from "./error/matchers";
+export { createClient } from "./client";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAI5B,OAAO,EACL,UAAU,EACV,eAAe,EACf,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,YAAY,EACZ,cAAc,EACd,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC"}

package/dist/run.d.ts

@@ -0,0 +1,13 @@
+import type { AppError } from "./error/types";
+import type { RunOptions, RunResult } from "./types";
+/**
+ * Executes an async operation and returns a Result instead of throwing.
+ *
+ * Errors are normalized into an `AppError` (or a custom error type `E`)
+ * using the provided `toError` function.
+ *
+ * This utility is framework-agnostic and works in browsers, Node.js,
+ * React effects, and any async context.
+ */
+export declare function run<T, E extends AppError = AppError>(fn: () => Promise<T>, options?: RunOptions<T, E>): Promise<RunResult<T, E>>;
+//# sourceMappingURL=run.d.ts.map

package/dist/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAErD;;;;;;;;GAQG;AACH,wBAAsB,GAAG,CAAC,CAAC,EAAE,CAAC,SAAS,QAAQ,GAAG,QAAQ,EACxD,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,GAAE,UAAU,CAAC,CAAC,EAAE,CAAC,CAAM,GAC7B,OAAO,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CA4B1B"}

package/dist/run.js

@@ -0,0 +1,33 @@
+import { toAppError as defaultToAppError } from "./error/normalize";
+/**
+ * Executes an async operation and returns a Result instead of throwing.
+ *
+ * Errors are normalized into an `AppError` (or a custom error type `E`)
+ * using the provided `toError` function.
+ *
+ * This utility is framework-agnostic and works in browsers, Node.js,
+ * React effects, and any async context.
+ */
+export async function run(fn, options = {}) {
+    const { toError = defaultToAppError, mapError, onError, onSuccess, onFinally, ignoreAbort = true, } = options;
+    try {
+        const data = await fn();
+        onSuccess?.(data);
+        return { ok: true, data, error: null };
+    }
+    catch (e) {
+        let err = toError(e);
+        if (mapError)
+            err = mapError(err);
+        if (ignoreAbort && err.code === "ABORTED") {
+            // decisión de diseño: devolvemos ok:false pero sin llamar onError (para no toastear)
+            return { ok: false, data: null, error: err };
+        }
+        onError?.(err);
+        return { ok: false, data: null, error: err };
+    }
+    finally {
+        onFinally?.();
+    }
+}
+//# sourceMappingURL=run.js.map

package/dist/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,IAAI,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAGpE;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,GAAG,CACvB,EAAoB,EACpB,UAA4B,EAAE;IAE9B,MAAM,EACJ,OAAO,GAAG,iBAAmD,EAC7D,QAAQ,EACR,OAAO,EACP,SAAS,EACT,SAAS,EACT,WAAW,GAAG,IAAI,GACnB,GAAG,OAAO,CAAC;IAEZ,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,EAAE,EAAE,CAAC;QACxB,SAAS,EAAE,CAAC,IAAI,CAAC,CAAC;QAClB,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACzC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,IAAI,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;QACrB,IAAI,QAAQ;YAAE,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;QAElC,IAAI,WAAW,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC1C,qFAAqF;YACrF,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;QAC/C,CAAC;QAED,OAAO,EAAE,CAAC,GAAG,CAAC,CAAC;QACf,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;IAC/C,CAAC;YAAS,CAAC;QACT,SAAS,EAAE,EAAE,CAAC;IAChB,CAAC;AACH,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,61 @@
+import type { AppError } from "./error/types";
+export type RunOptions<T, E extends AppError = AppError> = {
+    /**
+     * Converts an unknown thrown value into your normalized error type `E`.
+     *
+     * Use this to integrate custom errors (e.g. HttpError, AxiosError, ZodError),
+     * map status codes, or attach metadata for UI/debugging.
+     *
+     * If omitted, a default normalizer is used (best-effort).
+     */
+    toError?: (err: unknown) => E;
+    /**
+     * Optional error transformer applied AFTER `toError`.
+     *
+     * Useful for translating messages, mapping status to user-friendly text,
+     * or enforcing a consistent error format across the app.
+     */
+    mapError?: (error: E) => E;
+    /**
+     * Called when the operation fails (except when `ignoreAbort` is true and the error code is "ABORTED").
+     *
+     * Great place for toasts, logging, analytics, etc.
+     */
+    onError?: (error: E) => void;
+    /**
+     * Called when the operation succeeds.
+     */
+    onSuccess?: (data: T) => void;
+    /**
+     * Called after success or failure (similar to a `finally` block).
+     *
+     * Common use: stop loading spinners, cleanup state, etc.
+     */
+    finally?: () => void;
+    /**
+     * Called after success or failure, similar to `finally`, but with no return value.
+     *
+     * Common use: stop loading spinners, cleanup state, etc.
+     */
+    onFinally?: () => void;
+    /**
+     * When true, errors with `code === "ABORTED"` are treated as non-fatal:
+     * - `onError` is NOT called
+     * - the result is returned as `{ ok: false, error }`
+     *
+     * This is useful for cancellable side-effects (React effects, debounced searches, etc.).
+     *
+     * @default true
+     */
+    ignoreAbort?: boolean;
+};
+export type RunResult<T, E extends AppError = AppError> = {
+    ok: true;
+    data: T;
+    error: null;
+} | {
+    ok: false;
+    data: null;
+    error: E;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,MAAM,MAAM,UAAU,CAAC,CAAC,EAAE,CAAC,SAAS,QAAQ,GAAG,QAAQ,IAAI;IACzD;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,CAAC,CAAC;IAE9B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC;IAE3B;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IAE7B;;OAEG;IACH,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC;IAE9B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IAErB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IAEvB;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,SAAS,CAAC,CAAC,EAAE,CAAC,SAAS,QAAQ,GAAG,QAAQ,IAClD;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,CAAC,CAAC;IAAC,KAAK,EAAE,IAAI,CAAA;CAAE,GAClC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,CAAC"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runtry",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Run async functions and return a typed Result instead of throwing.",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,12 +17,18 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.build.json",
     "prepublishOnly": "npm run build"
   },
   "devDependencies": {
     "@types/bun": "latest",
     "typescript": "^5.0.0"
   },
-  "license": "MIT"
+  "license": "MIT",
+  "homepage": "https://github.com/sebastiansala/runtry#readme",
+  "bugs": "https://github.com/sebastiansala/runtry/issues",
+  "author": {
+    "name": "sebasxsala",
+    "url": "https://github.com/sebasxsala"
+  }
 }