use-fetch-error 1.0.3 → 2.0.0

package/README.md

@@ -1,20 +1,162 @@
-# Use-fetch-error
-
-## A library for error handling with [error, result] tuples using a `useFetchError()` function.
-
-### Example usage:
-
-```javascript
-(async () => {
-  const validURL = "https://jsonplaceholder.typicode.com/posts/1";
-  const invalidURL = "https://url-invalid.com";
-
-  const [error, data] = await useFetchError(invalidURL);
-
-  if (error) {
-    console.error("An error occurred:", error);
-  } else {
-    console.log("Data received:", data);
-  }
-})();
-```
+# Use-fetch-error
+
+## A library for error handling with [error, result] tuples using a `useFetchError()` function.
+
+Works with **JavaScript and TypeScript**, as ES modules (`import`) or CommonJS (`require`). It does not modify any built-in prototype and has no dependencies.
+
+### Installation
+
+```bash
+npm install use-fetch-error
+```
+
+### Example usage (JavaScript)
+
+```javascript
+import { useFetchError } from "use-fetch-error";
+// or: const { useFetchError } = require("use-fetch-error");
+
+const [error, data] = await useFetchError("https://jsonplaceholder.typicode.com/posts/1");
+
+if (error) {
+  console.error("An error occurred:", error);
+} else {
+  console.log("Data received:", data);
+}
+```
+
+### Example usage (TypeScript)
+
+```typescript
+import { useFetchError, HttpError } from "use-fetch-error";
+
+interface Post {
+  id: number;
+  title: string;
+}
+
+const [error, post] = await useFetchError<Post>("https://jsonplaceholder.typicode.com/posts/1");
+
+if (error) {
+  if (error instanceof HttpError) {
+    console.error(error.status, error.body);
+  }
+} else {
+  console.log(post.title); // `post` is `Post` here, not `Post | undefined`
+}
+```
+
+### When is `error` set?
+
+| Case | `error` |
+| --- | --- |
+| Network failure / aborted request | the `fetch` error |
+| `timeout` expired | `TimeoutError` (`error.timeout`) |
+| Status outside 200-299 | `HttpError` (`error.status`, `error.statusText`, `error.body`, `error.response`) |
+| Body cannot be parsed | the parse error (e.g. `SyntaxError`) |
+
+An empty body (e.g. `204 No Content`) returns `[null, null]`.
+
+### Options
+
+`useFetchError(input, options)` accepts every `fetch` option plus:
+
+- `parseAs`: `"json"` (default), `"text"`, `"blob"`, `"arrayBuffer"`, `"formData"` or `"response"` (returns the `Response` untouched).
+- `timeout`: milliseconds before the request is aborted.
+
+```javascript
+const [error, html] = await useFetchError("/page", { parseAs: "text", timeout: 5000 });
+```
+
+### Other helpers: `to()` and `tryCatch()`
+
+`useFetchError` is built on two small helpers, and they are exported so you can use the same `[error, data]` style for anything that is not an HTTP request (database queries, file reads, `JSON.parse`...). You don't need them to use `useFetchError`.
+
+Both catch the error instead of letting it be thrown, and return a tuple:
+
+- `[null, data]` if everything went well.
+- `[error, undefined]` if something failed.
+
+#### `to(promise)`: for async code
+
+Takes any promise (or anything you would `await`) and waits for it.
+
+```javascript
+import { to } from "use-fetch-error";
+
+const [error, user] = await to(db.users.findById(id));
+
+if (error) {
+  console.error("Could not load the user:", error);
+} else {
+  console.log(user.name);
+}
+```
+
+It is the same as writing:
+
+```javascript
+let error = null;
+let user;
+try {
+  user = await db.users.findById(id);
+} catch (e) {
+  error = e;
+}
+```
+
+More examples:
+
+```javascript
+// Read a file (Node.js)
+import { readFile } from "node:fs/promises";
+const [readError, content] = await to(readFile("config.json", "utf8"));
+
+// Several requests at once: fails if any of them fails
+const [error, [posts, users] = []] = await to(Promise.all([getPosts(), getUsers()]));
+```
+
+#### `tryCatch(fn, ...args)`: for sync code
+
+Calls `fn(...args)` for you and catches anything it throws.
+
+```javascript
+import { tryCatch } from "use-fetch-error";
+
+tryCatch(JSON.parse, '{"port": 3000}'); // → [null, { port: 3000 }]
+tryCatch(JSON.parse, "{ not json");     // → [SyntaxError, undefined]
+```
+
+Pass the function and its arguments **separately**: `tryCatch(JSON.parse, text)`, not `tryCatch(JSON.parse(text))`. In the second form `JSON.parse(text)` runs, and throws, before `tryCatch` can catch anything.
+
+When you need more than a single call, pass an arrow function with no arguments:
+
+```javascript
+const [error, url] = tryCatch(() => new URL(input, "https://example.com"));
+```
+
+#### With TypeScript
+
+Types are inferred, and checking the error narrows the data:
+
+```typescript
+import { to, tryCatch } from "use-fetch-error";
+
+const [error, user] = await to(getUser(id)); // user: User | undefined
+if (error) throw error;
+user.name; // user: User
+
+// The error is typed as `Error`; you can be more specific
+const [parseError, data] = tryCatch<[string], Config, SyntaxError>(JSON.parse, text);
+```
+
+The error is always an `Error`: if the code throws something else (for example `throw "oops"`), it is wrapped in `new Error("oops")`.
+
+### Development
+
+```bash
+npm install
+npm test
+```
+
+`npm test` type-checks, builds `dist/esm` and `dist/cjs` (with `.d.ts` files) and runs the tests against both builds.

