@marianmeres/http-utils 1.23.0 → 2.0.2

package/README.md

@@ -1,59 +1,276 @@
 # @marianmeres/http-utils
 
-A few opinionated [sweet](https://en.wikipedia.org/wiki/Syntactic_sugar) `fetch` helpers.
+Opinionated, lightweight HTTP client wrapper for `fetch` with type-safe errors and convenient defaults.
 
-## Example
+## Features
 
-```javascript
-import { HTTP_ERROR, HTTP_STATUS, createHttpApi } from '@marianmeres/http-utils';
+- 🎯 **Type-safe HTTP errors** - Well-known status codes map to specific error classes
+- 🔧 **Convenient defaults** - Auto JSON parsing, Bearer tokens, base URLs
+- 🪶 **Lightweight** - Zero dependencies, thin wrapper over native `fetch`
+- 🎨 **Flexible error handling** - Three-tier error message extraction (local → factory → global)
+- 📦 **Deno & Node.js** - Works in both runtimes
 
-// create api helper
-const api = createHttpApi(
-    // optional base url
-    'https://api.example.com',
-    // optional lazy evaluated default fetch params (can be overridden per call)
-    async () => ({
-        token: await getApiTokenFromDb() // example
-    })
+## Installation
 
-// EXAMPLE: assuming `/resource` returns json {"some":"data"}
-const r = await api.get('/resource');
-assert(r.some === 'data');
+```shell
+deno add jsr:@marianmeres/http-utils
+```
+
+```shell
+npm install @marianmeres/http-utils
+```
+
+```ts
+import { createHttpApi, HTTP_ERROR } from "@marianmeres/http-utils";
+```
+
+## Quick Start
+
+```ts
+import { createHttpApi, HTTP_ERROR, NotFound } from "@marianmeres/http-utils";
+
+// Create an API client with base URL
+const api = createHttpApi("https://api.example.com", {
+  headers: { "Authorization": "Bearer your-token" }
+});
+
+// GET request (new options API - recommended)
+const users = await api.get("/users", {
+  params: { headers: { "X-Custom": "value" } }
+});
+
+// POST request (new options API - recommended)
+const newUser = await api.post("/users", {
+  data: { name: "John Doe" },
+  params: { headers: { "X-Custom": "value" } }
+});
+
+// Legacy API still works
+const legacyUsers = await api.get("/users", { headers: { "X-Custom": "value" } });
+const legacyUser = await api.post("/users", { name: "John Doe" });
+
+// Error handling
+try {
+  await api.get("/not-found");
+} catch (error) {
+  if (error instanceof NotFound) {
+    console.log("Resource not found");
+  }
+  // or use the namespace
+  if (error instanceof HTTP_ERROR.NotFound) {
+    console.log(error.status); // 404
+    console.log(error.body);   // Response body
+  }
+}
+```
+
+## API Reference
+
+### `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
+});
+```
+
+**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
+
+```ts
+const api = createHttpApi("https://api.example.com", async () => {
+  const token = await getToken(); // Fetch fresh token
+  return { headers: { "Authorization": `Bearer ${token}` } };
+});
+```
+
+### Raw Response Access
+
+```ts
+const response = await api.get("/users", { raw: true });
+console.log(response instanceof Response); // true
+const data = await response.json();
+```
+
+### Non-Throwing Errors
+
+```ts
+const data = await api.get("/might-fail", { assert: false });
+if (data.error) {
+  console.log("Request failed:", data.error.message);
+}
+```
+
+### AbortController Support
+
+```ts
+const controller = new AbortController();
+
+setTimeout(() => controller.abort(), 5000);
+
+await api.get("/slow-endpoint", { signal: controller.signal });
+```
+
+## Utilities
+
+### `getErrorMessage(error, stripErrorPrefix?)`
+
+Extracts human-readable messages from any error format:
+
+```ts
+import { getErrorMessage } from "@marianmeres/http-utils";
 
