@marianmeres/http-utils 2.0.2 → 2.2.0

package/dist/error.d.ts

@@ -1,5 +1,25 @@
+/**
+ * @module error
+ *
+ * HTTP error classes and utilities for type-safe error handling.
+ * Provides specific error classes for well-known HTTP status codes.
+ */
 /**
  * Base HTTP error class. Extends Error with HTTP-specific properties.
+ * All specific error classes (NotFound, BadRequest, etc.) extend this class.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await api.get("/resource");
+ * } catch (error) {
+ *   if (error instanceof HttpError) {
+ *     console.log(error.status);     // e.g., 404
+ *     console.log(error.statusText); // e.g., "Not Found"
+ *     console.log(error.body);       // Response body
+ *   }
+ * }
+ * ```
  */
 declare class HttpError extends Error {
     name: string;
@@ -8,87 +28,122 @@ declare class HttpError extends Error {
     /** HTTP status text (e.g., "Not Found", "Internal Server Error") */
     statusText: string;
     /** Response body (auto-parsed as JSON if possible) */
-    body: any;
+    body: unknown;
 }
+/** HTTP 400 Bad Request error. */
 declare class BadRequest extends HttpError {
     name: string;
     status: number;
     statusText: string;
 }
+/** HTTP 401 Unauthorized error. */
 declare class Unauthorized extends HttpError {
     name: string;
     status: number;
     statusText: string;
 }
+/** HTTP 403 Forbidden error. */
 declare class Forbidden extends HttpError {
     name: string;
     status: number;
     statusText: string;
 }
+/** HTTP 404 Not Found error. */
 declare class NotFound extends HttpError {
     name: string;
     status: number;
     statusText: string;
 }
+/** HTTP 405 Method Not Allowed error. */
 declare class MethodNotAllowed extends HttpError {
     name: string;
     status: number;
     statusText: string;
 }
+/** HTTP 408 Request Timeout error. */
 declare class RequestTimeout extends HttpError {
     name: string;
     status: number;
     statusText: string;
 }
+/** HTTP 409 Conflict error. */
 declare class Conflict extends HttpError {
     name: string;
     status: number;
     statusText: string;
 }
+/** HTTP 410 Gone error. */
 declare class Gone extends HttpError {
     name: string;
     status: number;
     statusText: string;
 }
+/** HTTP 411 Length Required error. */
 declare class LengthRequired extends HttpError {
     name: string;
     status: number;
     statusText: string;
 }
+/** HTTP 422 Unprocessable Content error. */
 declare class UnprocessableContent extends HttpError {
     name: string;
     status: number;
     statusText: string;
 }
+/** HTTP 429 Too Many Requests error. */
 declare class TooManyRequests extends HttpError {
     name: string;
     status: number;
     statusText: string;
 }
+/** HTTP 418 I'm a Teapot error. */
 declare class ImATeapot extends HttpError {
     name: string;
     status: number;
     statusText: string;
 }
+/** HTTP 500 Internal Server Error. */
 declare class InternalServerError extends HttpError {
     name: string;
 }
+/** HTTP 501 Not Implemented error. */
 declare class NotImplemented extends HttpError {
     name: string;
     status: number;
     statusText: string;
 }
+/** HTTP 502 Bad Gateway error. */
 declare class BadGateway extends HttpError {
     name: string;
     status: number;
     statusText: string;
 }
+/** HTTP 503 Service Unavailable error. */
 declare class ServiceUnavailable extends HttpError {
     name: string;
     status: number;
     statusText: string;
 }
 export { HttpError, BadRequest, Unauthorized, Forbidden, NotFound, MethodNotAllowed, RequestTimeout, Conflict, Gone, LengthRequired, ImATeapot, UnprocessableContent, TooManyRequests, InternalServerError, NotImplemented, BadGateway, ServiceUnavailable, };
+/**
+ * Namespace containing all HTTP error classes for convenient access.
+ *
+ * @example
+ * ```ts
+ * import { HTTP_ERROR } from "@marianmeres/http-utils";
+ *
+ * try {
+ *   await api.get("/resource");
+ * } catch (error) {
+ *   if (error instanceof HTTP_ERROR.NotFound) {
+ *     console.log("Resource not found");
+ *   }
+ *   if (error instanceof HTTP_ERROR.HttpError) {
+ *     console.log("HTTP error:", error.status);
+ *   }
+ * }
+ * ```
+ */
 export declare const HTTP_ERROR: {
     HttpError: typeof HttpError;
     BadRequest: typeof BadRequest;
@@ -128,7 +183,7 @@ export declare const HTTP_ERROR: {
  * console.log(err.body); // { id: 123 }
  * ```
  */
-export declare const createHttpError: (code: number | string, message?: string | null, body?: any, cause?: any) => HttpError;
+export declare const createHttpError: (code: number | string, message?: string | null, body?: unknown, cause?: unknown) => HttpError;
 /**
  * Extracts a human-readable error message from various error formats.
  * Tries multiple strategies to find the best message, with fallbacks.
@@ -146,4 +201,4 @@ export declare const createHttpError: (code: number | string, message?: string |
  *
  * @returns A human-readable error message string.
  */
-export declare const getErrorMessage: (e: any, stripErrorPrefix?: boolean) => string;
+export declare const getErrorMessage: (e: unknown, stripErrorPrefix?: boolean) => string;

package/dist/error.js

@@ -1,6 +1,26 @@
+/**
+ * @module error
+ *
+ * HTTP error classes and utilities for type-safe error handling.
+ * Provides specific error classes for well-known HTTP status codes.
+ */
 import { HTTP_STATUS } from './status.js';
 /**
  * Base HTTP error class. Extends Error with HTTP-specific properties.
+ * All specific error classes (NotFound, BadRequest, etc.) extend this class.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await api.get("/resource");
+ * } catch (error) {
+ *   if (error instanceof HttpError) {
+ *     console.log(error.status);     // e.g., 404
+ *     console.log(error.statusText); // e.g., "Not Found"
+ *     console.log(error.body);       // Response body
+ *   }
+ * }
+ * ```
  */
 class HttpError extends Error {
     name = 'HttpError';
@@ -11,94 +31,127 @@ class HttpError extends Error {
     /** Response body (auto-parsed as JSON if possible) */
     body = null;
 }
-// some more specific instances of the well known ones...
-// client
+// Client error classes (4xx)
+/** HTTP 400 Bad Request error. */
 class BadRequest extends HttpError {
     name = 'HttpBadRequestError';
     status = HTTP_STATUS.ERROR_CLIENT.BAD_REQUEST.CODE;
     statusText = HTTP_STATUS.ERROR_CLIENT.BAD_REQUEST.TEXT;
 }
+/** HTTP 401 Unauthorized error. */
 class Unauthorized extends HttpError {
     name = 'HttpUnauthorizedError';
     status = HTTP_STATUS.ERROR_CLIENT.UNAUTHORIZED.CODE;
     statusText = HTTP_STATUS.ERROR_CLIENT.UNAUTHORIZED.TEXT;
 }
+/** HTTP 403 Forbidden error. */
 class Forbidden extends HttpError {
     name = 'HttpForbiddenError';
     status = HTTP_STATUS.ERROR_CLIENT.FORBIDDEN.CODE;
     statusText = HTTP_STATUS.ERROR_CLIENT.FORBIDDEN.TEXT;
 }
+/** HTTP 404 Not Found error. */
 class NotFound extends HttpError {
     name = 'HttpNotFoundError';
     status = HTTP_STATUS.ERROR_CLIENT.NOT_FOUND.CODE;
     statusText = HTTP_STATUS.ERROR_CLIENT.NOT_FOUND.TEXT;
 }
+/** HTTP 405 Method Not Allowed error. */
 class MethodNotAllowed extends HttpError {
     name = 'HttpMethodNotAllowedError';
     status = HTTP_STATUS.ERROR_CLIENT.METHOD_NOT_ALLOWED.CODE;
     statusText = HTTP_STATUS.ERROR_CLIENT.METHOD_NOT_ALLOWED.TEXT;
 }
+/** HTTP 408 Request Timeout error. */
 class RequestTimeout extends HttpError {
     name = 'HttpRequestTimeoutError';
     status = HTTP_STATUS.ERROR_CLIENT.REQUEST_TIMEOUT.CODE;
     statusText = HTTP_STATUS.ERROR_CLIENT.REQUEST_TIMEOUT.TEXT;
 }
+/** HTTP 409 Conflict error. */
 class Conflict extends HttpError {
     name = 'HttpConflictError';
     status = HTTP_STATUS.ERROR_CLIENT.CONFLICT.CODE;
     statusText = HTTP_STATUS.ERROR_CLIENT.CONFLICT.TEXT;
 }
+/** HTTP 410 Gone error. */
 class Gone extends HttpError {
     name = 'HttpGoneError';
     status = HTTP_STATUS.ERROR_CLIENT.GONE.CODE;
     statusText = HTTP_STATUS.ERROR_CLIENT.GONE.TEXT;
 }
+/** HTTP 411 Length Required error. */
 class LengthRequired extends HttpError {
     name = 'HttpLengthRequiredError';
     status = HTTP_STATUS.ERROR_CLIENT.LENGTH_REQUIRED.CODE;
     statusText = HTTP_STATUS.ERROR_CLIENT.LENGTH_REQUIRED.TEXT;
 }
+/** HTTP 422 Unprocessable Content error. */
 class UnprocessableContent extends HttpError {
     name = 'HttpUnprocessableContentError';
     status = HTTP_STATUS.ERROR_CLIENT.UNPROCESSABLE_CONTENT.CODE;
     statusText = HTTP_STATUS.ERROR_CLIENT.UNPROCESSABLE_CONTENT.TEXT;
 }
+/** HTTP 429 Too Many Requests error. */
 class TooManyRequests extends HttpError {
     name = 'HttpTooManyRequestsError';
     status = HTTP_STATUS.ERROR_CLIENT.TOO_MANY_REQUESTS.CODE;
     statusText = HTTP_STATUS.ERROR_CLIENT.TOO_MANY_REQUESTS.TEXT;
 }
+/** HTTP 418 I'm a Teapot error. */
 class ImATeapot extends HttpError {
     name = 'HttpImATeapotError';
     status = HTTP_STATUS.ERROR_CLIENT.IM_A_TEAPOT.CODE;
     statusText = HTTP_STATUS.ERROR_CLIENT.IM_A_TEAPOT.TEXT;
 }
-// server
+// Server error classes (5xx)
+/** HTTP 500 Internal Server Error. */
 class InternalServerError extends HttpError {
     name = 'HttpInternalServerError';
 }
+/** HTTP 501 Not Implemented error. */
 class NotImplemented extends HttpError {
-    name = 'HttpServiceUnavailableError';
+    name = 'HttpNotImplementedError';
     status = HTTP_STATUS.ERROR_SERVER.NOT_IMPLEMENTED.CODE;
     statusText = HTTP_STATUS.ERROR_SERVER.NOT_IMPLEMENTED.TEXT;
 }
+/** HTTP 502 Bad Gateway error. */
 class BadGateway extends HttpError {
     name = 'HttpBadGatewayError';
     status = HTTP_STATUS.ERROR_SERVER.BAD_GATEWAY.CODE;
     statusText = HTTP_STATUS.ERROR_SERVER.BAD_GATEWAY.TEXT;
 }
+/** HTTP 503 Service Unavailable error. */
 class ServiceUnavailable extends HttpError {
     name = 'HttpServiceUnavailableError';
     status = HTTP_STATUS.ERROR_SERVER.SERVICE_UNAVAILABLE.CODE;
     statusText = HTTP_STATUS.ERROR_SERVER.SERVICE_UNAVAILABLE.TEXT;
 }
-// Export individual error classes
+// Export individual error classes for direct imports
 export { HttpError, 
 // Client errors
 BadRequest, Unauthorized, Forbidden, NotFound, MethodNotAllowed, RequestTimeout, Conflict, Gone, LengthRequired, ImATeapot, UnprocessableContent, TooManyRequests, 
 // Server errors
 InternalServerError, NotImplemented, BadGateway, ServiceUnavailable, };
-// Namespace export for convenience
+/**
+ * Namespace containing all HTTP error classes for convenient access.
+ *
+ * @example
+ * ```ts
+ * import { HTTP_ERROR } from "@marianmeres/http-utils";
+ *
+ * try {
+ *   await api.get("/resource");
+ * } catch (error) {
+ *   if (error instanceof HTTP_ERROR.NotFound) {
+ *     console.log("Resource not found");
+ *   }
+ *   if (error instanceof HTTP_ERROR.HttpError) {
+ *     console.log("HTTP error:", error.status);
+ *   }
+ * }
+ * ```
+ */
 export const HTTP_ERROR = {
     // base
     HttpError,
@@ -143,9 +196,11 @@ const _wellKnownCtorMap = {
 const _maybeJsonParse = (v) => {
     if (typeof v === 'string') {
         try {
-            v = JSON.parse(v);
+            return JSON.parse(v);
+        }
+        catch (_e) {
+            // ignore parse errors
         }
-        catch (e) { }
     }
     return v;
 };
@@ -211,31 +266,30 @@ export const getErrorMessage = (e, stripErrorPrefix = true) => {
         return '';
     // Errors may bubble from various sources which are not always under control.
     // We try our best to extract a meaningful message using common conventions.
-    const cause = _maybeJsonParse(e?.cause);
-    const body = _maybeJsonParse(e?.body);
-    let msg = 
+    const err = e;
+    const cause = _maybeJsonParse(err?.cause);
+    const body = _maybeJsonParse(err?.body);
+    let msg = String(
     // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause
     // e.cause is the standard prop for error details, so should be considered as
     // the most authoritative (if available)
     // "code" and "message" are my own conventions
-    cause?.message ||
-        cause?.code ||
+    (typeof cause === 'object' ? cause?.message : null) ||
+        (typeof cause === 'object' ? cause?.code : null) ||
         (typeof cause === 'string' ? cause : null) ||
         // non-standard "body" is this package's HttpError prop
-        body?.error?.message ||
-        body?.message ||
-        body?.error ||
+        (typeof body === 'object' ? body?.error?.message : null) ||
+        (typeof body === 'object' ? body?.message : null) ||
+        (typeof body === 'object' ? body?.error : null) ||
         (typeof body === 'string' ? body : null) ||
         // the common message from Error ctor (e.g. "Foo" if new TypeError("Foo"))
-        e?.message ||
+        err?.message ||
         // the Error class name (e.g. TypeError)
-        e?.name ||
+        err?.name ||
         // this should handle (almost) everything else (mainly if e is not an Error instance)
-        e?.toString() ||
+        (typeof err?.toString === 'function' ? err.toString() : null) ||
         // very last fallback if `toString()` was not available (or returned empty)
-        'Unknown Error';
-    // ensure we're sending string
-    msg = `${msg}`;
+        'Unknown Error');
     if (stripErrorPrefix) {
         msg = msg.replace(/^[^:]*Error: /i, '');
     }

package/dist/mod.d.ts

@@ -1,3 +1,26 @@
-export { HttpApi, createHttpApi, type DataOptions, type GetOptions, } from "./api.js";
+/**
+ * @module http-utils
+ *
+ * Opinionated, lightweight HTTP client wrapper for the native `fetch` API.
+ * Provides type-safe HTTP errors, convenient defaults, and flexible error handling.
+ *
+ * @example
+ * ```ts
+ * import { createHttpApi, HTTP_ERROR, HTTP_STATUS } from "@marianmeres/http-utils";
+ *
+ * const api = createHttpApi("https://api.example.com", {
+ *   headers: { "Authorization": "Bearer token" }
+ * });
+ *
+ * try {
+ *   const users = await api.get("/users");
+ * } catch (error) {
+ *   if (error instanceof HTTP_ERROR.NotFound) {
+ *     console.log("Not found:", error.body);
+ *   }
+ * }
+ * ```
+ */
+export { HttpApi, createHttpApi, type DataOptions, type GetOptions, type FetchParams, type ErrorMessageExtractor, type ResponseHeaders, type RequestData, } from "./api.js";
 export { HTTP_ERROR, createHttpError, getErrorMessage } from "./error.js";
 export { HTTP_STATUS } from "./status.js";

package/dist/mod.js

@@ -1,3 +1,26 @@
+/**
+ * @module http-utils
+ *
+ * Opinionated, lightweight HTTP client wrapper for the native `fetch` API.
+ * Provides type-safe HTTP errors, convenient defaults, and flexible error handling.
+ *
+ * @example
+ * ```ts
+ * import { createHttpApi, HTTP_ERROR, HTTP_STATUS } from "@marianmeres/http-utils";
+ *
+ * const api = createHttpApi("https://api.example.com", {
+ *   headers: { "Authorization": "Bearer token" }
+ * });
+ *
+ * try {
+ *   const users = await api.get("/users");
+ * } catch (error) {
+ *   if (error instanceof HTTP_ERROR.NotFound) {
+ *     console.log("Not found:", error.body);
+ *   }
+ * }
+ * ```
+ */
 export { HttpApi, createHttpApi, } from "./api.js";
 export { HTTP_ERROR, createHttpError, getErrorMessage } from "./error.js";
 export { HTTP_STATUS } from "./status.js";

package/dist/status.d.ts

@@ -1,6 +1,34 @@
 /**
+ * @module status
+ *
  * HTTP status codes organized by category with convenience shortcuts.
- * Provides comprehensive coverage of standard HTTP status codes.
+ */
+/**
+ * HTTP status codes organized by category with convenience shortcuts.
+ *
+ * Categories:
+ * - `INFO` (1xx): Informational responses
+ * - `SUCCESS` (2xx): Successful responses
+ * - `REDIRECT` (3xx): Redirection messages
+ * - `ERROR_CLIENT` (4xx): Client error responses
+ * - `ERROR_SERVER` (5xx): Server error responses
+ *
+ * @example
+ * ```ts
+ * import { HTTP_STATUS } from "@marianmeres/http-utils";
+ *
+ * // Access 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
+ *
+ * // Lookup by code
+ * const info = HTTP_STATUS.findByCode(404);
+ * // { CODE: 404, TEXT: "Not Found", _TYPE: "ERROR_CLIENT", _KEY: "NOT_FOUND" }
+ * ```
  */
 export declare class HTTP_STATUS {
     static readonly INFO: {

package/dist/status.js

@@ -1,6 +1,34 @@
 /**
+ * @module status
+ *
  * HTTP status codes organized by category with convenience shortcuts.
- * Provides comprehensive coverage of standard HTTP status codes.
+ */
+/**
+ * HTTP status codes organized by category with convenience shortcuts.
+ *
+ * Categories:
+ * - `INFO` (1xx): Informational responses
+ * - `SUCCESS` (2xx): Successful responses
+ * - `REDIRECT` (3xx): Redirection messages
+ * - `ERROR_CLIENT` (4xx): Client error responses
+ * - `ERROR_SERVER` (5xx): Server error responses
+ *
+ * @example
+ * ```ts
+ * import { HTTP_STATUS } from "@marianmeres/http-utils";
+ *
+ * // Access 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
+ *
+ * // Lookup by code
+ * const info = HTTP_STATUS.findByCode(404);
+ * // { CODE: 404, TEXT: "Not Found", _TYPE: "ERROR_CLIENT", _KEY: "NOT_FOUND" }
+ * ```
  */
 // prettier-ignore
 export class HTTP_STATUS {
@@ -126,7 +154,8 @@ export class HTTP_STATUS {
             'INFO', 'SUCCESS', 'REDIRECT', 'ERROR_CLIENT', 'ERROR_SERVER',
         ];
         for (const _TYPE of keys) {
-            for (const [_KEY, data] of Object.entries(HTTP_STATUS[_TYPE])) {
+            const entries = Object.entries(HTTP_STATUS[_TYPE]);
+            for (const [_KEY, data] of entries) {
                 if (data.CODE == code) {
                     return { ...data, _TYPE, _KEY };
                 }

package/package.json

@@ -1,11 +1,18 @@
 {
 	"name": "@marianmeres/http-utils",
-	"version": "2.0.2",
+	"version": "2.2.0",
 	"type": "module",
 	"main": "dist/mod.js",
 	"types": "dist/mod.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/mod.d.ts",
+			"import": "./dist/mod.js"
+		}
+	},
 	"author": "Marian Meres",
 	"license": "MIT",
+	"dependencies": {},
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/marianmeres/http-utils.git"