Merge pull request #5 from WJSoftware:JP/ShortCutFunctions

feat: Add shortcut functions for popular HTTP methods

Author: webJose

README.md

@@ -169,7 +169,35 @@ const localFetcher = rootFetcher.clone(true, { includeParsers: false }); // No c
 > **IMPORTANT**:  The first parameter to the `clone` function cannot be a variable.  It is just used as a TypeScript 
 > trick to reset the body typing.  The value itself means nothing in runtime because types are not a runtime thing.
 
+## Shortcut Functions
+
+> Since **v0.3.0**
+
+`DrFetch` objects now provide the shortcut functions `get`, `post`, `patch`, `put` and `delete`.  Except for `get`, all 
+these accept a body parameter.  When this body is a POJO or an array, the body is stringified and the `Content-Type` 
+header is given the value `application/json`.  If a body of any other type is given (that the `fetch()` function 
+accepts, such as `FormData`), no headers are explicitly specified and therefore it is up to what `fetch()` (or the 
+custom data-fetching function you provide) does in these cases.
+
+```typescript
+const newTodo = { text: 'I am new.  Insert me!' };
+const response = await fetcher
+    .for<200, { success: boolean; }>()
+    .for<400, { errors: string[]; }>()
+    .post('/api/todos', newTodo);
+
+const newTodos = [{ text: 'I am new.  Insert me!' }, { text: 'Me too!' }];
+const response = await fetcher
+    .for<200, { success: boolean; }>()
+    .for<400, { errors: string[]; }>()
+    .post('/api/todos', newTodos);
+```
+
+As stated, your custom fetch can be used to further customize the request because these shortcut functions will, in the 
+end, call it.
+
 ## Usage Without TypeScript (JavaScript Projects)
 
 Why are you a weird fellow/gal?  Anyway, prejudice aside, body typing will mean nothing to you, so forget about `for()` 
-and anything else regarding types.  Do your custom data-fetching function, add your custom body parsers and that's it.
+and anything else regarding types.  Do your custom data-fetching function, add your custom body parsers and fetch away 
+using `.fetch()`, `.get()`, `.post()`, `.put()`, `.patch()` or `.delete()`.

src/DrFetch.ts

@@ -16,6 +16,22 @@ const textTypes: (string | RegExp)[] = [
     /^text\/.+/,
 ];
 