package/dist/cjs/errors.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Error returned when the server answers with a status outside 200-299.
+ */
+export declare class HttpError extends Error {
+    readonly status: number;
+    readonly statusText: string;
+    readonly response: Response;
+    /** Response body (parsed as JSON when possible, otherwise text). */
+    readonly body: unknown;
+    constructor(response: Response, body: unknown);
+}
+/**
+ * Error returned when the request is aborted because `timeout` expired.
+ */
+export declare class TimeoutError extends Error {
+    readonly timeout: number;
+    constructor(timeout: number);
+}

package/dist/cjs/errors.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TimeoutError = exports.HttpError = void 0;
+/**
+ * Error returned when the server answers with a status outside 200-299.
+ */
+class HttpError extends Error {
+    constructor(response, body) {
+        super(`HTTP ${response.status} ${response.statusText}`.trim());
+        this.name = "HttpError";
+        this.status = response.status;
+        this.statusText = response.statusText;
+        this.response = response;
+        this.body = body;
+    }
+}
+exports.HttpError = HttpError;
+/**
+ * Error returned when the request is aborted because `timeout` expired.
+ */
+class TimeoutError extends Error {
+    constructor(timeout) {
+        super(`Request timed out after ${timeout} ms`);
+        this.name = "TimeoutError";
+        this.timeout = timeout;
+    }
+}
+exports.TimeoutError = TimeoutError;
+//# sourceMappingURL=errors.js.map

package/dist/cjs/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":";;;AAAA;;GAEG;AACH,MAAa,SAAU,SAAQ,KAAK;IAOlC,YAAY,QAAkB,EAAE,IAAa;QAC3C,KAAK,CAAC,QAAQ,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC;QAC/D,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;QACxB,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC;QAC9B,IAAI,CAAC,UAAU,GAAG,QAAQ,CAAC,UAAU,CAAC;QACtC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAfD,8BAeC;AAED;;GAEG;AACH,MAAa,YAAa,SAAQ,KAAK;IAGrC,YAAY,OAAe;QACzB,KAAK,CAAC,2BAA2B,OAAO,KAAK,CAAC,CAAC;QAC/C,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF;AARD,oCAQC"}

package/dist/cjs/helpers.d.ts

@@ -0,0 +1,19 @@
+import type { Result } from "./types.js";
+/** Returns `value` if it is an `Error`, otherwise wraps it in one. */
+export declare function toError(value: unknown): Error;
+/**
+ * Awaits a promise and returns a tuple `[error, data]` instead of throwing.
+ * Thrown values that are not an `Error` are wrapped in one.
+ *
+ * @example
+ * const [error, user] = await to(getUser(id));
+ */
+export declare function to<T, E extends Error = Error>(promise: PromiseLike<T>): Promise<Result<T, E>>;
+/**
+ * Runs a synchronous function and returns a tuple `[error, data]` instead of throwing.
+ * Thrown values that are not an `Error` are wrapped in one.
+ *
+ * @example
+ * const [error, config] = tryCatch(JSON.parse, text);
+ */
+export declare function tryCatch<A extends unknown[], R, E extends Error = Error>(fn: (...args: A) => R, ...args: A): Result<R, E>;

package/dist/cjs/helpers.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toError = toError;
+exports.to = to;
+exports.tryCatch = tryCatch;
+/** Returns `value` if it is an `Error`, otherwise wraps it in one. */
+function toError(value) {
+    return value instanceof Error ? value : new Error(String(value));
+}
+/**
+ * Awaits a promise and returns a tuple `[error, data]` instead of throwing.
+ * Thrown values that are not an `Error` are wrapped in one.
+ *
+ * @example
+ * const [error, user] = await to(getUser(id));
+ */
+async function to(promise) {
+    try {
+        return [null, await promise];
+    }
+    catch (error) {
+        return [toError(error), undefined];
+    }
+}
+/**
+ * Runs a synchronous function and returns a tuple `[error, data]` instead of throwing.
+ * Thrown values that are not an `Error` are wrapped in one.
+ *
+ * @example
+ * const [error, config] = tryCatch(JSON.parse, text);
+ */
+function tryCatch(fn, ...args) {
+    try {
+        return [null, fn(...args)];
+    }
+    catch (error) {
+        return [toError(error), undefined];
+    }
+}
+//# sourceMappingURL=helpers.js.map