-// EXAMPLE: assuming `/foo` returns 404 header and json {"message":"hey"}
-// by default always throws
 try {
-    const r = await api.get('/foo');
-} catch (e) {
-    // see HTTP_ERROR for more
-    assert(e instanceof HTTP_ERROR.NotFound);
-    assert(e.toString() === 'HttpNotFoundError: Not Found');
-    assert(e.status === HTTP_STATUS.ERROR_CLIENT.NOT_FOUND.CODE);
-    assert(e.statusText === HTTP_STATUS.ERROR_CLIENT.NOT_FOUND.TEXT);
-    // `body` is a custom prop containing the raw http response body text (JSON.parse-d if available)
-    assert(e.body.message === 'hey');
-    // `cause` is a standart Error prop, containing here some default debug info
-    assert(err.cause.response.headers)
+  await api.get("/fail");
+} catch (error) {
+  console.log(getErrorMessage(error)); // "Not Found"
 }
+```
 
-// EXAMPLE: assuming `/foo` returns 404 header and json {"message":"hey"}
-// will not throw if we pass false flag
-const r = await api.get('/foo', { assert: false });
-assert(r.message === 'hey');
+### `createHttpError(code, message?, body?, cause?)`
 
-// EXAMPLE: assuming POST to `/resource` returns OK and json {"message":"created"}
-// the provided token below will override the one from the `getApiTokenFromDb()` call above
-const r = await api.post('/resource', { some: 'data' }, { token: 'my-api-token' });
-assert(r.message === 'created');
+Manually create HTTP errors:
 
-// EXAMPLE: raw Response
-const r = await api.get('/resource', { raw: true });
-assert(r instanceof Response);
+```ts
+import { createHttpError } from "@marianmeres/http-utils";
 
