feat: Serialize errors as JSON in Response body (#7)

* Initial plan

* Implement JSON error serialization in Response body

Co-authored-by: nzakas <38546+nzakas@users.noreply.github.com>

* Add safety checks for circular references and non-serializable properties

Co-authored-by: nzakas <38546+nzakas@users.noreply.github.com>

* Refactor to eliminate code duplication

Co-authored-by: nzakas <38546+nzakas@users.noreply.github.com>

* docs: Update README with error serialization examples

Co-authored-by: nzakas <38546+nzakas@users.noreply.github.com>

* Add Content-Type: application/json header to error responses

Co-authored-by: nzakas <38546+nzakas@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: nzakas <38546+nzakas@users.noreply.github.com>

Author: Copilot

README.md

@@ -40,6 +40,11 @@ if (response.ok) {
 	// the ERROR_STATUS indicates it's a caught error
 	console.error("Error:", response.statusText);
 	// "This operation was aborted"
+
+	// You can also access the error details from the response body
+	const errorDetails = await response.json();
+	console.error("Error details:", errorDetails);
+	// { message: "This operation was aborted", stack: "..." }
 } else {
 	// Handle HTTP errors (non-2xx status codes)
 	console.error(`HTTP Error: ${response.status} ${response.statusText}`);
@@ -66,6 +71,10 @@ if (response.ok) {
 	console.log("Success!");
 } else if (response.status === ERROR_STATUS) {
 	console.error("Error:", response.statusText);
+
+	// Access detailed error information from the response body
+	const errorDetails = await response.json();
+	console.error("Error details:", errorDetails);
 } else {
 	// Handle HTTP errors (non-2xx status codes)
 	console.error(`HTTP Error: ${response.status} ${response.statusText}`);
@@ -87,6 +96,10 @@ if (response.ok) {
 	console.log(data);
 } else if (response.status === ERROR_STATUS) {
 	console.error("Error:", response.statusText);
+
+	// Get detailed error information from the response body
+	const errorDetails = await response.json();
+	console.error("Error details:", errorDetails);
 } else {
 	// Handle HTTP errors (non-2xx status codes)
 	console.error(`HTTP Error: ${response.status} ${response.statusText}`);
@@ -103,6 +116,55 @@ When a fetch operation fails (network error, abort signal, etc.), instead of rej
 
 - `status`: `ERROR_STATUS` (10001)
 - `statusText`: The error message
+- `body`: JSON-serialized error details
+
+### Error Body Serialization
+
+The error details are serialized as JSON in the response body, making it easy to access structured error information:
+
+- **String errors**: Serialized as `{ message: "error string" }`
+- **Error objects**: All properties (including `message`, `stack`, and custom properties) are extracted and serialized
+
+**Example with Error object:**
+
+```javascript
+import { safeFetch, ERROR_STATUS } from "@humanwhocodes/safe-fetch";
+
+const response = await safeFetch("https://invalid-domain.example");
+
+if (response.status === ERROR_STATUS) {
+	const error = await response.json();
+	console.log(error.message); // "Failed to fetch"
+	console.log(error.stack);   // Stack trace
+}
+```
+
+**Example with custom error properties:**
+
+```javascript
+const mockFetch = async () => {
+	const error = new Error("Database connection failed");
+	error.code = "DB_CONN_ERROR";
+	error.retryAfter = 5000;
+	throw error;
+};
+
+const safeMockFetch = createSafeFetch(mockFetch);
+const response = await safeMockFetch("https://api.example.com/data");
+
+if (response.status === ERROR_STATUS) {
+	const error = await response.json();
+	console.log(error.message);    // "Database connection failed"
+	console.log(error.code);       // "DB_CONN_ERROR"
+	console.log(error.retryAfter); // 5000
+}
+```
+
+**Safety features:**
+
+- Circular references are handled gracefully with a fallback to a simple message format
+- Non-serializable properties (functions, symbols) are automatically filtered out
+- Property access errors are caught and handled
 
 ## License
 

src/index.js

@@ -19,12 +19,53 @@ export const ERROR_STATUS = 10001;
 export function createSafeFetch(fetch) {
 	return (url, init) => {
 		return fetch(url, init).catch(error => {
+			// Serialize error to JSON
+			/** @type {Record<string, any>} */
+			let errorObject;
+			const errorMessage =
+				typeof error === "string" ? error : error.message || "Unknown error";
+
+			if (typeof error === "string") {
+				errorObject = { message: error };
+			} else {
+				// Extract all properties from the error object
+				errorObject = {};
+				const propertyNames = Object.getOwnPropertyNames(error);
+
+				for (const name of propertyNames) {
+					try {
+						const value = error[name];
+
+						// Skip functions and symbols as they can't be serialized
+						if (
+							typeof value !== "function" &&
+							typeof value !== "symbol"
+						) {
+							errorObject[name] = value;
+						}
+					} catch {
+						// Skip properties that throw on access
+					}
+				}
+			}
+
+			// Safely stringify with circular reference handling
+			let body;
+
+			try {
+				body = JSON.stringify(errorObject);
+			} catch {
+				// Fallback if serialization fails (e.g., circular references)
+				body = JSON.stringify({ message: errorMessage });
+			}
+
 			// Create a custom Response-like object since ERROR_STATUS is out of valid range
-			const statusText =
-				typeof error === "string" ? error : error.message;
-			const response = new Response(null, {
+			const response = new Response(body, {
 				status: 599,
-				statusText,
+				statusText: errorMessage,
+				headers: {
+					"Content-Type": "application/json",
+				},
 			});
 
 			// Override the status property with a custom value

tests/index.js

@@ -126,6 +126,129 @@ describe("createSafeFetch", () => {
 		assert.strictEqual(response.status, 10001);
 		assert.strictEqual(response.statusText, errorMessage);
 	});
+
+	it("should serialize string errors as JSON in response body", async () => {
+		const errorMessage = "String error message";
+		const mockFetch = async () => {
+			throw errorMessage;
+		};
+		const safe = createSafeFetch(mockFetch);
+		const response = await safe("https://example.com");
+
+		const body = await response.json();
+
+		assert.deepStrictEqual(body, { message: errorMessage });
+	});
+
+	it("should serialize Error object properties as JSON in response body", async () => {
+		const errorMessage = "Network error occurred";
+		const mockFetch = async () => {
+			throw new Error(errorMessage);
+		};
+		const safe = createSafeFetch(mockFetch);
+		const response = await safe("https://example.com");
+
+		const body = await response.json();
+
+		assert.strictEqual(body.message, errorMessage);
+		assert.ok("stack" in body);
+	});
+
+	it("should serialize custom error object with additional properties", async () => {
+		const mockFetch = async () => {
+			const error = new Error("Custom error");
+			error.code = "ERR_CUSTOM";
+			error.statusCode = 500;
+			throw error;
+		};
+		const safe = createSafeFetch(mockFetch);
+		const response = await safe("https://example.com");
+
+		const body = await response.json();
+
+		assert.strictEqual(body.message, "Custom error");
+		assert.strictEqual(body.code, "ERR_CUSTOM");
+		assert.strictEqual(body.statusCode, 500);
+		assert.ok("stack" in body);
+	});
+
+	it("should serialize TypeError properties as JSON in response body", async () => {
+		const errorMessage = "Failed to fetch";
+		const mockFetch = async () => {
+			throw new TypeError(errorMessage);
+		};
+		const safe = createSafeFetch(mockFetch);
+		const response = await safe("https://example.com");
+
+		const body = await response.json();
+
+		assert.strictEqual(body.message, errorMessage);
+		assert.ok("stack" in body);
+	});
+
+	it("should serialize plain object errors as JSON in response body", async () => {
+		const errorObject = {
+			message: "Plain object error",
+			code: 123,
+			details: "Some details",
+		};
+		const mockFetch = async () => {
+			throw errorObject;
+		};
+		const safe = createSafeFetch(mockFetch);
+		const response = await safe("https://example.com");
+
+		const body = await response.json();
+
+		assert.deepStrictEqual(body, errorObject);
+	});
+
+	it("should handle circular references in error objects", async () => {
+		const mockFetch = async () => {
+			const error = new Error("Circular reference error");
+			error.self = error; // Create circular reference
+			throw error;
+		};
+		const safe = createSafeFetch(mockFetch);
+		const response = await safe("https://example.com");
+
+		const body = await response.json();
+
+		// Should fallback to simple message format
+		assert.strictEqual(body.message, "Circular reference error");
+	});
+
+	it("should skip non-serializable properties like functions", async () => {
+		const mockFetch = async () => {
+			const error = new Error("Error with function");
+			error.myFunction = () => {
+				return "test";
+			};
+			error.normalProp = "value";
+			throw error;
+		};
+		const safe = createSafeFetch(mockFetch);
+		const response = await safe("https://example.com");
+
+		const body = await response.json();
+
+		assert.strictEqual(body.message, "Error with function");
+		assert.strictEqual(body.normalProp, "value");
+		assert.ok(!("myFunction" in body));
+	});
+
+	it("should set Content-Type header to application/json", async () => {
+		const mockFetch = async () => {
+			throw new Error("Test error");
+		};
+		const safe = createSafeFetch(mockFetch);
+		const response = await safe("https://example.com");
+
+		assert.strictEqual(
+			response.headers.get("Content-Type"),
+			"application/json",
+		);
+	});
 });
 
 describe("safeFetch", () => {