fetch-request-browser 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Jesus Graterol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,205 @@
+# Fetch Request Browser
+
+The `fetch-request-browser` package makes working with external APIs simple and efficient. This intuitive wrapper leverages the power of the Fetch API, providing a clean and concise interface for your API interactions.
+
+
+
+
+
+<br />
+
+## Getting Started
+
+Install the package:
+```bash
+$ npm install -S fetch-request-browser
+```
+
+
+
+
+
+<br />
+
+## Usage
+
+```typescript
+import { sendGET } from 'fetch-request-browser';
+
+await sendGET('https://httpbin.org/get');
+// {
+//   code: 200,
+//   headers: Headers {
+//     date: 'Tue, 04 Jun 2024 18:52:29 GMT',
+//     'content-type': 'application/json',
+//     'content-length': '407',
+//     connection: 'keep-alive',
+//     server: 'gunicorn/19.9.0',
+//     'access-control-allow-origin': '*',
+//     'access-control-allow-credentials': 'true'
+//   },
+//   data: {
+//     args: {},
+//     headers: {
+//       Accept: 'application/json',
+//       'Accept-Encoding': 'br, gzip, deflate',
+//       'Accept-Language': '*',
+//       'Content-Type': 'application/json',
+//       Host: 'httpbin.org',
+//       'Sec-Fetch-Mode': 'cors',
+//       'User-Agent': 'node',
+//       'X-Amzn-Trace-Id': '...'
+//     },
+//     origin: '...',
+//     url: 'https://httpbin.org/get'
+//   }
+// }
+```
+
+
+
+
+
+<br/>
+
+## API
+
+Build and send an HTTP Request (any method):
+
+```typescript
+send(
+  input: IRequestInput, 
+  options?: Partial<IOptions>
+): Promise<IRequestResponse>
+```
+
+<br />
+
+Build and send a `GET` HTTP Request:
+```typescript
+sendGET(
+  input: IRequestInput,
+  options?: Partial<IOptions>,
+  retryAttempts?: number,
+  retryDelaySeconds?: number
+): Promise<IRequestResponse>
+```
+
+<br />
+
+Build and send a `POST` HTTP Request:
+```typescript
+sendPOST(
+  input: IRequestInput,
+  options?: Partial<IOptions>
+): Promise<IRequestResponse>
+```
+
+<br />
+
+Build and send a `PUT` HTTP Request:
+```typescript
+sendPUT(
+  input: IRequestInput,
+  options?: Partial<IOptions>
+): Promise<IRequestResponse>
+```
+
+<br />
+
+Build and send a `PATCH` HTTP Request:
+```typescript
+sendPATCH(
+  input: IRequestInput,
+  options?: Partial<IOptions>
+): Promise<IRequestResponse>
+```
+
+<br />
+
+Build and send a `DELETE` HTTP Request:
+```typescript
+sendDELETE(
+  input: IRequestInput,
+  options?: Partial<IOptions>
+): Promise<IRequestResponse>
+```
+
+
+
+<br />
+
+## Built With
+
+- TypeScript
+
+
+
+
+<br />
+
+## Running the Tests
+
+```bash
+# Unit Tests
+$ npm run test:unit
+
+# Integration Tests
+$ npm run test:integration
+```
+
+
+
+
+
+<br />
+
+## License
+
+[MIT](https://choosealicense.com/licenses/mit/)
+
+
+
+
+
+<br />
+
+## Acknowledgments
+
+- [MDN](https://developer.mozilla.org/en-US/)
+- [web.dev](https://web.dev/)
+
+
+
+
+
+<br />
+
+## @TODOS
+
+- [ ] Improve the docs
+
+
+
+
+
+<br />
+
+## Deployment
+
+Install dependencies:
+```bash
+$ npm install
+```
+
+
+Build the library:
+```bash
+$ npm start
+```
+
+
+Publish to `npm`:
+```bash
+$ npm publish
+```

package/dist/index.d.ts

@@ -0,0 +1,91 @@
+import { IRequestInput, IRequestMethod, IRequestOptions, IResponseDataType, IOptions, IRequestResponse } from './shared/types.js';
+/**
+ * Builds and sends an HTTP Request based on the provided input and options.
+ * @param input
+ * @param options?
+ * @returns Promise<IRequestResponse>
+ * @throws
+ * - INVALID_REQUEST_URL: if the provided input URL cannot be parsed
+ * - INVALID_REQUEST_HEADERS: if invalid headers are passed in object format
+ * - INVALID_REQUEST_OPTIONS: if the Request Instance cannot be instantiated due to the passed opts
+ * - UNEXPECTED_RESPONSE_STATUS_CODE: if the code doesn't meet the requirements set in the options
+ * - CONTENT_TYPE_MISSMATCH: if the Content-Type Headers are not identical
+ * - INVALID_RESPONSE_DTYPE: if the data type is not supported by the Response Instance
+ */
+declare const send: (input: IRequestInput, options?: Partial<IOptions>) => Promise<IRequestResponse>;
+/**
+ * Builds and sends a GET HTTP Request based on the provided input and options.
+ * IMPORTANT: The browser environment can be highly unreliable as the user can physically move
+ * around and suffer from an intermittent Internet connection. Therefore, some GET requests are
+ * worth retrying as they could fail temporarily and prevent a view from loading.
+ * @param input
+ * @param options?
+ * @param retryAttempts? - the number of times it will retry the request on failure
+ * @param retryDelaySeconds? - the # of secs it will wait before re-sending the req. Defaults to 3
+ * @returns Promise<IRequestResponse>
+ * @throws
+ * - INVALID_REQUEST_URL: if the provided input URL cannot be parsed
+ * - INVALID_REQUEST_HEADERS: if invalid headers are passed in object format
+ * - INVALID_REQUEST_OPTIONS: if the Request Instance cannot be instantiated due to the passed opts
+ * - UNEXPECTED_RESPONSE_STATUS_CODE: if the code doesn't meet the requirements set in the options
+ * - CONTENT_TYPE_MISSMATCH: if the Content-Type Headers are not identical
+ * - INVALID_RESPONSE_DTYPE: if the data type is not supported by the Response Instance
+ */
+declare const sendGET: (input: IRequestInput, options?: Partial<IOptions>, retryAttempts?: number, retryDelaySeconds?: number) => Promise<IRequestResponse>;
+/**
+ * Builds and sends a POST HTTP Request based on the provided input and options.
+ * @param input
+ * @param options?
+ * @returns Promise<IRequestResponse>
+ * @throws
+ * - INVALID_REQUEST_URL: if the provided input URL cannot be parsed
+ * - INVALID_REQUEST_HEADERS: if invalid headers are passed in object format
+ * - INVALID_REQUEST_OPTIONS: if the Request Instance cannot be instantiated due to the passed opts
+ * - UNEXPECTED_RESPONSE_STATUS_CODE: if the code doesn't meet the requirements set in the options
+ * - CONTENT_TYPE_MISSMATCH: if the Content-Type Headers are not identical
+ * - INVALID_RESPONSE_DTYPE: if the data type is not supported by the Response Instance
+ */
+declare const sendPOST: (input: IRequestInput, options?: Partial<IOptions>) => Promise<IRequestResponse>;
+/**
+ * Builds and sends a PUT HTTP Request based on the provided input and options.
+ * @param input
+ * @param options?
+ * @returns Promise<IRequestResponse>
+ * @throws
+ * - INVALID_REQUEST_URL: if the provided input URL cannot be parsed
+ * - INVALID_REQUEST_HEADERS: if invalid headers are passed in object format
+ * - INVALID_REQUEST_OPTIONS: if the Request Instance cannot be instantiated due to the passed opts
+ * - UNEXPECTED_RESPONSE_STATUS_CODE: if the code doesn't meet the requirements set in the options
+ * - CONTENT_TYPE_MISSMATCH: if the Content-Type Headers are not identical
+ * - INVALID_RESPONSE_DTYPE: if the data type is not supported by the Response Instance
+ */
+declare const sendPUT: (input: IRequestInput, options?: Partial<IOptions>) => Promise<IRequestResponse>;
+/**
+ * Builds and sends a PATCH HTTP Request based on the provided input and options.
+ * @param input
+ * @param options?
+ * @returns Promise<IRequestResponse>
+ * @throws
+ * - INVALID_REQUEST_URL: if the provided input URL cannot be parsed
+ * - INVALID_REQUEST_HEADERS: if invalid headers are passed in object format
+ * - INVALID_REQUEST_OPTIONS: if the Request Instance cannot be instantiated due to the passed opts
+ * - UNEXPECTED_RESPONSE_STATUS_CODE: if the code doesn't meet the requirements set in the options
+ * - CONTENT_TYPE_MISSMATCH: if the Content-Type Headers are not identical
+ * - INVALID_RESPONSE_DTYPE: if the data type is not supported by the Response Instance
+ */
+declare const sendPATCH: (input: IRequestInput, options?: Partial<IOptions>) => Promise<IRequestResponse>;
+/**
+ * Builds and sends a DELETE HTTP Request based on the provided input and options.
+ * @param input
+ * @param options?
+ * @returns Promise<IRequestResponse>
+ * @throws
+ * - INVALID_REQUEST_URL: if the provided input URL cannot be parsed
+ * - INVALID_REQUEST_HEADERS: if invalid headers are passed in object format
+ * - INVALID_REQUEST_OPTIONS: if the Request Instance cannot be instantiated due to the passed opts
+ * - UNEXPECTED_RESPONSE_STATUS_CODE: if the code doesn't meet the requirements set in the options
+ * - CONTENT_TYPE_MISSMATCH: if the Content-Type Headers are not identical
+ * - INVALID_RESPONSE_DTYPE: if the data type is not supported by the Response Instance
+ */
+declare const sendDELETE: (input: IRequestInput, options?: Partial<IOptions>) => Promise<IRequestResponse>;
+export { IRequestInput, IRequestMethod, IRequestOptions, IResponseDataType, IOptions, IRequestResponse, send, sendGET, sendPOST, sendPUT, sendPATCH, sendDELETE, };

package/dist/index.js

@@ -0,0 +1 @@
+import{buildOptions,buildRequest,extractResponseData,delay}from"./utils/utils.js";import{validateResponse}from"./validations/validations.js";const send=async(e,t)=>{const s=buildOptions(t),n=buildRequest(e,s.requestOptions),d=await fetch(n);return validateResponse(n,d,s),d.redirected&&console.warn(`The request sent to '${n.url}' was redirected. Please update the implementation to avoid future redirections.`),{code:d.status,headers:d.headers,data:await extractResponseData(d,s.responseDataType)}},__executeSendGET=(e,t)=>send(e,{...t,requestOptions:{...t?.requestOptions,method:"GET"}}),sendGET=async(e,t,s,n)=>{try{return await __executeSendGET(e,t)}catch(d){if("number"==typeof s&&s>0)return await delay(n||3),sendGET(e,t,s-1,n);throw d}},sendPOST=(e,t)=>send(e,{...t,requestOptions:{...t?.requestOptions,method:"POST"}}),sendPUT=(e,t)=>send(e,{...t,requestOptions:{...t?.requestOptions,method:"PUT"}}),sendPATCH=(e,t)=>send(e,{...t,requestOptions:{...t?.requestOptions,method:"PATCH"}}),sendDELETE=(e,t)=>send(e,{...t,requestOptions:{...t?.requestOptions,method:"DELETE"}});export{send,sendGET,sendPOST,sendPUT,sendPATCH,sendDELETE};

package/dist/shared/errors.d.ts

@@ -0,0 +1,9 @@
+declare enum ERRORS {
+    INVALID_REQUEST_URL = "INVALID_REQUEST_URL",
+    INVALID_REQUEST_HEADERS = "INVALID_REQUEST_HEADERS",
+    INVALID_REQUEST_OPTIONS = "INVALID_REQUEST_OPTIONS",
+    INVALID_RESPONSE_DTYPE = "INVALID_RESPONSE_DTYPE",
+    UNEXPECTED_RESPONSE_STATUS_CODE = "UNEXPECTED_RESPONSE_STATUS_CODE",
+    CONTENT_TYPE_MISSMATCH = "CONTENT_TYPE_MISSMATCH"
+}
+export { ERRORS, };

package/dist/shared/errors.js

@@ -0,0 +1 @@
+var ERRORS;!function(E){E.INVALID_REQUEST_URL="INVALID_REQUEST_URL",E.INVALID_REQUEST_HEADERS="INVALID_REQUEST_HEADERS",E.INVALID_REQUEST_OPTIONS="INVALID_REQUEST_OPTIONS",E.INVALID_RESPONSE_DTYPE="INVALID_RESPONSE_DTYPE",E.UNEXPECTED_RESPONSE_STATUS_CODE="UNEXPECTED_RESPONSE_STATUS_CODE",E.CONTENT_TYPE_MISSMATCH="CONTENT_TYPE_MISSMATCH"}(ERRORS||(ERRORS={}));export{ERRORS};

package/dist/shared/types.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Request Input
+ * The URL of the request's target.
+ */
+type IRequestInput = string | URL;
+/**
+ * Request Options
+ * The options that can be applied when sending a Fetch Request.
+ * IMPORTANT: the reason RequestInit is extended is because in the original type, the body property
+ * does not accept plain objects. Even though this makes sense, the body is processed in the
+ * utilities so the Request's body is always instantiated with a string.
+ */
+interface IRequestOptions extends RequestInit {
+    method: IRequestMethod;
+    body: any;
+}
+/**
+ * Request Method
+ * The HTTP Methods supported by this library. To make use of a different one, pass the method name
+ * directly in the request options.
+ */
+type IRequestMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/**
+ * Response Data Type
+ * The type of data that will be extracted from the HTTP Response body.
+ */
+type IResponseDataType = 'arrayBuffer' | 'blob' | 'formData' | 'json' | 'text';
+/**
+ * Response Data
+ * The format of the data that can be extracted from the Response object.
+ */
+type IResponseData<T> = T extends 'arrayBuffer' ? ArrayBuffer : T extends 'blob' ? Blob : T extends 'formData' ? FormData : T extends 'json' ? any : T extends 'text' ? string : never;
+/**
+ * Options
+ * The options object that can be passed and used for any request.
+ */
+interface IOptions {
+    requestOptions?: Partial<IRequestOptions>;
+    responseDataType: IResponseDataType;
+    /**
+     * Response Status Codes
+     * The request's response can be validated by providing a list of acceptable codes or a range
+     * object. Keep in mind that if the acceptableStatusCodes array is provided, it will only perform
+     * that validation and ignore the acceptableStatusCodesRange.
+     */
+    acceptableStatusCodes?: number[];
+    acceptableStatusCodesRange: {
+        min: number;
+        max: number;
+    };
+}
+/**
+ * Request Response
+ * The object containing the result of the Request.
+ */
+interface IRequestResponse {
+    code: number;
+    headers: Headers;
+    data: any;
+}
+export type { IRequestInput, IRequestOptions, IRequestMethod, IResponseDataType, IResponseData, IOptions, IRequestResponse, };

package/dist/shared/types.js

@@ -0,0 +1 @@
+export{};

package/dist/utils/utils.d.ts

@@ -0,0 +1,34 @@
+import { IRequestInput, IResponseDataType, IResponseData, IRequestOptions, IOptions } from '../shared/types.js';
+/**
+ * Builds the Request Instance based on given input and options.
+ * @param input
+ * @param options
+ * @returns Request
+ * @throws
+ * - INVALID_REQUEST_URL: if the provided input URL cannot be parsed
+ * - INVALID_REQUEST_HEADERS: if invalid headers are passed in object format
+ * - INVALID_REQUEST_OPTIONS: if the Request Instance cannot be instantiated due to the passed opts
+ */
+declare const buildRequest: (input: IRequestInput, options?: Partial<IRequestOptions>) => Request;
+/**
+ * Extracts the data from the Response object based on the provided data type.
+ * @param res
+ * @param dType
+ * @returns Promise<IResponseData<T>>
+ * @throws
+ * - INVALID_RESPONSE_DTYPE: if the data type is not supported by the Response Instance
+ */
+declare const extractResponseData: <T extends IResponseDataType>(res: Response, dType: T) => Promise<IResponseData<T>>;
+/**
+ * Builds the main options object based on given args (if any).
+ * @param options
+ * @returns IOptions
+ */
+declare const buildOptions: (options?: Partial<IOptions>) => IOptions;
+/**
+ * Creates an asynchronous delay that resolves once the provided seconds have passed.
+ * @param seconds
+ * @returns Promise<void>
+ */
+declare const delay: (seconds: number) => Promise<void>;
+export { buildRequest, extractResponseData, buildOptions, delay, };

package/dist/utils/utils.js

@@ -0,0 +1 @@
+import{encodeError,isEncodedError}from"error-message-utils";import{ERRORS}from"../shared/errors.js";const __buildRequestInput=e=>{if(e instanceof URL)return e;try{return new URL(e)}catch(e){throw new Error(encodeError(e,ERRORS.INVALID_REQUEST_URL))}},__buildRequestHeaders=e=>{let r;if(e&&"object"==typeof e)try{r=new Headers(e)}catch(e){throw new Error(encodeError(e,ERRORS.INVALID_REQUEST_HEADERS))}else r=e instanceof Headers?e:new Headers({Accept:"application/json","Content-Type":"application/json"});return r.has("Accept")||r.append("Accept","application/json"),r.has("Content-Type")||r.append("Content-Type","application/json"),r},__buildRequestBody=e=>e?"object"==typeof e?JSON.stringify(e):e:null,__buildRequestOptions=(e={})=>{const r=e.method??"GET";return{method:r,mode:e.mode??"cors",cache:e.cache??"default",credentials:e.credentials??"same-origin",headers:__buildRequestHeaders(e.headers),priority:e.priority??"auto",redirect:e.redirect??"follow",referrer:e.referrer??"about:client",referrerPolicy:e.referrerPolicy??"no-referrer-when-downgrade",signal:e.signal,integrity:e.integrity||"",keepalive:e.keepalive??!1,body:"GET"===r?null:__buildRequestBody(e.body)}},buildRequest=(e,r)=>{try{return new Request(__buildRequestInput(e),__buildRequestOptions(r))}catch(e){if(isEncodedError(e))throw e;throw new Error(encodeError(e,ERRORS.INVALID_REQUEST_OPTIONS))}},extractResponseData=async(e,r)=>{switch(r){case"arrayBuffer":return e.arrayBuffer();case"blob":return e.blob();case"formData":return e.formData();case"json":return e.json();case"text":return e.text();default:throw new Error(encodeError(`The provided response data type '${r}' is invalid.`,ERRORS.INVALID_RESPONSE_DTYPE))}},buildOptions=(e={})=>({requestOptions:e.requestOptions,responseDataType:e.responseDataType??"json",acceptableStatusCodes:e.acceptableStatusCodes,acceptableStatusCodesRange:e.acceptableStatusCodesRange??{min:200,max:299}}),delay=e=>new Promise((r=>{setTimeout(r,1e3*e)}));export{buildRequest,extractResponseData,buildOptions,delay};

package/dist/validations/validations.d.ts

@@ -0,0 +1,12 @@
+import { IOptions } from '../shared/types.js';
+/**
+ * Validates the Response's status code and the Content-Type Header.
+ * @param req
+ * @param res
+ * @param options
+ * @throws
+ * - UNEXPECTED_RESPONSE_STATUS_CODE: if the code doesn't meet the requirements set in the options
+ * - CONTENT_TYPE_MISSMATCH: if the Content-Type Headers are not identical
+ */
+declare const validateResponse: (req: Request, res: Response, options: IOptions) => void;
+export { validateResponse, };

package/dist/validations/validations.js

@@ -0,0 +1 @@
+import{encodeError}from"error-message-utils";import{ERRORS}from"../shared/errors.js";const __buildUnexpectedCodeErrorMessage=e=>encodeError(`Request Failed: received unexpected response code '${e.status}': ${e.statusText}`,ERRORS.UNEXPECTED_RESPONSE_STATUS_CODE),__validateStatusCode=(e,t)=>{if(Array.isArray(t.acceptableStatusCodes)&&t.acceptableStatusCodes.length){if(!t.acceptableStatusCodes.includes(e.status))throw new Error(__buildUnexpectedCodeErrorMessage(e))}else if(e.status<t.acceptableStatusCodesRange.min||e.status>t.acceptableStatusCodesRange.max)throw new Error(__buildUnexpectedCodeErrorMessage(e))},__validateContentType=(e,t)=>{const r=e.headers.get("Accept"),s=t.headers.get("Content-Type");if(r!==s)throw new Error(encodeError(`The request's Accept Header '${r}' is different from the Content-Type received in the response '${s}'.`,ERRORS.CONTENT_TYPE_MISSMATCH))},validateResponse=(e,t,r)=>{__validateStatusCode(t,r),__validateContentType(e,t)};export{validateResponse};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "fetch-request-browser",
+  "version": "1.0.0",
+  "description": "The fetch-request-browser package makes working with external APIs simple and efficient. This intuitive wrapper leverages the power of the Fetch API, providing a clean and concise interface for your API interactions.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "start": "ts-lib-builder --tsconfig=tsconfig.build.json",
+    "test": "echo \"Error: tests are executed with  npm run test:(integration|unit)\" && exit 1",
+    "test:integration": "vitest run --config vitest.test-integration.config.ts",
+    "test:unit": "vitest run --config vitest.test-unit.config.ts",
+    "watch-test:integration": "vitest --config vitest.test-integration.config.ts",
+    "watch-test:unit": "vitest --config vitest.test-unit.config.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jesusgraterol/fetch-request-browser.git"
+  },
+  "keywords": [
+    "fetch",
+    "http",
+    "https",
+    "request",
+    "fetch-api",
+    "utils",
+    "utilities"
+  ],
+  "author": "Jesus Graterol",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/jesusgraterol/fetch-request-browser/issues"
+  },
+  "homepage": "https://github.com/jesusgraterol/fetch-request-browser#readme",
+  "devDependencies": {
+    "@types/node": "^20.13.0",
+    "@typescript-eslint/eslint-plugin": "^7.11.0",
+    "@typescript-eslint/parser": "^7.11.0",
+    "eslint-config-airbnb-typescript": "^18.0.0",
+    "ts-lib-builder": "^1.0.3",
+    "typescript": "^5.4.5",
+    "vitest": "^1.6.0"
+  },
+  "dependencies": {
+    "error-message-utils": "^1.1.0"
+  }
+}