feat: added getJSON() method

Author: nktnet1

README.md

@@ -82,6 +82,9 @@ Please refer to the [compatibility](#4-compatibility) section for known issues a
 
 ## 2. Usage
 
+> [!TIP]
+> Starting from `sync-request-curl@3.2.0`, you can replace `JSON.parse(res.body.toString())` with `res.getJSON()`.
+
 Try with [Replit](https://replit.com/@nktnet1/sync-request-curl-example#index.js).
 
 ```typescript
@@ -140,6 +143,7 @@ const res = request(
     },
   }
 );
+
 console.log('Status Code:', res.statusCode);
 const jsonBody = JSON.parse(res.body.toString());
 console.log('Returned JSON Object:', jsonBody);
@@ -334,19 +338,21 @@ export interface Options {
 
 - **`statusCode`** - a number representing the HTTP status code (e.g. `200`, `400`, `401`, `403`)
 - **`headers`** - HTTP response headers. The keys/properties of the object will always be in lowercase, e.g. `"content-type"` instead of `"Content-Type"`
+- **`url`** - the final URL used in the request after all redirections are followed and all query string parameters appended
 - **`body`** - a string or buffer - for JSON responses, use `JSON.parse(response.body.toString())` to get the returned data as an object
 - **`getBody`** - a function with an optional `encoding` argument that returns the `body` if `encoding` is undefined, otherwise `body.toString(encoding)`. If `statusCode >= 300`, an `Error` is thrown instead
-- **`url`** - the final URL used in the request after all redirections are followed, and with the query string parameters appended
+- **`getJSON`** - a function that returns the body as `JSON`. an `Error` is thrown if the body cannot be parsed.
 
 In [src/types.ts](src/types.ts), the `Response` interface is defined as:
 
 ```typescript
 export interface Response {
   statusCode: number;
   headers: IncomingHttpHeaders;
+  url: string;
   body: string | Buffer;
   getBody: (encoding?: BufferEncoding) => string | Buffer; // simplified
-  url: string;
+  getJSON: <T = any>(encoding?: BufferEncoding) => T
 }
 ```
 

src/request.ts

@@ -1,7 +1,7 @@
 import { Curl, Easy } from 'node-libcurl';
-import { HttpVerb, Options, Response, GetBody } from './types';
+import { HttpVerb, Options, Response, GetBody, GetJSON } from './types';
 import {
-  checkGetBodyStatus,
+  checkValidStatusCode,
   checkValidCurlCode,
   handleQs,
   parseReturnedHeaders,
@@ -165,14 +165,39 @@ const request = (method: HttpVerb, url: string, options: Options = {}): Response
    * @returns {Buffer | string} buffer body by default, string body with encoding
    */
   const getBody: GetBody = (encoding?) => {
-    checkGetBodyStatus(statusCode, body);
+    checkValidStatusCode(statusCode, body);
     return typeof encoding === 'string' ? body.toString(encoding) as any : body;
   };
 
+  /**
+ * Get the JSON-parsed body of a response.
+ *
+ * @throws {Error} if the body is nto a valid JSON
+ * @returns {any} parsed JSON body
+ */
+  const getJSON: GetJSON = (encoding?) => {
+    try {
+      return JSON.parse(body.toString(encoding));
+    } catch (err) {
+      throw new Error(`
+The server body response for
+  - ${method}
+  - ${url}
+cannot be parsed as JSON.
+
+Body:
+  ${body.toString(encoding)}
+
+JSON-Parsing Error Message:
+  ${err instanceof Error ? err.message : String(err)}
+      `);
+    }
+  };
+
   url = curl.getInfo('EFFECTIVE_URL').data as string;
 
   curl.close();
-  return { statusCode, headers, body, getBody, url };
+  return { statusCode, headers, url, body, getBody, getJSON };
 };
 
 export default request;

src/types.ts

@@ -48,13 +48,16 @@ export interface Options {
 }
 
 // Infer type `string` if encoding is specified, otherwise `string | Buffer
-export type GetBody = <encoding extends BufferEncoding | undefined>(arg?: encoding)
-  => encoding extends BufferEncoding ? string : Buffer;
+export type GetBody = <Encoding extends BufferEncoding | undefined>(arg?: Encoding)
+  => Encoding extends BufferEncoding ? string : Buffer;
+
+export type GetJSON = <T = any>(encoding?: BufferEncoding) => T;
 
 export interface Response {
   statusCode: number;
   headers: IncomingHttpHeaders;
+  url: string;
   body: string | Buffer;
   getBody: GetBody;
-  url: string;
+  getJSON: GetJSON;
 }

src/utils.ts

@@ -99,16 +99,19 @@ export const checkValidCurlCode = (code: CurlCode, requestInputs: RequestInputs)
  * @param {Buffer} body - The body of the HTTP response.
  * @throws {Error} if the status code is >= 300.
  */
-export const checkGetBodyStatus = (statusCode: number, body: Buffer) => {
+export const checkValidStatusCode = (statusCode: number, body: Buffer) => {
   if (statusCode >= 300) {
     throw new Error(`
-      Server responded with status code ${statusCode}
+Server responded with status code
+  ${statusCode}
 
-      Body: ${body.toString()}
+Body:
+  ${body.toString()}
 
-      Use 'res.body' instead of 'res.getBody()' to not have any errors thrown.
-      The status code (in this case, ${statusCode}) can be checked manually
-      with res.statusCode.
+Use 'res.body' instead of 'res.getBody()' to not have any errors thrown.
+
+The status code (in this case, ${statusCode}) can be checked manually
+with res.statusCode.
     `);
   }
 };

tests/app/index.ts

@@ -63,6 +63,10 @@ app.post('/timeout', async (c) => {
   return c.json({});
 });
 
+app.post('/text', async (c) => {
+  return c.text('Hello world!');
+});
+
 app.onError((err, c) => {
   const status = err instanceof HTTPException ? err.status : 500;
   const message = err instanceof HTTPException ? err.message : 'Internal Server Error';

tests/request.test.ts

@@ -265,3 +265,28 @@ describe('Redirects', () => {
     expect(noRedirect).toMatchObject({ code: 302 });
   });
 });
+
+// ========================================================================= //
+
+describe('v3.2.0 getJSON method', () => {
+  test('Valid JSON body', () => {
+    const value = {
+      1: 'one',
+      two: 2,
+      three: true,
+      four: null,
+      nested: {
+        five: false,
+        array: [{ key: 'value' }, { key2: 'value2' }]
+      }
+    };
+    const res = request('POST', `${SERVER_URL}/post`, { json: { value } });
+    const jsonBody = res.getJSON();
+    expect(jsonBody).toStrictEqual({ value });
+  });
+
+  test('Invalid JSON body', () => {
+    const res = request('POST', `${SERVER_URL}/text`);
+    expect(() => res.getJSON()).toThrow(Error);
+  });
+});