package/dist/cjs/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../src/helpers.ts"],"names":[],"mappings":";;AAGA,0BAEC;AASD,gBAQC;AASD,4BASC;AAtCD,sEAAsE;AACtE,SAAgB,OAAO,CAAC,KAAc;IACpC,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;AACnE,CAAC;AAED;;;;;;GAMG;AACI,KAAK,UAAU,EAAE,CACtB,OAAuB;IAEvB,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC;IAC/B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,OAAO,CAAC,KAAK,CAAM,EAAE,SAAS,CAAC,CAAC;IAC1C,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,QAAQ,CACtB,EAAqB,EACrB,GAAG,IAAO;IAEV,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;IAC7B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,OAAO,CAAC,KAAK,CAAM,EAAE,SAAS,CAAC,CAAC;IAC1C,CAAC;AACH,CAAC"}

package/dist/cjs/index.d.ts

@@ -0,0 +1,4 @@
+export { useFetchError } from "./useFetchError.js";
+export { HttpError, TimeoutError } from "./errors.js";
+export { to, tryCatch } from "./helpers.js";
+export type { Result, ParseAs, UseFetchErrorOptions } from "./types.js";

package/dist/cjs/index.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tryCatch = exports.to = exports.TimeoutError = exports.HttpError = exports.useFetchError = void 0;
+var useFetchError_js_1 = require("./useFetchError.js");
+Object.defineProperty(exports, "useFetchError", { enumerable: true, get: function () { return useFetchError_js_1.useFetchError; } });
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "HttpError", { enumerable: true, get: function () { return errors_js_1.HttpError; } });
+Object.defineProperty(exports, "TimeoutError", { enumerable: true, get: function () { return errors_js_1.TimeoutError; } });
+var helpers_js_1 = require("./helpers.js");
+Object.defineProperty(exports, "to", { enumerable: true, get: function () { return helpers_js_1.to; } });
+Object.defineProperty(exports, "tryCatch", { enumerable: true, get: function () { return helpers_js_1.tryCatch; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;AAAA,uDAAmD;AAA1C,iHAAA,aAAa,OAAA;AACtB,yCAAsD;AAA7C,sGAAA,SAAS,OAAA;AAAE,yGAAA,YAAY,OAAA;AAChC,2CAA4C;AAAnC,gGAAA,EAAE,OAAA;AAAE,sGAAA,QAAQ,OAAA"}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cjs/types.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Tuple `[error, data]`. When `error` is `null`, `data` holds the value;
+ * otherwise `data` is `undefined`. Checking `error` narrows the type of `data`.
+ */
+export type Result<T, E = unknown> = [error: null, data: T] | [error: E, data: undefined];
+/** How the response body is read when the request succeeds. */
+export type ParseAs = "json" | "text" | "blob" | "arrayBuffer" | "formData" | "response";
+export interface UseFetchErrorOptions extends RequestInit {
+    /** How to read the response body. Defaults to `"json"`. */
+    parseAs?: ParseAs;
+    /** Aborts the request after this many milliseconds. */
+    timeout?: number;
+}

package/dist/cjs/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/cjs/types.js.map

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

package/dist/cjs/useFetchError.d.ts

@@ -0,0 +1,14 @@
+import type { Result, UseFetchErrorOptions } from "./types.js";
+/**
+ * Makes an HTTP request with `fetch` and never throws: it returns `[error, data]`.
+ *
+ * `error` is set when there is a network error, a timeout or abort, an HTTP
+ * status outside 200-299 (`HttpError`), or the body cannot be parsed.
+ *
+ * @template T - Expected type of the parsed body.
+ * @example
+ * const [error, post] = await useFetchError<Post>("/api/posts/1");
+ * if (error) return console.error(error);
+ * console.log(post.title);
+ */
+export declare function useFetchError<T = unknown>(input: RequestInfo | URL, options?: UseFetchErrorOptions): Promise<Result<T, Error>>;

package/dist/cjs/useFetchError.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useFetchError = useFetchError;
+const errors_js_1 = require("./errors.js");
+const helpers_js_1 = require("./helpers.js");
+async function readBody(response, parseAs) {
+    switch (parseAs) {
+        case "response":
+            return response;
+        case "text":
+            return response.text();
+        case "blob":
+            return response.blob();
+        case "arrayBuffer":
+            return response.arrayBuffer();
+        case "formData":
+            return response.formData();
+        case "json": {
+            // Empty bodies (204, 205, HEAD...) resolve to `null` instead of failing.
+            const text = await response.text();
+            return text.trim() === "" ? null : JSON.parse(text);
+        }
+        default:
+            throw new TypeError(`Unsupported parseAs value: ${String(parseAs)}`);
+    }
+}
+async function readErrorBody(response) {
+    const [, text] = await (0, helpers_js_1.to)(response.text());
+    if (text === undefined || text === "")
+        return undefined;
+    const [parseError, json] = (0, helpers_js_1.tryCatch)(JSON.parse, text);
+    return parseError ? text : json;
+}
+/**
+ * Makes an HTTP request with `fetch` and never throws: it returns `[error, data]`.
+ *
+ * `error` is set when there is a network error, a timeout or abort, an HTTP
+ * status outside 200-299 (`HttpError`), or the body cannot be parsed.
+ *
+ * @template T - Expected type of the parsed body.
+ * @example
+ * const [error, post] = await useFetchError<Post>("/api/posts/1");
+ * if (error) return console.error(error);
+ * console.log(post.title);
+ */
+async function useFetchError(input, options = {}) {
+    const { parseAs = "json", timeout, ...init } = options;
+    let timer;
+    let timedOut = false;
+    let onAbort;
+    if (timeout !== undefined) {
+        const controller = new AbortController();
+        const userSignal = init.signal;
+        if (userSignal) {
+            if (userSignal.aborted)
+                controller.abort(userSignal.reason);
+            onAbort = () => controller.abort(userSignal.reason);
+            userSignal.addEventListener("abort", onAbort, { once: true });
+        }
+        timer = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+        }, timeout);
+        init.signal = controller.signal;
+    }
+    try {
+        const [fetchError, response] = await (0, helpers_js_1.to)(fetch(input, init));
+        if (fetchError || !response) {
+            return [timedOut ? new errors_js_1.TimeoutError(timeout) : (0, helpers_js_1.toError)(fetchError), undefined];
+        }
+        if (!response.ok) {
+            return [new errors_js_1.HttpError(response, await readErrorBody(response)), undefined];
+        }
+        const [parseError, data] = await (0, helpers_js_1.to)(readBody(response, parseAs));
+        if (parseError) {
+            return [timedOut ? new errors_js_1.TimeoutError(timeout) : (0, helpers_js_1.toError)(parseError), undefined];
+        }
+        return [null, data];
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        if (onAbort)
+            options.signal?.removeEventListener("abort", onAbort);
+    }
+}
+//# sourceMappingURL=useFetchError.js.map

package/dist/cjs/useFetchError.js.map

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

package/dist/esm/errors.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Error returned when the server answers with a status outside 200-299.
+ */
+export declare class HttpError extends Error {
+    readonly status: number;
+    readonly statusText: string;
+    readonly response: Response;
+    /** Response body (parsed as JSON when possible, otherwise text). */
+    readonly body: unknown;
+    constructor(response: Response, body: unknown);
+}
+/**
+ * Error returned when the request is aborted because `timeout` expired.
+ */
+export declare class TimeoutError extends Error {
+    readonly timeout: number;
+    constructor(timeout: number);
+}

package/dist/esm/errors.js

@@ -0,0 +1,24 @@
+/**
+ * Error returned when the server answers with a status outside 200-299.
+ */
+export class HttpError extends Error {
+    constructor(response, body) {
+        super(`HTTP ${response.status} ${response.statusText}`.trim());
+        this.name = "HttpError";
+        this.status = response.status;
+        this.statusText = response.statusText;
+        this.response = response;
+        this.body = body;
+    }
+}
+/**
+ * Error returned when the request is aborted because `timeout` expired.
+ */
+export class TimeoutError extends Error {
+    constructor(timeout) {
+        super(`Request timed out after ${timeout} ms`);
+        this.name = "TimeoutError";
+        this.timeout = timeout;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/esm/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,OAAO,SAAU,SAAQ,KAAK;IAOlC,YAAY,QAAkB,EAAE,IAAa;QAC3C,KAAK,CAAC,QAAQ,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC;QAC/D,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;QACxB,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC;QAC9B,IAAI,CAAC,UAAU,GAAG,QAAQ,CAAC,UAAU,CAAC;QACtC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;IAGrC,YAAY,OAAe;QACzB,KAAK,CAAC,2BAA2B,OAAO,KAAK,CAAC,CAAC;QAC/C,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF"}

package/dist/esm/helpers.d.ts

@@ -0,0 +1,19 @@
+import type { Result } from "./types.js";
+/** Returns `value` if it is an `Error`, otherwise wraps it in one. */
+export declare function toError(value: unknown): Error;
+/**
+ * Awaits a promise and returns a tuple `[error, data]` instead of throwing.
+ * Thrown values that are not an `Error` are wrapped in one.
+ *
+ * @example
+ * const [error, user] = await to(getUser(id));
+ */
+export declare function to<T, E extends Error = Error>(promise: PromiseLike<T>): Promise<Result<T, E>>;
+/**
+ * Runs a synchronous function and returns a tuple `[error, data]` instead of throwing.
+ * Thrown values that are not an `Error` are wrapped in one.
+ *
+ * @example
+ * const [error, config] = tryCatch(JSON.parse, text);
+ */
+export declare function tryCatch<A extends unknown[], R, E extends Error = Error>(fn: (...args: A) => R, ...args: A): Result<R, E>;

package/dist/esm/helpers.js

@@ -0,0 +1,35 @@
+/** Returns `value` if it is an `Error`, otherwise wraps it in one. */
+export function toError(value) {
+    return value instanceof Error ? value : new Error(String(value));
+}
+/**
+ * Awaits a promise and returns a tuple `[error, data]` instead of throwing.
+ * Thrown values that are not an `Error` are wrapped in one.
+ *
+ * @example
+ * const [error, user] = await to(getUser(id));
+ */
+export async function to(promise) {
+    try {
+        return [null, await promise];
+    }
+    catch (error) {
+        return [toError(error), undefined];
+    }
+}
+/**
+ * Runs a synchronous function and returns a tuple `[error, data]` instead of throwing.
+ * Thrown values that are not an `Error` are wrapped in one.
+ *
+ * @example
+ * const [error, config] = tryCatch(JSON.parse, text);
+ */
+export function tryCatch(fn, ...args) {
+    try {
+        return [null, fn(...args)];
+    }
+    catch (error) {
+        return [toError(error), undefined];
+    }
+}
+//# sourceMappingURL=helpers.js.map

package/dist/esm/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../src/helpers.ts"],"names":[],"mappings":"AAEA,sEAAsE;AACtE,MAAM,UAAU,OAAO,CAAC,KAAc;IACpC,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;AACnE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,EAAE,CACtB,OAAuB;IAEvB,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC;IAC/B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,OAAO,CAAC,KAAK,CAAM,EAAE,SAAS,CAAC,CAAC;IAC1C,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,QAAQ,CACtB,EAAqB,EACrB,GAAG,IAAO;IAEV,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;IAC7B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,OAAO,CAAC,KAAK,CAAM,EAAE,SAAS,CAAC,CAAC;IAC1C,CAAC;AACH,CAAC"}

package/dist/esm/index.d.ts

@@ -0,0 +1,4 @@
+export { useFetchError } from "./useFetchError.js";
+export { HttpError, TimeoutError } from "./errors.js";
+export { to, tryCatch } from "./helpers.js";
+export type { Result, ParseAs, UseFetchErrorOptions } from "./types.js";

package/dist/esm/index.js

@@ -0,0 +1,4 @@
+export { useFetchError } from "./useFetchError.js";
+export { HttpError, TimeoutError } from "./errors.js";
+export { to, tryCatch } from "./helpers.js";
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,EAAE,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC"}

package/dist/esm/package.json

@@ -0,0 +1 @@
+{"type":"module"}

package/dist/esm/types.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Tuple `[error, data]`. When `error` is `null`, `data` holds the value;
+ * otherwise `data` is `undefined`. Checking `error` narrows the type of `data`.
+ */
+export type Result<T, E = unknown> = [error: null, data: T] | [error: E, data: undefined];
+/** How the response body is read when the request succeeds. */
+export type ParseAs = "json" | "text" | "blob" | "arrayBuffer" | "formData" | "response";
+export interface UseFetchErrorOptions extends RequestInit {
+    /** How to read the response body. Defaults to `"json"`. */
+    parseAs?: ParseAs;
+    /** Aborts the request after this many milliseconds. */
+    timeout?: number;
+}

package/dist/esm/types.js

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

package/dist/esm/types.js.map

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

package/dist/esm/useFetchError.d.ts

@@ -0,0 +1,14 @@
+import type { Result, UseFetchErrorOptions } from "./types.js";
+/**
+ * Makes an HTTP request with `fetch` and never throws: it returns `[error, data]`.
+ *
+ * `error` is set when there is a network error, a timeout or abort, an HTTP
+ * status outside 200-299 (`HttpError`), or the body cannot be parsed.
+ *
+ * @template T - Expected type of the parsed body.
+ * @example
+ * const [error, post] = await useFetchError<Post>("/api/posts/1");
+ * if (error) return console.error(error);
+ * console.log(post.title);
+ */
+export declare function useFetchError<T = unknown>(input: RequestInfo | URL, options?: UseFetchErrorOptions): Promise<Result<T, Error>>;

package/dist/esm/useFetchError.js

@@ -0,0 +1,84 @@
+import { HttpError, TimeoutError } from "./errors.js";
+import { to, toError, tryCatch } from "./helpers.js";
+async function readBody(response, parseAs) {
+    switch (parseAs) {
+        case "response":
+            return response;
+        case "text":
+            return response.text();
+        case "blob":
+            return response.blob();
+        case "arrayBuffer":
+            return response.arrayBuffer();
+        case "formData":
+            return response.formData();
+        case "json": {
+            // Empty bodies (204, 205, HEAD...) resolve to `null` instead of failing.
+            const text = await response.text();
+            return text.trim() === "" ? null : JSON.parse(text);
+        }
+        default:
+            throw new TypeError(`Unsupported parseAs value: ${String(parseAs)}`);
+    }
+}
+async function readErrorBody(response) {
+    const [, text] = await to(response.text());
+    if (text === undefined || text === "")
+        return undefined;
+    const [parseError, json] = tryCatch(JSON.parse, text);
+    return parseError ? text : json;
+}
+/**
+ * Makes an HTTP request with `fetch` and never throws: it returns `[error, data]`.
+ *
+ * `error` is set when there is a network error, a timeout or abort, an HTTP
+ * status outside 200-299 (`HttpError`), or the body cannot be parsed.
+ *
+ * @template T - Expected type of the parsed body.
+ * @example
+ * const [error, post] = await useFetchError<Post>("/api/posts/1");
+ * if (error) return console.error(error);
+ * console.log(post.title);
+ */
+export async function useFetchError(input, options = {}) {
+    const { parseAs = "json", timeout, ...init } = options;
+    let timer;
+    let timedOut = false;
+    let onAbort;
+    if (timeout !== undefined) {
+        const controller = new AbortController();
+        const userSignal = init.signal;
+        if (userSignal) {
+            if (userSignal.aborted)
+                controller.abort(userSignal.reason);
+            onAbort = () => controller.abort(userSignal.reason);
+            userSignal.addEventListener("abort", onAbort, { once: true });
+        }
+        timer = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+        }, timeout);
+        init.signal = controller.signal;
+    }
+    try {
+        const [fetchError, response] = await to(fetch(input, init));
+        if (fetchError || !response) {
+            return [timedOut ? new TimeoutError(timeout) : toError(fetchError), undefined];
+        }
+        if (!response.ok) {
+            return [new HttpError(response, await readErrorBody(response)), undefined];
+        }
+        const [parseError, data] = await to(readBody(response, parseAs));
+        if (parseError) {
+            return [timedOut ? new TimeoutError(timeout) : toError(parseError), undefined];
+        }
+        return [null, data];
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        if (onAbort)
+            options.signal?.removeEventListener("abort", onAbort);
+    }
+}
+//# sourceMappingURL=useFetchError.js.map

package/dist/esm/useFetchError.js.map

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

package/package.json

@@ -1,14 +1,50 @@
 {
   "name": "use-fetch-error",
-  "version": "1.0.3",
+  "version": "2.0.0",
   "description": "A library for error handling with [error, result] tuples using a useFetchError() function.",
   "keywords": [
     "javascript",
+    "typescript",
     "fetch",
     "handle error"
   ],
   "author": "llatzer",
   "license": "MIT",
-  "main": "src/index.js",
-  "browser": "src/index.js"
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/llatzer-dev/use-fetch-error.git"
+  },
+  "sideEffects": false,
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/cjs/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && tsc -p tsconfig.esm.json && tsc -p tsconfig.cjs.json && node scripts/write-dist-packages.mjs",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "npm run typecheck && npm run build && node --test test/esm.test.mjs test/cjs.test.cjs",
+    "prepublishOnly": "npm test"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.2"
+  }
 }

