@marianmeres/http-utils 1.5.0 → 1.6.1

package/README.md

@@ -30,7 +30,10 @@ try {
     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);
-    assert(e.detail.message === 'hey');
+    // `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, containg here some default debug info
+    assert(err.cause.response.headers)
 }
 
 // EXAMPLE: assuming `/foo` returns 404 header and json {"message":"hey"}
@@ -46,6 +49,11 @@ assert(r.message === 'created');
 // EXAMPLE: raw Response
 const r = await api.get('/resource', { raw: true });
 assert(r instanceof Response);
+
+// EXAMPLE: access to response headers
+let respHeaders = {};
+const r = await api.get('/resource', null, respHeaders);
+assert(Object.keys(respHeaders).length)
 ```
 
 See [`HTTP_STATUS`](./src/status.ts) and [`HTTP_ERROR`](./src/error.ts) for more.

package/dist/api.d.ts

@@ -13,10 +13,10 @@ interface FetchParams {
 }
 type BaseFetchParams = BaseParams & FetchParams;
 export declare const createHttpApi: (base?: string | null, defaults?: Partial<BaseFetchParams> | (() => Promise<Partial<BaseFetchParams>>)) => {
-    get(path: string, params?: FetchParams, respHeaders?: null, _dumpParams?: boolean): Promise<string | BaseFetchParams | Response>;
-    post(path: string, data?: null, params?: FetchParams, respHeaders?: null, _dumpParams?: boolean): Promise<string | BaseFetchParams | Response>;
-    put(path: string, data?: null, params?: FetchParams, respHeaders?: null, _dumpParams?: boolean): Promise<string | BaseFetchParams | Response>;
-    patch(path: string, data?: null, params?: FetchParams, respHeaders?: null, _dumpParams?: boolean): Promise<string | BaseFetchParams | Response>;
-    del(path: string, data?: null, params?: FetchParams, respHeaders?: null, _dumpParams?: boolean): Promise<string | BaseFetchParams | Response>;
+    get(path: string, params?: FetchParams, respHeaders?: any, _dumpParams?: boolean): Promise<string | BaseFetchParams | Response>;
+    post(path: string, data?: null, params?: FetchParams, respHeaders?: any, _dumpParams?: boolean): Promise<string | BaseFetchParams | Response>;
+    put(path: string, data?: null, params?: FetchParams, respHeaders?: any, _dumpParams?: boolean): Promise<string | BaseFetchParams | Response>;
+    patch(path: string, data?: null, params?: FetchParams, respHeaders?: any, _dumpParams?: boolean): Promise<string | BaseFetchParams | Response>;
+    del(path: string, data?: null, params?: FetchParams, respHeaders?: any, _dumpParams?: boolean): Promise<string | BaseFetchParams | Response>;
 };
 export {};

package/dist/error.d.ts

@@ -2,6 +2,7 @@ declare class HttpError extends Error {
     name: string;
     status: number;
     statusText: string;
+    body: any;
 }
 declare class BadRequest extends HttpError {
     name: string;
@@ -82,5 +83,5 @@ export declare const HTTP_ERROR: {
     BadGateway: typeof BadGateway;
     ServiceUnavailable: typeof ServiceUnavailable;
 };
-export declare const createHttpError: (code: number | string, message?: string | null, cause?: any) => BadRequest | Unauthorized | Forbidden | NotFound | MethodNotAllowed | RequestTimeout | Conflict | Gone | ImATeapot | InternalServerError | NotImplemented | BadGateway | ServiceUnavailable;
+export declare const createHttpError: (code: number | string, message?: string | null, body?: string | null, cause?: any) => BadRequest | Unauthorized | Forbidden | NotFound | MethodNotAllowed | RequestTimeout | Conflict | Gone | ImATeapot | InternalServerError | NotImplemented | BadGateway | ServiceUnavailable;
 export {};

package/dist/index.cjs

@@ -106,8 +106,10 @@ class HTTP_STATUS {
 // opinionated base for all
 class HttpError extends Error {
     name = 'HttpError';
+    // props simulating fetch Response
     status = HTTP_STATUS.ERROR_SERVER.INTERNAL_SERVER_ERROR.CODE;
     statusText = HTTP_STATUS.ERROR_SERVER.INTERNAL_SERVER_ERROR.TEXT;
+    body = null;
 }
 // some more specific instances of the well known ones...
 // client
@@ -212,15 +214,24 @@ const _wellKnownCtorMap = {
     '503': ServiceUnavailable,
 };
 const createHttpError = (code, message, 
+// arbitrary content, typically http response body which threw this error
+// (will be JSON.parse-d if the content is a valid json string)
+body, 
 // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause
-// arbitrary details, typically response text (will be JSON.parse-d if text is valid json string)
+// arbitrary details, typically response text (will be JSON.parse-d if the content is a valid json string)
 cause) => {
     const fallback = HTTP_STATUS.ERROR_SERVER.INTERNAL_SERVER_ERROR;
     code = Number(code);
     if (isNaN(code) || !(code >= 400 && code < 600))
         code = fallback.CODE;
-    const found = HTTP_STATUS.findByCode(code);
-    const statusText = found?.TEXT ?? fallback.TEXT;
+    // opinionated convention
+    if (typeof body === 'string') {
+        // prettier-ignore
+        try {
+            body = JSON.parse(body);
+        }
+        catch (e) { }
+    }
     // opinionated convention
     if (typeof cause === 'string') {
         // prettier-ignore
@@ -231,9 +242,14 @@ cause) => {
     }
     // try to find the well known one, otherwise fallback to generic
     const ctor = _wellKnownCtorMap[`${code}`] ?? HttpError;
+    //
+    const found = HTTP_STATUS.findByCode(code);
+    const statusText = found?.TEXT ?? fallback.TEXT;
+    //
     let e = new ctor(message || statusText, { cause });
     e.status = found?.CODE ?? fallback.CODE;
     e.statusText = statusText;
+    e.body = body;
     return e;
 };
 
@@ -267,14 +283,13 @@ const _fetch = async (params, respHeaders = null, _dumpParams = false) => {
     const r = await _fetchRaw(params);
     if (params.raw)
         return r;
+    //
+    const headers = [...r.headers.entries()].reduce((m, [k, v]) => ({ ...m, [k]: v }), {});
     // quick-n-dirty reference to headers (so it's still accessible over this api wrap)
     if (respHeaders) {
-        Object.assign(respHeaders, [...r.headers.entries()].reduce((m, [k, v]) => ({ ...m, [k]: v }), {}), 
+        Object.assign(respHeaders, { ...headers }, 
         // adding status/text under special keys
-        {
-            __http_status_code__: r.status,
-            __http_status_text__: r.statusText,
-        });
+        { __http_status_code__: r.status, __http_status_text__: r.statusText });
     }
     let body = await r.text();
     // prettier-ignore
@@ -284,7 +299,15 @@ const _fetch = async (params, respHeaders = null, _dumpParams = false) => {
     catch (e) { }
     params.assert ??= true; // default is true
     if (!r.ok && params.assert) {
-        throw createHttpError(r.status, null, body);
+        throw createHttpError(r.status, null, body, {
+            method: params.method,
+            path: params.path,
+            response: {
+                status: r.status,
+                statusText: r.statusText,
+                headers,
+            },
+        });
     }
     return body;
 };
@@ -305,28 +328,28 @@ const createHttpApi = (base, defaults) => {
     return {
         // GET
         async get(path, params, respHeaders = null, _dumpParams = false) {
-            path = `${base || ''}` + path;
+            path = `${base || ''}${path || ''}`;
             return _fetch(_merge(await _getDefs(), { ...params, method: 'GET', path }), respHeaders, _dumpParams);
         },
         // POST
         async post(path, data = null, params, respHeaders = null, _dumpParams = false) {
-            path = `${base || ''}` + path;
+            path = `${base || ''}${path || ''}`;
             return _fetch(_merge(await _getDefs(), { ...(params || {}), data, method: 'POST', path }), respHeaders, _dumpParams);
         },
         // PUT
         async put(path, data = null, params, respHeaders = null, _dumpParams = false) {
-            path = `${base || ''}` + path;
+            path = `${base || ''}${path || ''}`;
             return _fetch(_merge(await _getDefs(), { ...(params || {}), data, method: 'PUT', path }), respHeaders, _dumpParams);
         },
         // PATCH
         async patch(path, data = null, params, respHeaders = null, _dumpParams = false) {
-            path = `${base || ''}` + path;
+            path = `${base || ''}${path || ''}`;
             return _fetch(_merge(await _getDefs(), { ...(params || {}), data, method: 'PATCH', path }), respHeaders, _dumpParams);
         },
         // DELETE
         // https://stackoverflow.com/questions/299628/is-an-entity-body-allowed-for-an-http-delete-request
         async del(path, data = null, params, respHeaders = null, _dumpParams = false) {
-            path = `${base || ''}` + path;
+            path = `${base || ''}${path || ''}`;
             return _fetch(_merge(await _getDefs(), { ...(params || {}), data, method: 'DELETE', path }), respHeaders, _dumpParams);
         },
     };

package/dist/index.js

@@ -104,8 +104,10 @@ class HTTP_STATUS {
 // opinionated base for all
 class HttpError extends Error {
     name = 'HttpError';
+    // props simulating fetch Response
     status = HTTP_STATUS.ERROR_SERVER.INTERNAL_SERVER_ERROR.CODE;
     statusText = HTTP_STATUS.ERROR_SERVER.INTERNAL_SERVER_ERROR.TEXT;
+    body = null;
 }
 // some more specific instances of the well known ones...
 // client
@@ -210,15 +212,24 @@ const _wellKnownCtorMap = {
     '503': ServiceUnavailable,
 };
 const createHttpError = (code, message, 
+// arbitrary content, typically http response body which threw this error
+// (will be JSON.parse-d if the content is a valid json string)
+body, 
 // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause
-// arbitrary details, typically response text (will be JSON.parse-d if text is valid json string)
+// arbitrary details, typically response text (will be JSON.parse-d if the content is a valid json string)
 cause) => {
     const fallback = HTTP_STATUS.ERROR_SERVER.INTERNAL_SERVER_ERROR;
     code = Number(code);
     if (isNaN(code) || !(code >= 400 && code < 600))
         code = fallback.CODE;
-    const found = HTTP_STATUS.findByCode(code);
-    const statusText = found?.TEXT ?? fallback.TEXT;
+    // opinionated convention
+    if (typeof body === 'string') {
+        // prettier-ignore
+        try {
+            body = JSON.parse(body);
+        }
+        catch (e) { }
+    }
     // opinionated convention
     if (typeof cause === 'string') {
         // prettier-ignore
@@ -229,9 +240,14 @@ cause) => {
     }
     // try to find the well known one, otherwise fallback to generic
     const ctor = _wellKnownCtorMap[`${code}`] ?? HttpError;
+    //
+    const found = HTTP_STATUS.findByCode(code);
+    const statusText = found?.TEXT ?? fallback.TEXT;
+    //
     let e = new ctor(message || statusText, { cause });
     e.status = found?.CODE ?? fallback.CODE;
     e.statusText = statusText;
+    e.body = body;
     return e;
 };
 
@@ -265,14 +281,13 @@ const _fetch = async (params, respHeaders = null, _dumpParams = false) => {
     const r = await _fetchRaw(params);
     if (params.raw)
         return r;
+    //
+    const headers = [...r.headers.entries()].reduce((m, [k, v]) => ({ ...m, [k]: v }), {});
     // quick-n-dirty reference to headers (so it's still accessible over this api wrap)
     if (respHeaders) {
-        Object.assign(respHeaders, [...r.headers.entries()].reduce((m, [k, v]) => ({ ...m, [k]: v }), {}), 
+        Object.assign(respHeaders, { ...headers }, 
         // adding status/text under special keys
-        {
-            __http_status_code__: r.status,
-            __http_status_text__: r.statusText,
-        });
+        { __http_status_code__: r.status, __http_status_text__: r.statusText });
     }
     let body = await r.text();
     // prettier-ignore
@@ -282,7 +297,15 @@ const _fetch = async (params, respHeaders = null, _dumpParams = false) => {
     catch (e) { }
     params.assert ??= true; // default is true
     if (!r.ok && params.assert) {
-        throw createHttpError(r.status, null, body);
+        throw createHttpError(r.status, null, body, {
+            method: params.method,
+            path: params.path,
+            response: {
+                status: r.status,
+                statusText: r.statusText,
+                headers,
+            },
+        });
     }
     return body;
 };
@@ -303,28 +326,28 @@ const createHttpApi = (base, defaults) => {
     return {
         // GET
         async get(path, params, respHeaders = null, _dumpParams = false) {
-            path = `${base || ''}` + path;
+            path = `${base || ''}${path || ''}`;
             return _fetch(_merge(await _getDefs(), { ...params, method: 'GET', path }), respHeaders, _dumpParams);
         },
         // POST
         async post(path, data = null, params, respHeaders = null, _dumpParams = false) {
-            path = `${base || ''}` + path;
+            path = `${base || ''}${path || ''}`;
             return _fetch(_merge(await _getDefs(), { ...(params || {}), data, method: 'POST', path }), respHeaders, _dumpParams);
         },
         // PUT
         async put(path, data = null, params, respHeaders = null, _dumpParams = false) {
-            path = `${base || ''}` + path;
+            path = `${base || ''}${path || ''}`;
             return _fetch(_merge(await _getDefs(), { ...(params || {}), data, method: 'PUT', path }), respHeaders, _dumpParams);
         },
         // PATCH
         async patch(path, data = null, params, respHeaders = null, _dumpParams = false) {
-            path = `${base || ''}` + path;
+            path = `${base || ''}${path || ''}`;
             return _fetch(_merge(await _getDefs(), { ...(params || {}), data, method: 'PATCH', path }), respHeaders, _dumpParams);
         },
         // DELETE
         // https://stackoverflow.com/questions/299628/is-an-entity-body-allowed-for-an-http-delete-request
         async del(path, data = null, params, respHeaders = null, _dumpParams = false) {
-            path = `${base || ''}` + path;
+            path = `${base || ''}${path || ''}`;
             return _fetch(_merge(await _getDefs(), { ...(params || {}), data, method: 'DELETE', path }), respHeaders, _dumpParams);
         },
     };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/http-utils",
-	"version": "1.5.0",
+	"version": "1.6.1",
 	"description": "Misc DRY http fetch related helpers",
 	"type": "module",
 	"main": "./dist/index.cjs",