-// EXAMPLE: access to response headers
-let respHeaders = {};
-const r = await api.get('/resource', null, respHeaders);
-assert(Object.keys(respHeaders).length)
+const error = createHttpError(404, "User not found", { userId: 123 });
+throw error;
 ```
 
-See [`HTTP_STATUS`](./src/status.ts) and [`HTTP_ERROR`](./src/error.ts) for more.
+## Package Identity
+
+- **Name:** @marianmeres/http-utils
+- **Author:** Marian Meres
+- **Repository:** https://github.com/marianmeres/http-utils
+- **License:** MIT

package/dist/api.d.ts

@@ -5,24 +5,148 @@ interface BaseParams {
 interface FetchParams {
     data?: any;
     token?: string | null;
-    headers?: null | Record<string, string>;
-    signal?: any;
-    credentials?: null | 'omit' | 'same-origin' | 'include';
-    raw?: null | boolean;
-    assert?: null | boolean;
+    headers?: Record<string, string> | null;
+    signal?: AbortSignal;
+    credentials?: 'omit' | 'same-origin' | 'include' | null;
+    raw?: boolean | null;
+    assert?: boolean | null;
 }
 type BaseFetchParams = BaseParams & FetchParams;
-type ErrorMessageExtractor = (body: any, response: Response) => any;
-export declare function createHttpApi(base?: string | null, defaults?: Partial<BaseFetchParams> | (() => Promise<Partial<BaseFetchParams>>), factoryErrorMessageExtractor?: ErrorMessageExtractor | null | undefined): {
-    get(path: string, params?: FetchParams, respHeaders?: any, errorMessageExtractor?: ErrorMessageExtractor | null | undefined, _dumpParams?: boolean): Promise<any>;
-    post(path: string, data?: any, params?: FetchParams, respHeaders?: any, errorMessageExtractor?: ErrorMessageExtractor | null | undefined, _dumpParams?: boolean): Promise<any>;
-    put(path: string, data?: any, params?: FetchParams, respHeaders?: any, errorMessageExtractor?: ErrorMessageExtractor | null | undefined, _dumpParams?: boolean): Promise<any>;
-    patch(path: string, data?: any, params?: FetchParams, respHeaders?: any, errorMessageExtractor?: ErrorMessageExtractor | null | undefined, _dumpParams?: boolean): Promise<any>;
-    del(path: string, data?: any, params?: FetchParams, respHeaders?: any, errorMessageExtractor?: ErrorMessageExtractor | null | undefined, _dumpParams?: boolean): Promise<any>;
-    url: (path: string) => string;
-    base: string | null | undefined;
-};
+type ErrorMessageExtractor = (body: any, response: Response) => string;
+type ResponseHeaders = Record<string, string | number>;
+/**
+ * Options for HTTP GET requests (new cleaner API).
+ */
+export interface GetOptions {
+    params?: FetchParams;
+    respHeaders?: ResponseHeaders | null;
+    errorExtractor?: ErrorMessageExtractor | null;
+}
+/**
+ * Options for HTTP POST/PUT/PATCH/DELETE requests (new cleaner API).
+ */
+export interface DataOptions {
+    data?: any;
+    params?: FetchParams;
+    respHeaders?: ResponseHeaders | null;
+    errorExtractor?: ErrorMessageExtractor | null;
+}
+/**
+ * HTTP API client with convenient defaults and error handling.
+ */
+export declare class HttpApi {
+    #private;
+    constructor(base?: string | null, defaults?: Partial<BaseFetchParams> | (() => Promise<Partial<BaseFetchParams>>), factoryErrorMessageExtractor?: ErrorMessageExtractor | null | undefined);
+    /**
+     * Performs a GET request (new options API - recommended).
+     *
+     * @param path - The request path (will be appended to base URL if set).
+     * @param options - Request options object.
+     * @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).
+     *
+     * @example
+     * ```ts
+     * const data = await api.get('/users', {
+     *   params: { headers: { 'X-Custom': 'value' } },
+     *   respHeaders: {}
+     * });
+     * ```
+     */
+    get(path: string, options: GetOptions): Promise<any>;
+    /**
+     * Performs a GET request (legacy API).
+     *
+     * @param path - The request path (will be appended to base URL if set).
+     * @param params - Optional fetch parameters.
+     * @param respHeaders - Optional object to be mutated with response headers.
+     * @param errorMessageExtractor - Optional custom error message extractor.
+     * @param _dumpParams - Internal parameter for testing.
+     * @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>;
+    /**
+     * Performs a POST request (new options API - recommended).
+     *
+     * @param path - The request path (will be appended to base URL if set).
+     * @param options - Request options object including data and params.
+     * @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).
+     *
+     * @example
+     * ```ts
+     * await api.post('/users', {
+     *   data: { name: 'John' },
+     *   params: { headers: { 'X-Custom': 'value' } },
+     *   respHeaders: {}
+     * });
+     * ```
+     */
+    post(path: string, options: DataOptions): Promise<any>;
+    /**
+     * Performs a POST request (legacy API).
+     *
+     * @param path - The request path (will be appended to base URL if set).
+     * @param data - Request body data.
+     * @param params - Optional fetch parameters.
+     * @param respHeaders - Optional object to be mutated with response headers.
+     * @param errorMessageExtractor - Optional custom error message extractor.
+     * @param _dumpParams - Internal parameter for testing.
+     * @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>;
+    /** Performs a PUT request (new options API). @see post */
+    put(path: string, options: DataOptions): Promise<any>;
+    /** 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>;
+    /** Performs a PATCH request (new options API). @see post */
+    patch(path: string, options: DataOptions): Promise<any>;
+    /** 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>;
+    /**
+     * 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>;
+    /** 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>;
+    /**
+     * Helper method to build the full URL from a path.
+     *
+     * @param path - The path to resolve (absolute URLs are returned as-is).
+     * @returns The resolved URL (base + path, or just path if it's already absolute).
+     */
+    url(path: string): string;
+    /**
+     * Get or set the base URL for all requests.
+     */
+    get base(): string | null | undefined;
+    set base(v: string | null | undefined);
+}
+/**
+ * Creates an HTTP API client with convenient defaults and error handling.
+ *
+ * @param base - Optional base URL to prepend to all requests. Can be changed later via the `base` property.
+ * @param defaults - Optional default parameters to merge with each request. Can be an object or async function returning an object.
+ * @param factoryErrorMessageExtractor - Optional function to extract error messages from failed responses.
+ *
+ * @returns An HttpApi instance with methods: get, post, put, patch, del, url, base.
+ *
+ * @example
+ * ```ts
+ * const api = createHttpApi('https://api.example.com', {
+ *   headers: { 'Authorization': 'Bearer token' }
+ * });
+ *
+ * const data = await api.get('/users');
+ * await api.post('/users', { name: 'John' });
+ * ```
+ */
+export declare function createHttpApi(base?: string | null, defaults?: Partial<BaseFetchParams> | (() => Promise<Partial<BaseFetchParams>>), factoryErrorMessageExtractor?: ErrorMessageExtractor | null | undefined): HttpApi;
 export declare namespace createHttpApi {
-    var defaultErrorMessageExtractor: ErrorMessageExtractor | null | undefined;
+    var defaultErrorMessageExtractor: ErrorMessageExtractor;
 }
 export {};