@marianmeres/http-utils 2.0.1 → 2.1.0

package/README.md

@@ -1,5 +1,9 @@
 # @marianmeres/http-utils
 
+[![NPM version](https://img.shields.io/npm/v/@marianmeres/http-utils)](https://www.npmjs.com/package/@marianmeres/http-utils)
+[![JSR version](https://jsr.io/badges/@marianmeres/http-utils)](https://jsr.io/@marianmeres/http-utils)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 Opinionated, lightweight HTTP client wrapper for `fetch` with type-safe errors and convenient defaults.
 
 ## Features
@@ -64,186 +68,69 @@ try {
 }
 ```
 
-## API Reference
+## API Overview
 
 ### `createHttpApi(base?, defaults?, errorExtractor?)`
 
 Creates an HTTP API client.
 
-**Parameters:**
-- `base` - Optional base URL for all requests
-- `defaults` - Optional default params (headers, credentials, etc.) or async function returning defaults
-- `errorExtractor` - Optional global error message extractor function
-
-**Returns:** Object with methods: `get`, `post`, `put`, `patch`, `del`, `url`, `base`
-
-### HTTP Methods
-
-All methods return the parsed response body (JSON if possible) or throw `HttpError` on failure.
-
-**New Options API (recommended):**
 ```ts
-// GET with options
-await api.get(path, {
-  params?: { headers?, signal?, credentials?, raw?, assert?, token? },
-  respHeaders?: {},
-  errorExtractor?: (body, response) => string
-});
-
-// POST/PUT/PATCH/DELETE with options
-await api.post(path, {
-  data?: any,  // Request body
-  params?: { headers?, signal?, credentials?, raw?, assert?, token? },
-  respHeaders?: {},
-  errorExtractor?: (body, response) => string
+const api = createHttpApi("https://api.example.com", {
+  headers: { "Authorization": "Bearer token" }
 });
 ```
 
-**Legacy API (still supported):**
-```ts
-// GET
-await api.get(path, params?, respHeaders?, errorExtractor?)
-
-// POST, PUT, PATCH, DELETE
-await api.post(path, data?, params?, respHeaders?, errorExtractor?)
-```
-
-**Common params:**
-- `headers` - Custom headers object
-- `token` - Bearer token (auto-adds `Authorization: Bearer {token}`)
-- `signal` - AbortSignal for cancellation
-- `credentials` - `'omit' | 'same-origin' | 'include'`
-- `raw` - Return raw Response object instead of parsed body
-- `assert` - Set to `false` to disable throwing on errors
-
-### Response Headers
-
-Access response headers by passing a respHeaders object:
-
-```ts
-// New API
-const headers = {};
-const data = await api.get("/users", { respHeaders: headers });
-
-console.log(headers.__http_status_code__); // 200
-console.log(headers["content-type"]);      // "application/json"
-
-// Legacy API
-const legacyHeaders = {};
-const data2 = await api.get("/users", {}, legacyHeaders);
-```
-
-### Error Classes
-
-Well-known HTTP errors have specific classes:
-
-**Client Errors (4xx):**
-- `BadRequest` (400)
-- `Unauthorized` (401)
-- `Forbidden` (403)
-- `NotFound` (404)
-- `MethodNotAllowed` (405)
-- `RequestTimeout` (408)
-- `Conflict` (409)
-- `Gone` (410)
-- `LengthRequired` (411)
-- `ImATeapot` (418)
-- `UnprocessableContent` (422)
-- `TooManyRequests` (429)
-
-**Server Errors (5xx):**
-- `InternalServerError` (500)
-- `NotImplemented` (501)
-- `BadGateway` (502)
-- `ServiceUnavailable` (503)
-
-All errors extend `HttpError` with properties:
-- `status` - HTTP status code
-- `statusText` - HTTP status text
-- `body` - Response body (auto-parsed as JSON if possible)
-- `cause` - Error details/context
-
-### HTTP Status Codes
-
-Access status codes via `HTTP_STATUS`:
-
-```ts
-import { HTTP_STATUS } from "@marianmeres/http-utils";
-
-// By category
-HTTP_STATUS.SUCCESS.OK.CODE          // 200
-HTTP_STATUS.ERROR_CLIENT.NOT_FOUND.CODE  // 404
-
-// Direct shortcuts
-HTTP_STATUS.OK              // 200
-HTTP_STATUS.NOT_FOUND       // 404
-HTTP_STATUS.INTERNAL_SERVER_ERROR  // 500
-
-// Lookup by code
-const info = HTTP_STATUS.findByCode(404);
-// { CODE: 404, TEXT: "Not Found", _TYPE: "ERROR_CLIENT", _KEY: "NOT_FOUND" }
-```
-
-## Advanced Usage
-
-### Error Message Extraction
-
-Customize how error messages are extracted from failed responses:
-
-```ts
-// Global default
-createHttpApi.defaultErrorMessageExtractor = (body, response) => {
-  return body.error?.message || response.statusText;
-};
-
-// Per-instance
-const api = createHttpApi(null, null, (body) => body.customError);
-
-// Per-request
-await api.get("/path", null, null, (body) => body.message);
-```
-
-Priority: per-request → per-instance → global → built-in fallback
-
-### Dynamic Configuration
+### HTTP Methods
 
 ```ts
-const api = createHttpApi("https://api.example.com", async () => {
-  const token = await getToken(); // Fetch fresh token
-  return { headers: { "Authorization": `Bearer ${token}` } };
+// GET (new options API)
+const data = await api.get("/users", {
+  params: { headers: { "X-Custom": "value" } },
+  respHeaders: {}
 });
-```
 
-### Raw Response Access
+// POST/PUT/PATCH/DELETE (new options API)
+await api.post("/users", {
+  data: { name: "John" },
+  params: { token: "bearer-token" }
+});
 
-```ts
-const response = await api.get("/users", { raw: true });
-console.log(response instanceof Response); // true
-const data = await response.json();
+// Legacy API still supported
+const data = await api.get("/users", { headers: { "X-Custom": "value" } });
+await api.post("/users", { name: "John" });
 ```
 
-### Non-Throwing Errors
+### Error Handling
 
 ```ts
-const data = await api.get("/might-fail", { assert: false });
-if (data.error) {
-  console.log("Request failed:", data.error.message);
+import { HTTP_ERROR, NotFound } from "@marianmeres/http-utils";
+
+try {
+  await api.get("/resource");
+} catch (error) {
+  if (error instanceof NotFound) {
+    console.log("Not found:", error.body);
+  }
+  // All errors have: status, statusText, body, cause
 }
 ```
 
-### AbortController Support
+### Key Features
 
-```ts
-const controller = new AbortController();
+- **Auto JSON**: Response bodies are automatically parsed as JSON
+- **Bearer tokens**: Use `token` param to auto-add `Authorization: Bearer` header
+- **Response headers**: Pass `respHeaders: {}` to capture response headers
+- **Raw response**: Use `raw: true` to get the raw Response object
+- **Non-throwing**: Use `assert: false` to prevent throwing on errors
+- **AbortController**: Pass `signal` for request cancellation
 
-setTimeout(() => controller.abort(), 5000);
+## Full API Reference
 
-await api.get("/slow-endpoint", { signal: controller.signal });
-```
+For complete API documentation including all error classes, HTTP status codes, types, and utilities, see **[API.md](API.md)**.
 
 ## Utilities
 
-### `getErrorMessage(error, stripErrorPrefix?)`
+### `getErrorMessage(error)`
 
 Extracts human-readable messages from any error format:
 
@@ -265,9 +152,5 @@ Manually create HTTP errors:
 import { createHttpError } from "@marianmeres/http-utils";
 
 const error = createHttpError(404, "User not found", { userId: 123 });
-throw error;
-```
-
-## License
-
-MIT
+throw error; // instanceof NotFound
+```

package/dist/api.d.ts

@@ -1,34 +1,74 @@
+/**
+ * @module api
+ *
+ * HTTP API client factory and related types.
+ * Provides a convenient wrapper over the native `fetch` API with sensible defaults.
+ */
+/**
+ * Request body data type.
+ * Supports JSON-serializable objects, FormData for file uploads, or raw strings.
+ */
+export type RequestData = Record<string, unknown> | FormData | string | null;
 interface BaseParams {
     method: 'GET' | 'POST' | 'PATCH' | 'DELETE' | 'PUT';
     path: string;
 }
-interface FetchParams {
-    data?: any;
+/**
+ * Parameters for fetch requests.
+ */
+export interface FetchParams {
+    /** Request body data (automatically JSON stringified unless FormData). */
+    data?: RequestData;
+    /** Bearer token (auto-adds `Authorization: Bearer {token}` header). */
     token?: string | null;
+    /** Custom request headers. */
     headers?: Record<string, string> | null;
+    /** AbortSignal for request cancellation. */
     signal?: AbortSignal;
+    /** Credentials mode for the request. */
     credentials?: 'omit' | 'same-origin' | 'include' | null;
+    /** If true, returns the raw Response object instead of parsed body. */
     raw?: boolean | null;
+    /** If false, does not throw on HTTP errors (default: true). */
     assert?: boolean | null;
 }
 type BaseFetchParams = BaseParams & FetchParams;
-type ErrorMessageExtractor = (body: any, response: Response) => string;
-type ResponseHeaders = Record<string, string | number>;
 /**
- * Options for HTTP GET requests (new cleaner API).
+ * Function to extract error messages from failed HTTP responses.
+ * @param body - The parsed response body.
+ * @param response - The raw Response object.
+ * @returns A human-readable error message string.
+ */
+export type ErrorMessageExtractor = (body: unknown, response: Response) => string;
+/**
+ * Object to receive response headers after a request completes.
+ * Will be mutated to include all response headers plus special keys:
+ * - `__http_status_code__`: The HTTP status code
+ * - `__http_status_text__`: The HTTP status text
+ */
+export type ResponseHeaders = Record<string, string | number>;
+/**
+ * Options for HTTP GET requests using the new cleaner API.
  */
 export interface GetOptions {
+    /** Fetch parameters (headers, token, signal, credentials, raw, assert). */
     params?: FetchParams;
+    /** Object to receive response headers (will be mutated). */
     respHeaders?: ResponseHeaders | null;
+    /** Custom error message extractor for this request. */
     errorExtractor?: ErrorMessageExtractor | null;
 }
 /**
- * Options for HTTP POST/PUT/PATCH/DELETE requests (new cleaner API).
+ * Options for HTTP POST/PUT/PATCH/DELETE requests using the new cleaner API.
  */
 export interface DataOptions {
-    data?: any;
+    /** Request body data. */
+    data?: RequestData;
+    /** Fetch parameters (headers, token, signal, credentials, raw, assert). */
     params?: FetchParams;
+    /** Object to receive response headers (will be mutated). */
     respHeaders?: ResponseHeaders | null;
+    /** Custom error message extractor for this request. */
     errorExtractor?: ErrorMessageExtractor | null;
 }
 /**
@@ -53,7 +93,7 @@ export declare class HttpApi {
      * });
      * ```
      */
-    get(path: string, options: GetOptions): Promise<any>;
+    get(path: string, options: GetOptions): Promise<unknown>;
     /**
      * Performs a GET request (legacy API).
      *
@@ -65,7 +105,7 @@ export declare class HttpApi {
      * @returns The response body (auto-parsed as JSON if possible), or Response if `raw: true`.
      * @throws {HttpError} When the response is not OK and `assert` is true (default).
      */
-    get(path: string, params?: FetchParams, respHeaders?: ResponseHeaders | null, errorMessageExtractor?: ErrorMessageExtractor | null, _dumpParams?: boolean): Promise<any>;
+    get(path: string, params?: FetchParams, respHeaders?: ResponseHeaders | null, errorMessageExtractor?: ErrorMessageExtractor | null, _dumpParams?: boolean): Promise<unknown>;
     /**
      * Performs a POST request (new options API - recommended).
      *
@@ -83,7 +123,7 @@ export declare class HttpApi {
      * });
      * ```
      */
-    post(path: string, options: DataOptions): Promise<any>;
+    post(path: string, options: DataOptions): Promise<unknown>;
     /**
      * Performs a POST request (legacy API).
      *
@@ -96,23 +136,23 @@ export declare class HttpApi {
      * @returns The response body (auto-parsed as JSON if possible), or Response if `raw: true`.
      * @throws {HttpError} When the response is not OK and `assert` is true (default).
      */
-    post(path: string, data?: any, params?: FetchParams, respHeaders?: ResponseHeaders | null, errorMessageExtractor?: ErrorMessageExtractor | null, _dumpParams?: boolean): Promise<any>;
+    post(path: string, data?: RequestData, params?: FetchParams, respHeaders?: ResponseHeaders | null, errorMessageExtractor?: ErrorMessageExtractor | null, _dumpParams?: boolean): Promise<unknown>;
     /** Performs a PUT request (new options API). @see post */
-    put(path: string, options: DataOptions): Promise<any>;
+    put(path: string, options: DataOptions): Promise<unknown>;
     /** Performs a PUT request (legacy API). @see post */
-    put(path: string, data?: any, params?: FetchParams, respHeaders?: ResponseHeaders | null, errorMessageExtractor?: ErrorMessageExtractor | null, _dumpParams?: boolean): Promise<any>;
+    put(path: string, data?: RequestData, params?: FetchParams, respHeaders?: ResponseHeaders | null, errorMessageExtractor?: ErrorMessageExtractor | null, _dumpParams?: boolean): Promise<unknown>;
     /** Performs a PATCH request (new options API). @see post */
-    patch(path: string, options: DataOptions): Promise<any>;
+    patch(path: string, options: DataOptions): Promise<unknown>;
     /** Performs a PATCH request (legacy API). @see post */
-    patch(path: string, data?: any, params?: FetchParams, respHeaders?: ResponseHeaders | null, errorMessageExtractor?: ErrorMessageExtractor | null, _dumpParams?: boolean): Promise<any>;
+    patch(path: string, data?: RequestData, params?: FetchParams, respHeaders?: ResponseHeaders | null, errorMessageExtractor?: ErrorMessageExtractor | null, _dumpParams?: boolean): Promise<unknown>;
     /**
      * Performs a DELETE request (new options API).
      * Note: Request body in DELETE is allowed per HTTP spec.
      * @see post
      */
-    del(path: string, options: DataOptions): Promise<any>;
+    del(path: string, options: DataOptions): Promise<unknown>;
     /** Performs a DELETE request (legacy API). @see post */
-    del(path: string, data?: any, params?: FetchParams, respHeaders?: ResponseHeaders | null, errorMessageExtractor?: ErrorMessageExtractor | null, _dumpParams?: boolean): Promise<any>;
+    del(path: string, data?: RequestData, params?: FetchParams, respHeaders?: ResponseHeaders | null, errorMessageExtractor?: ErrorMessageExtractor | null, _dumpParams?: boolean): Promise<unknown>;
     /**
      * Helper method to build the full URL from a path.
      *

package/dist/api.js

@@ -1,6 +1,10 @@
+/**
+ * @module api
+ *
+ * HTTP API client factory and related types.
+ * Provides a convenient wrapper over the native `fetch` API with sensible defaults.
+ */
 import { createHttpError } from './error.js';
-// This is an opinionated HTTP client wrapper and may not be suitable for every use case.
-// It provides convenient defaults over plain fetch calls without adding unnecessary abstractions.
 /**
  * Deep merges two objects. Later properties overwrite earlier properties.
  */
@@ -8,23 +12,25 @@ function deepMerge(target, source) {
     const output = { ...target };
     if (isObject(target) && isObject(source)) {
         Object.keys(source).forEach(key => {
-            if (isObject(source[key])) {
-                if (!(key in target)) {
-                    Object.assign(output, { [key]: source[key] });
+            const sourceVal = source[key];
+            const targetVal = target[key];
+            if (isObject(sourceVal)) {
+                if (!(key in target) || !isObject(targetVal)) {
+                    Object.assign(output, { [key]: sourceVal });
                 }
                 else {
-                    output[key] = deepMerge(target[key], source[key]);
+                    output[key] = deepMerge(targetVal, sourceVal);
                 }
             }
             else {
-                Object.assign(output, { [key]: source[key] });
+                Object.assign(output, { [key]: sourceVal });
             }
         });
     }
     return output;
 }
 function isObject(item) {
-    return item && typeof item === 'object' && !Array.isArray(item);
+    return item !== null && typeof item === 'object' && !Array.isArray(item);
 }
 const _fetchRaw = async ({ method, path, data = null, token = null, headers = null, signal, credentials, }) => {
     const normalizedHeaders = Object.entries(headers || {}).reduce((m, [k, v]) => ({ ...m, [k.toLowerCase()]: v }), {});
@@ -84,13 +90,14 @@ const _fetch = async (params, respHeaders = null, errorMessageExtractor = null,
             createHttpApi.defaultErrorMessageExtractor ?? // static default
             // educated guess fallback
             function (_body, _response) {
-                let msg = 
+                const b = _body;
+                let msg = String(
                 // try opinionated convention first
-                _body?.error?.message ||
-                    _body?.message ||
-                    _body?.error ||
+                b?.error?.message ||
+                    b?.message ||
+                    b?.error ||
                     _response?.statusText ||
-                    'Unknown error';
+                    'Unknown error');
                 if (msg.length > 255)
                     msg = `[Shortened]: ${msg.slice(0, 255)}`;
                 return msg;
@@ -161,10 +168,13 @@ export class HttpApi {
         let fetchParams;
         let headers = null;
         let extractor = null;
-        if (dataOrOptions && ('data' in dataOrOptions ||
-            'params' in dataOrOptions ||
-            'respHeaders' in dataOrOptions ||
-            'errorExtractor' in dataOrOptions)) {
+        if (dataOrOptions &&
+            typeof dataOrOptions === 'object' &&
+            !(dataOrOptions instanceof FormData) &&
+            ('data' in dataOrOptions ||
+                'params' in dataOrOptions ||
+                'respHeaders' in dataOrOptions ||
+                'errorExtractor' in dataOrOptions)) {
             // New options API
             const opts = dataOrOptions;
             data = opts.data ?? null;
@@ -187,10 +197,13 @@ export class HttpApi {
         let fetchParams;
         let headers = null;
         let extractor = null;
-        if (dataOrOptions && ('data' in dataOrOptions ||
-            'params' in dataOrOptions ||
-            'respHeaders' in dataOrOptions ||
-            'errorExtractor' in dataOrOptions)) {
+        if (dataOrOptions &&
+            typeof dataOrOptions === 'object' &&
+            !(dataOrOptions instanceof FormData) &&
+            ('data' in dataOrOptions ||
+                'params' in dataOrOptions ||
+                'respHeaders' in dataOrOptions ||
+                'errorExtractor' in dataOrOptions)) {
             const opts = dataOrOptions;
             data = opts.data ?? null;
             fetchParams = opts.params;
@@ -211,10 +224,13 @@ export class HttpApi {
         let fetchParams;
         let headers = null;
         let extractor = null;
-        if (dataOrOptions && ('data' in dataOrOptions ||
-            'params' in dataOrOptions ||
-            'respHeaders' in dataOrOptions ||
-            'errorExtractor' in dataOrOptions)) {
+        if (dataOrOptions &&
+            typeof dataOrOptions === 'object' &&
+            !(dataOrOptions instanceof FormData) &&
+            ('data' in dataOrOptions ||
+                'params' in dataOrOptions ||
+                'respHeaders' in dataOrOptions ||
+                'errorExtractor' in dataOrOptions)) {
             const opts = dataOrOptions;
             data = opts.data ?? null;
             fetchParams = opts.params;
@@ -235,10 +251,13 @@ export class HttpApi {
         let fetchParams;
         let headers = null;
         let extractor = null;
-        if (dataOrOptions && ('data' in dataOrOptions ||
-            'params' in dataOrOptions ||
-            'respHeaders' in dataOrOptions ||
-            'errorExtractor' in dataOrOptions)) {
+        if (dataOrOptions &&
+            typeof dataOrOptions === 'object' &&
+            !(dataOrOptions instanceof FormData) &&
+            ('data' in dataOrOptions ||
+                'params' in dataOrOptions ||
+                'respHeaders' in dataOrOptions ||
+                'errorExtractor' in dataOrOptions)) {
             const opts = dataOrOptions;
             data = opts.data ?? null;
             fetchParams = opts.params;
@@ -295,4 +314,16 @@ export class HttpApi {
 export function createHttpApi(base, defaults, factoryErrorMessageExtractor) {
     return new HttpApi(base, defaults, factoryErrorMessageExtractor);
 }
+/**
+ * Global default error message extractor.
+ * Applied to all requests unless overridden at instance or request level.
+ * Priority: per-request → per-instance → global → built-in fallback.
+ *
+ * @example
+ * ```ts
+ * createHttpApi.defaultErrorMessageExtractor = (body, response) => {
+ *   return body?.error?.message || response.statusText;
+ * };
+ * ```
+ */
 createHttpApi.defaultErrorMessageExtractor = null;