package/src/errors.ts

@@ -0,0 +1,32 @@
+/**
+ * Error returned when the server answers with a status outside 200-299.
+ */
+export class HttpError extends Error {
+  readonly status: number;
+  readonly statusText: string;
+  readonly response: Response;
+  /** Response body (parsed as JSON when possible, otherwise text). */
+  readonly body: unknown;
+
+  constructor(response: Response, body: unknown) {
+    super(`HTTP ${response.status} ${response.statusText}`.trim());
+    this.name = "HttpError";
+    this.status = response.status;
+    this.statusText = response.statusText;
+    this.response = response;
+    this.body = body;
+  }
+}
+
+/**
+ * Error returned when the request is aborted because `timeout` expired.
+ */
+export class TimeoutError extends Error {
+  readonly timeout: number;
+
+  constructor(timeout: number) {
+    super(`Request timed out after ${timeout} ms`);
+    this.name = "TimeoutError";
+    this.timeout = timeout;
+  }
+}

package/src/helpers.ts

@@ -0,0 +1,41 @@
+import type { Result } from "./types.js";
+
+/** Returns `value` if it is an `Error`, otherwise wraps it in one. */
+export function toError(value: unknown): Error {
+  return value instanceof Error ? value : new Error(String(value));
+}
+
+/**
+ * Awaits a promise and returns a tuple `[error, data]` instead of throwing.
+ * Thrown values that are not an `Error` are wrapped in one.
+ *
+ * @example
+ * const [error, user] = await to(getUser(id));
+ */
+export async function to<T, E extends Error = Error>(
+  promise: PromiseLike<T>
+): Promise<Result<T, E>> {
+  try {
+    return [null, await promise];
+  } catch (error) {
+    return [toError(error) as E, undefined];
+  }
+}
+
+/**
+ * Runs a synchronous function and returns a tuple `[error, data]` instead of throwing.
+ * Thrown values that are not an `Error` are wrapped in one.
+ *
+ * @example
+ * const [error, config] = tryCatch(JSON.parse, text);
+ */
+export function tryCatch<A extends unknown[], R, E extends Error = Error>(
+  fn: (...args: A) => R,
+  ...args: A
+): Result<R, E> {
+  try {
+    return [null, fn(...args)];
+  } catch (error) {
+    return [toError(error) as E, undefined];
+  }
+}