+/**
+ * Determines if the given object is a POJO.
+ * @param obj Object under test.
+ * @returns `true` if it is a POJO, or `false` otherwise.
+ */
+function isPojo(obj: unknown): obj is Record<string, any> {
+    if (obj === null || typeof obj !== 'object') {
+        return false;
+    }
+    const proto = Object.getPrototypeOf(obj);
+    if (proto == null) {
+        return true;
+    }
+    return proto === Object.prototype;
+}
+
 /**
  * # DrFetch
  * 
@@ -230,4 +246,98 @@ export class DrFetch<T = unknown> {
             body
         } as T;
     }
+
+    #processBody(body: BodyInit | null | Record<string, any> | undefined) {
+        let headers: Record<string, string> = {};
+        if (isPojo(body) || Array.isArray(body)) {
+            body = JSON.stringify(body);
+            headers['content-type'] = 'application/json';
+        }
+        return [body as BodyInit | null, headers] as const;
+    }
+
+    /**
+     * Shortcut method to emit a GET HTTP request.
+     * @param url URL for the fetch function call.
+     * @returns A response object with the HTTP response's `ok`, `status`, `statusText` and `body` properties.
+     */
+    get(url: URL | string) {
+        return this.fetch(url, { method: 'GET' });
+    }
+
+    /**
+     * Shortcut method to emit a POST HTTP request.
+     * @param url URL for the fetch function call.
+     * @param body The data to send as body.
+     * 
+     * If a POJO is passed, it will be stringified and the `Content-Type` header of the request will be set to 
+     * `'application/json'`.  This is also true with arrays.
+     * 
+     * > **NOTE**:  You must make sure that the POJO or the array (and its elements) you pass as body are serializable.
+     * 
+     * Any other body type will not generate a `Content-Type` header and will be reliant on what the `fetch()` function 
+     * does in those cases.
+     * @returns A response object with the HTTP response's `ok`, `status`, `statusText` and `body` properties.
+     */
+    post(url: URL | string, body?: BodyInit | null | Record<string, any>) {
+        const [pBody, headers] = this.#processBody(body);
+        return this.fetch(url, { method: 'POST', body: pBody, headers });
+    }
+
+    /**
+     * Shortcut method to emit a PATCH HTTP request.
+     * @param url URL for the fetch function call.
+     * @param body The data to send as body.
+     * 
+     * If a POJO is passed, it will be stringified and the `Content-Type` header of the request will be set to 
+     * `'application/json'`.  This is also true with arrays.
+     * 
+     * > **NOTE**:  You must make sure that the POJO or the array (and its elements) you pass as body are serializable.
+     * 
+     * Any other body type will not generate a `Content-Type` header and will be reliant on what the `fetch()` function 
+     * does in those cases.
+     * @returns A response object with the HTTP response's `ok`, `status`, `statusText` and `body` properties.
+     */
+    patch(url: URL | string, body?: BodyInit | null | Record<string, any>) {
+        const [pBody, headers] = this.#processBody(body);
+        return this.fetch(url, { method: 'PATCH', body: pBody, headers });
+    }
+
+    /**
+     * Shortcut method to emit a DELETE HTTP request.
+     * @param url URL for the fetch function call.
+     * @param body The data to send as body.
+     * 
+     * If a POJO is passed, it will be stringified and the `Content-Type` header of the request will be set to 
+     * `'application/json'`.  This is also true with arrays.
+     * 
+     * > **NOTE**:  You must make sure that the POJO or the array (and its elements) you pass as body are serializable.
+     * 
+     * Any other body type will not generate a `Content-Type` header and will be reliant on what the `fetch()` function 
+     * does in those cases.
+     * @returns A response object with the HTTP response's `ok`, `status`, `statusText` and `body` properties.
+     */
+    delete(url: URL | string, body?: BodyInit | null | Record<string, any>) {
+        const [pBody, headers] = this.#processBody(body);
+        return this.fetch(url, { method: 'DELETE', body: pBody, headers });
+    }
+
+    /**
+     * Shortcut method to emit a PUT HTTP request.
+     * @param url URL for the fetch function call.
+     * @param body The data to send as body.
+     * 
+     * If a POJO is passed, it will be stringified and the `Content-Type` header of the request will be set to 
+     * `'application/json'`.  This is also true with arrays.
+     * 
+     * > **NOTE**:  You must make sure that the POJO or the array (and its elements) you pass as body are serializable.
+     * 
+     * Any other body type will not generate a `Content-Type` header and will be reliant on what the `fetch()` function 
+     * does in those cases.
+     * @returns A response object with the HTTP response's `ok`, `status`, `statusText` and `body` properties.
+     */
+    put(url: URL | string, body?: BodyInit | null | Record<string, any>) {
+        const [pBody, headers] = this.#processBody(body);
+        return this.fetch(url, { method: 'PUT', body: pBody, headers });
+    }
 }

src/tests/DrFetch.test.ts

@@ -3,6 +3,18 @@ import { describe, test } from "mocha";
 import { fake } from 'sinon';
 import { DrFetch } from "../DrFetch.js";
 