package/src/index.ts

@@ -1,80 +1,4 @@
-const symbol = Symbol("result");
-
-/**
- * Interface that extends the native `Function` prototype
- * to include a method that handles errors and returns a tuple
- * containing the error and result.
- */
-interface FunctionWithSymbol extends Function {
-  /**
-   * Executes the function and returns a tuple `[error, result]`.
-   * @param {...any[]} args - Arguments to pass to the function.
-   * @returns {[any, any]} A tuple containing `null` and the result if successful, or the error and `undefined` if it throws.
-   */
-  [symbol](...args: any[]): [any, any];
-}
-
-Function.prototype[symbol] = function (
-  this: FunctionWithSymbol,
-  ...args: any[]
-): [any, any] {
-  try {
-    const result = this.apply(this, args);
-    return [null, result];
-  } catch (error) {
-    return [error, undefined];
-  }
-};
-
-/**
- * Interface that extends the native `Promise` prototype
- * to include a method that handles promise rejections and
- * resolves to a tuple `[error, result]`.
- *
- * @template T - The type of the resolved value of the promise.
- */
-interface PromiseWithSymbol<T> extends Promise<T> {
-  /**
-   * Resolves the promise and returns a tuple `[error, result]`.
-   * @returns {Promise<[any, T | undefined]>} A promise that resolves with a tuple containing `null` and the result if successful, or the error and `undefined` if rejected.
-   */
-  [symbol](): Promise<[any, T | undefined]>;
-}
-
-Promise.prototype[symbol] = async function <T>(
-  this: PromiseWithSymbol<T>
-): Promise<[any, T | undefined]> {
-  try {
-    const result = await this;
-    return [null, result];
-  } catch (error) {
-    return [error, undefined];
-  }
-};
-
-/**
- * Fetches a URL and handles both network errors and JSON parsing errors.
- *
- * @template T - The expected data type of the parsed JSON response.
- * @param {string} url - The URL to fetch.
- * @param {RequestInit} [options={}] - Optional configuration for the fetch request.
- * @returns {Promise<[any, T | undefined]>} A promise that resolves with a tuple containing either the error and `undefined` if something went wrong, or `null` and the parsed JSON data if successful.
- */
-export async function useFetchError<T>(
-  url: string,
-  options: RequestInit = {}
-): Promise<[any, T | undefined]> {
-  const [error, response] = await fetch(url, options)[symbol]();
-
-  if (error) {
-    return [error, undefined]; // Retorna el error si ocurrió
-  }
-
-  const [parseError, data] = await (response as Response).json()[symbol]();
-
-  if (parseError) {
-    return [parseError, undefined]; // Retorna el error al parsear el JSON
-  }
-
-  return [null, data]; // Retorna el resultado si todo fue bien
-}
+export { useFetchError } from "./useFetchError.js";
+export { HttpError, TimeoutError } from "./errors.js";
+export { to, tryCatch } from "./helpers.js";
+export type { Result, ParseAs, UseFetchErrorOptions } from "./types.js";