+const shortcutMethodsWithBody = [
+    'post',
+    'put',
+    'patch',
+    'delete',
+] as const;
+
+const allShortcutMethods = [
+    'get',
+    ...shortcutMethodsWithBody
+] as const;
+
 describe('DrFetch', () => {
     describe('clone()', () => {
         [
@@ -162,7 +174,7 @@ describe('DrFetch', () => {
         });
         test("Should throw an error if the content type is unknown by the built-in parsers and custom parsers.", async () => {
             // Arrange.
-            const fetchFn = fake.resolves(new Response('x', { headers: { 'content-type': 'application/xml' }}));
+            const fetchFn = fake.resolves(new Response('x', { headers: { 'content-type': 'application/xml' } }));
             const fetcher = new DrFetch(fetchFn);
             let didThrow = false;
 
@@ -213,7 +225,7 @@ describe('DrFetch', () => {
             test(`Should use the provided custom parser with ${tc.patternType} pattern "${tc.pattern.toString()}" for content type "${tc.contentType}".`, async () => {
                 // Arrange.
                 const parserFn = fake();
-                const fetchFn = fake.resolves(new Response('x', { headers: { 'content-type': tc.contentType }}));
+                const fetchFn = fake.resolves(new Response('x', { headers: { 'content-type': tc.contentType } }));
                 const fetcher = new DrFetch(fetchFn);
                 fetcher.withParser(tc.pattern, parserFn);
 
@@ -225,4 +237,97 @@ describe('DrFetch', () => {
             });
         })
     });
+    describe('Shortcut Functions', () => {
+        allShortcutMethods.map(x => ({
+            shortcutFn: x,
+            expectedMethod: x.toUpperCase()
+        })).forEach(tc => {
+            test(`${tc.shortcutFn}():  Should perform a fetch() call with the '${tc.expectedMethod}' method.`, async () => {
+                // Arrange.
+                const fetchFn = fake.resolves(new Response());
+                const fetcher = new DrFetch(fetchFn);
+
+                // Act.
+                await fetcher[tc.shortcutFn]('x');
+
+                // Assert.
+                expect(fetchFn.calledOnce).to.be.true;
+                expect(fetchFn.args[0][1]['method']).to.equal(tc.expectedMethod);
+            });
+        });
+        shortcutMethodsWithBody.forEach(method => {
+            test(`${method}():  Should stringify the body argument when said argument is a POJO object.`, async () => {
+                // Arrange.
+                const body = { a: 'hi' };
+                const fetchFn = fake.resolves(new Response());
+                const fetcher = new DrFetch(fetchFn);
+
+                // Act.
+                await fetcher[method]('x', body);
+
+                // Assert.
+                expect(fetchFn.calledOnce).to.be.true;
+                expect(fetchFn.args[0][1]['body']).to.equal(JSON.stringify(body));
+                expect(fetchFn.args[0][1]['headers']['content-type']).to.equal('application/json');
+            });
+        });
+        shortcutMethodsWithBody.forEach(method => {
+            test(`${method}():  Should stringify the body argument when said argument is an array.`, async () => {
+                // Arrange.
+                const body = [{ a: 'hi' }];
+                const fetchFn = fake.resolves(new Response());
+                const fetcher = new DrFetch(fetchFn);
+
+                // Act.
+                await fetcher[method]('x', body);
+
+                // Assert.
+                expect(fetchFn.calledOnce).to.be.true;
+                expect(fetchFn.args[0][1]['body']).to.equal(JSON.stringify(body));
+                expect(fetchFn.args[0][1]['headers']['content-type']).to.equal('application/json');
+            });
+        });
+        shortcutMethodsWithBody.flatMap(method => [
+            {
+                body: new ReadableStream(),
+                text: 'a readable stream',
+            },
+            {
+                body: new Blob(),
+                text: 'a blob',
+            },
+            {
+                body: new ArrayBuffer(8),
+                text: 'an array buffer',
+            },
+            {
+                body: new FormData(),
+                text: 'a form data object',
+            },
+            {
+                body: new URLSearchParams(),
+                text: 'a URL search params object',
+            },
+            {
+                body: 'abc',
+                text: 'a string'
+            }
+        ].map(body => ({
+            method,
+            body
+        }))).forEach(tc => {
+            test(`${tc.method}():  Should not stringify the body when said argument is ${tc.body.text}.`, async () => {
+                // Arrange.
+                const fetchFn = fake.resolves(new Response());
+                const fetcher = new DrFetch(fetchFn);
+
+                // Act.
+                await fetcher[tc.method]('x', tc.body.body);
+
+                // Assert.
+                expect(fetchFn.calledOnce).to.be.true;
+                expect(fetchFn.args[0][1]['body']).to.equal(tc.body.body);
+            });
+        })
+    });
 });