package/src/types.ts

@@ -0,0 +1,23 @@
+/**
+ * Tuple `[error, data]`. When `error` is `null`, `data` holds the value;
+ * otherwise `data` is `undefined`. Checking `error` narrows the type of `data`.
+ */
+export type Result<T, E = unknown> =
+  | [error: null, data: T]
+  | [error: E, data: undefined];
+
+/** How the response body is read when the request succeeds. */
+export type ParseAs =
+  | "json"
+  | "text"
+  | "blob"
+  | "arrayBuffer"
+  | "formData"
+  | "response";
+
+export interface UseFetchErrorOptions extends RequestInit {
+  /** How to read the response body. Defaults to `"json"`. */
+  parseAs?: ParseAs;
+  /** Aborts the request after this many milliseconds. */
+  timeout?: number;
+}

package/src/useFetchError.ts

@@ -0,0 +1,91 @@
+import { HttpError, TimeoutError } from "./errors.js";
+import { to, toError, tryCatch } from "./helpers.js";
+import type { ParseAs, Result, UseFetchErrorOptions } from "./types.js";
+
+async function readBody(response: Response, parseAs: ParseAs): Promise<unknown> {
+  switch (parseAs) {
+    case "response":
+      return response;
+    case "text":
+      return response.text();
+    case "blob":
+      return response.blob();
+    case "arrayBuffer":
+      return response.arrayBuffer();
+    case "formData":
+      return response.formData();
+    case "json": {
+      // Empty bodies (204, 205, HEAD...) resolve to `null` instead of failing.
+      const text = await response.text();
+      return text.trim() === "" ? null : JSON.parse(text);
+    }
+    default:
+      throw new TypeError(`Unsupported parseAs value: ${String(parseAs)}`);
+  }
+}
+
+async function readErrorBody(response: Response): Promise<unknown> {
+  const [, text] = await to<string>(response.text());
+  if (text === undefined || text === "") return undefined;
+  const [parseError, json] = tryCatch(JSON.parse, text);
+  return parseError ? text : json;
+}
+
+/**
+ * Makes an HTTP request with `fetch` and never throws: it returns `[error, data]`.
+ *
+ * `error` is set when there is a network error, a timeout or abort, an HTTP
+ * status outside 200-299 (`HttpError`), or the body cannot be parsed.
+ *
+ * @template T - Expected type of the parsed body.
+ * @example
+ * const [error, post] = await useFetchError<Post>("/api/posts/1");
+ * if (error) return console.error(error);
+ * console.log(post.title);
+ */
+export async function useFetchError<T = unknown>(
+  input: RequestInfo | URL,
+  options: UseFetchErrorOptions = {}
+): Promise<Result<T, Error>> {
+  const { parseAs = "json", timeout, ...init } = options;
+
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let timedOut = false;
+  let onAbort: (() => void) | undefined;
+
+  if (timeout !== undefined) {
+    const controller = new AbortController();
+    const userSignal = init.signal;
+    if (userSignal) {
+      if (userSignal.aborted) controller.abort(userSignal.reason);
+      onAbort = () => controller.abort(userSignal.reason);
+      userSignal.addEventListener("abort", onAbort, { once: true });
+    }
+    timer = setTimeout(() => {
+      timedOut = true;
+      controller.abort();
+    }, timeout);
+    init.signal = controller.signal;
+  }
+
+  try {
+    const [fetchError, response] = await to(fetch(input, init));
+    if (fetchError || !response) {
+      return [timedOut ? new TimeoutError(timeout as number) : toError(fetchError), undefined];
+    }
+
+    if (!response.ok) {
+      return [new HttpError(response, await readErrorBody(response)), undefined];
+    }
+
+    const [parseError, data] = await to(readBody(response, parseAs));
+    if (parseError) {
+      return [timedOut ? new TimeoutError(timeout as number) : toError(parseError), undefined];
+    }
+
+    return [null, data as T];
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+    if (onAbort) options.signal?.removeEventListener("abort", onAbort);
+  }
+}

package/src/index.js

@@ -1,58 +0,0 @@
-const symbolResult = Symbol("result");
-
-/**
- * Extends the `Function` prototype to include a method
- * that handles errors and returns a tuple `[error, result]`.
- *
- * @param {...any[]} args - The arguments to be passed to the function.
- * @returns {[any, any]} A tuple with `null` and the result if the function executes successfully,
- * or the error and `undefined` if an exception occurs.
- */
-Function.prototype[symbolResult] = function (...args) {
-  try {
-    const result = this.apply(this, args);
-    return [null, result];
-  } catch (error) {
-    return [error, undefined];
-  }
-};
-
-/**
- * Extends the `Promise` prototype to include a method
- * that handles promise errors and returns a tuple `[error, result]`.
- *
- * @returns {Promise<[any, any]>} A promise that resolves with a tuple containing `null` and the result
- * if the promise resolves successfully, or the error and `undefined` if it is rejected.
- */
-Promise.prototype[symbolResult] = async function () {
-  try {
-    const result = await this;
-    return [null, result];
-  } catch (error) {
-    return [error, undefined];
-  }
-};
-
-/**
- * Makes an HTTP request using `fetch` and handles both network errors and JSON parsing errors.
- *
- * @param {string} url - The URL to which the request will be made.
- * @param {RequestInit} [options={}] - Optional options to configure the `fetch` request.
- * @returns {Promise<[any, any]>} A promise that resolves with a tuple containing the error and `undefined` if an error occurs,
- * or `null` and the parsed data if the request and JSON parsing are successful.
- */
-async function useFetchError(url, options = {}) {
-  const [error, response] = await fetch(url, options)[symbolResult]();
-
-  if (error) {
-    return [error, undefined]; // Returns the error if one occurred
-  }
-
-  const [parseError, data] = await response.json()[symbolResult]();
-
-  if (parseError) {
-    return [parseError, undefined]; // Returns the error when parsing JSON
-  }
-
-  return [null, data]; // Returns the result if everything went well
-}