Merge pull request #8

clean multipart and handlers to imports

Author: amanteaux

CHANGELOG.md

@@ -0,0 +1,13 @@
+Changelog
+-------------
+- Creation of a [Multipart HTTP client](src/lib/multipart/MultipartHttpClient.ts)
+  - Creation of a [OctetStreamType Validator](src/lib/client/FileFetchClient.ts) to handle octet stream responses 
+  - Creation of a [Raw Header Parser](src/lib/multipart/RawHeaderParser.ts) ot read headers from a xmlhttp response
+  - The use of the MultiPartHttpClient is demonstrated in the [README.md](README.md#upload-file) file
+- Moving generic Reponse Handlers to a [specific package](src/lib/handler) 
+  - [ResponseArrayBufferHandler](src/lib/handler/ResponseArrayBufferHandler.ts)
+  - [ResponseJsonHandler](src/lib/handler/ResponseJsonHandler.ts)
+  - [ResponseTextHandler](src/lib/handler/ResponseTextHandler.ts)
+- Moving generic Reponse Validators to a [specific package](src/lib/handler)
+  - [ValidateBasicStatusCodeHandler.ts](src/lib/handler/ValidateBasicStatusCodeHandler.ts)
+  - [ValidateContentTypeHandler.ts](src/lib/handler/ValidateContentTypeHandler.ts)

README.md

@@ -118,7 +118,7 @@ So a handler can:
 Expected results should be of type `Promise` of [HttpResponse](#httpresponse).
 
 Here are two samples usage:
-- A handler that validate the HTTP status code: <https://github.com/Coreoz/simple-http-rest-client/tree/master/src/lib/client/FetchStatusValidators.ts>
+- A handler that validate the HTTP status code: <https://github.com/Coreoz/simple-http-rest-client/tree/master/src/lib/handler/ValidateBasicStatusCodeHandler.ts>
 - A handler that return a JSON results (the function is named `toJsonResponse`): <https://github.com/Coreoz/simple-http-rest-client/tree/master/src/lib/client/JsonFetchClient.ts>
 
 ### HttpPromise
@@ -167,7 +167,7 @@ The goal here is to verify that the result is excepted and correct.
 By default, these validators are provided:
 - **validateBasicStatusCodes**: It raises an error if the status code is 403, and it returns an empty response if the status code is 200
 - **jsonContentTypeValidator**: It verifies the response content-type is JSON
-- **contentTypeValidator**: It is used to create response content-type validator like `jsonContentTypeValidator`
+- **validateContentType**: It is used to create response content-type validator like `jsonContentTypeValidator`
 
 Once validators are added, our API client should look like this:
 ```typescript

package.json

@@ -38,7 +38,7 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "simple-http-request-builder": "^2.0.1",
+    "simple-http-request-builder": "^2.1.0",
     "simple-logging-system": "^1.1.0"
   },
   "devDependencies": {

src/index.ts

@@ -1,18 +1,40 @@
-// content type validator
-export { contentTypeValidator } from './lib/client/ContentTypeValidator';
-// fetch client
+// clients
 export {
   fetchClientExecutor,
-  networkErrorCatcher,
   fetchClient,
   createHttpFetchRequest,
 } from './lib/client/FetchClient';
 export type {
-  FetchResponseHandler,
   HttpFetchClient,
 } from './lib/client/FetchClient';
-// fetch status validators
-export { validateBasicStatusCodes } from './lib/client/FetchStatusValidators';
+export {
+  multipartHttpFetchClient,
+  multipartHttpFetchClientExecutor,
+  createMultipartHttpFetchRequest,
+} from './lib/multipart/MultipartHttpClient';
+export type {
+  MultipartHttpFetchClient,
+} from './lib/multipart/MultipartHttpClient';
+// handlers
+export {
+  validateBasicStatusCodes,
+} from './lib/handler/ValidateBasicStatusCodeHandler';
+export { validateContentType } from './lib/handler/ValidateContentTypeHandler';
+export {
+  toJsonResponse, defaultJsonErrorMapper,
+} from './lib/handler/ResponseJsonHandler';
+export type {
+  JsonErrorMapper,
+} from './lib/handler/ResponseJsonHandler';
+export { toTextResponse } from './lib/handler/ResponseTextHandler';
+export { toArrayBufferResponse } from './lib/handler/ResponseArrayBufferHandler';
+export {
+  processHandlers,
+  networkErrorCatcher,
+} from './lib/handler/FetchResponseHandlers';
+export type {
+  FetchResponseHandler,
+} from './lib/handler/FetchResponseHandlers';
 // http response
 export type {
   HttpError,
@@ -27,16 +49,15 @@ export {
   timeoutError,
   forbiddenError,
 } from './lib/client/HttpResponse';
-// json fetch client
+// custom fetch clients
 export {
   jsonContentTypeValidator,
-  defaultJsonErrorMapper,
-  toJsonResponse,
   defaultJsonFetchClient,
 } from './lib/client/JsonFetchClient';
-export type {
-  JsonErrorMapper,
-} from './lib/client/JsonFetchClient';
+export {
+  octetStreamTypeValidator,
+  fileFetchClient,
+} from './lib/client/FileFetchClient';
 // http promise
 export {
   processHttpResponse,
@@ -52,3 +73,6 @@ export { PromiseMonitor } from './lib/promise/PromiseMonitor';
 export { HttpPromiseMonitor } from './lib/promise/HttpPromiseMonitor';
 // synchronized http promise
 export { SynchronizedHttpPromise } from './lib/promise/SynchronizedHttpPromise';
+
+// TODO to remove in the next future major release 3.x.x
+export { validateContentType as contentTypeValidator } from './lib/handler/ValidateContentTypeHandler';

src/lib/client/FetchClient.ts

@@ -1,17 +1,9 @@
 import {
   HttpClient, HttpMethod, HttpOptions, HttpRequest,
 } from 'simple-http-request-builder';
-import { Logger } from 'simple-logging-system';
 import { HttpPromise, unwrapHttpPromise } from '../promise/HttpPromise';
-import {
-  genericError,
-  HttpResponse,
-  networkError,
-  timeoutError,
-  toErrorResponsePromise,
-} from './HttpResponse';
-
-const logger = new Logger('FetchClient');
+import { processHandlers, FetchResponseHandler, networkErrorCatcher } from '../handler/FetchResponseHandlers';
+import { HttpResponse } from './HttpResponse';
 
 /**
  * A {@link HttpClient} that executes an {@link HttpRequest}
@@ -40,49 +32,10 @@ export const fetchClientExecutor: HttpClient<Promise<Response>> = (httpRequest:
     .finally(() => clearTimeout(timeoutHandle));
 };
 
-/**
- * Map {@link fetchClientExecutor} Promise errors to {@link HttpError}.
- * See {@link fetchClient} for reasons why these errors may occur.
- *
- * For now `AbortError` are mapped to {@link timeoutError} whereas all the other errors are mapped
- * to the generic {@link networkError}.
- *
- * @param error The raw {@link fetch} Promise {@link Error}
- */
-export const networkErrorCatcher = <T>(error: Error): HttpResponse<T> => {
-  if (error.name === 'AbortError') {
-    return {
-      error: timeoutError,
-    };
-  }
-  logger.warn('Cannot connect to HTTP server due to a network error', { error });
-  return {
-    error: networkError,
-  };
-};
-
-/**
- * Handlers are executed by {@link fetchClient} after a successful HTTP response is available:
- * this means an HTTP response has been received (whichever the response statut, 200, 400 or 500...).
- * These handlers will:
- * - Validate some preconditions and if necessary return an error result
- * - Return a result
- *
- * So a handler can:
- * - Either return a result (which can be a successful result or an error),
- * in that case following handlers **will not be executed**
- * - Either return `undefined`, in that case following handlers **will be executed**
- *
- * Expected results should be of type {@link Promise} of {@link HttpResponse}.
- */
-export interface FetchResponseHandler<T = unknown> {
-  (response: Response): Promise<HttpResponse<T>> | undefined;
-}
-
 /**
  * A {@link HttpClient} that uses:
  * - {@link fetchClientExecutor} to execute an {@link HttpRequest}
- * - {@link FetchResponseHandler handlers} to validate and transform the response
+ * - {@link FetchResponseHandler} handlers to validate and transform the response with {@link processHandlers}
  *
  * There are two outcomes for the execution of the {@link HttpRequest}:
  * - If the execution is successful (an HTTP response has been received),
@@ -92,29 +45,13 @@ export interface FetchResponseHandler<T = unknown> {
  * or that the request has been cancelled using the {@link HttpOptions#timeoutAbortController}
  * (see {@link HttpRequest#optionValues} for details),
  * or else it means there is a bug in the library...
- * in any case {@link networkErrorCatcher} will be executed to map the error to an {@link HttpError}
- *
- * If an {@link FetchResponseHandler handler} raises an error, a {@link genericError} will be returned
  *
  * @param httpRequest The {@link HttpRequest} to execute
  * @param handlers The {@link FetchResponseHandler}s to execute on an OK response (status code = 2xx)
  */
 export const fetchClient = <T = Response>(httpRequest: HttpRequest<unknown>, ...handlers: FetchResponseHandler[])
   : Promise<HttpResponse<T>> => <Promise<HttpResponse<T>>>fetchClientExecutor(httpRequest)
-    .then((response) => {
-      for (const handler of handlers) {
-        try {
-          const handlerResult = handler(response);
-          if (handlerResult !== undefined) {
-            return handlerResult;
-          }
-        } catch (error) {
-          logger.error('Error executing handler', { error });
-          return toErrorResponsePromise(genericError);
-        }
-      }
-      return { response };
-    })
+    .then((response: Response) => processHandlers(response, handlers))
     .catch(networkErrorCatcher);
 
 /**

src/lib/client/FileFetchClient.ts

@@ -1,50 +1,19 @@
 import { HttpRequest } from 'simple-http-request-builder';
-import { Logger } from 'simple-logging-system';
-import { contentTypeValidator } from './ContentTypeValidator';
-import { fetchClient, FetchResponseHandler } from './FetchClient';
-import { validateBasicStatusCodes } from './FetchStatusValidators';
-import { genericError, HttpResponse, toErrorResponsePromise } from './HttpResponse';
-import { defaultJsonErrorMapper, JsonErrorMapper, toJsonResponse } from './JsonFetchClient';
-
-const logger: Logger = new Logger('FileFetchClient');
-
-/**
- * A {@link FetchResponseHandler} that tries to retrieve the array buffer of the {@link Response} body
- * - If the {@link Response} body is not a valid array buffer,
- * {@link HttpResponse#error} will contain a {@link genericError}
- * - If the HTTP response is successful (status code is 2xx),
- * {@link HttpResponse#response} will contain the array buffer
- * - If the HTTP response is not successful (status code is not 2xx),
- * the {@link JsonErrorMapper} will be executed to return a {@link HttpResponse}
- *
- * @param response The {@link Response} to parse
- * @param jsonErrorMapper The {@link JsonErrorMapper} that will handle the parsed JSON object in case
- * the HTTP response is not successful (status code is not 2xx)
- */
-export const toArrayBufferResponse = async (
-  response: Response,
-  jsonErrorMapper: JsonErrorMapper = defaultJsonErrorMapper,
-): Promise<HttpResponse<unknown>> => {
-  if (response.ok) {
-    try {
-      return {
-        response: await response.arrayBuffer(),
-      };
-    } catch (error) {
-      logger.warn('Response could not be read as an array buffer');
-      return toErrorResponsePromise(genericError);
-    }
-  }
-
-  return toJsonResponse(response, jsonErrorMapper);
-};
+import { FetchResponseHandler } from '../handler/FetchResponseHandlers';
+import { toArrayBufferResponse } from '../handler/ResponseArrayBufferHandler';
+import {
+  validateBasicStatusCodes,
+} from '../handler/ValidateBasicStatusCodeHandler';
+import { validateContentType } from '../handler/ValidateContentTypeHandler';
+import { fetchClient } from './FetchClient';
+import { HttpResponse } from './HttpResponse';
 
 /**
  * Validate that the content-type header of the response is 'application/octet-stream'
  * @param response The {@link Response} to validate
  */
 export const octetStreamTypeValidator: FetchResponseHandler = (response: Response) => (
-  contentTypeValidator(response, 'application/octet-stream')
+  validateContentType(response, 'application/octet-stream')
 );
 
 /**

src/lib/client/JsonFetchClient.ts

@@ -1,84 +1,21 @@
-import { Logger } from 'simple-logging-system';
 import { HttpRequest } from 'simple-http-request-builder';
-import { genericError, HttpResponse } from './HttpResponse';
+import { toJsonResponse } from '../handler/ResponseJsonHandler';
+import { validateContentType } from '../handler/ValidateContentTypeHandler';
 import { fetchClient, FetchResponseHandler } from './FetchClient';
-import { validateBasicStatusCodes } from './FetchStatusValidators';
-import { contentTypeValidator } from './ContentTypeValidator';
-
-const logger = new Logger('JsonFetchClient');
+import { validateBasicStatusCodes } from '../handler/ValidateBasicStatusCodeHandler';
+import { HttpResponse } from './HttpResponse';
 
 /**
  * A {@link FetchResponseHandler} that verify that the content type of a {@link Response} is JSON
  * using the `content-type` response HTTP header.
  *
- * See {@link contentTypeValidator} for the content type validation.
+ * See {@link validateContentType} for the content type validation.
  *
  * @param response The {@link Response} to validate
  */
-export const jsonContentTypeValidator:
-FetchResponseHandler = (response: Response) => contentTypeValidator(response, 'json');
-
-/**
- * A mapper that will handle non-successful HTTP responses that have however a JSON body.
- *
- * This mapper generally returns an {@link HttpResponse#error} containing the matching `errorCode`.
- * But if necessary it can return a {@link HttpResponse#response}.
- *
- * See the default implementation: {@link defaultJsonErrorMapper}.
- *
- * @param response The non-successful HTTP {@link Response}
- * @param json The parsed JSON object
- */
-// any is the returned type of the Fetch.json() Promise
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type JsonErrorMapper = (response: Response, json: any) => HttpResponse<unknown>;
-
-/**
- * The default {@link JsonErrorMapper} implementation that returns an {@link HttpResponse#error} containing:
- * - The HTTP response body JSON object if it contains a {@link HttpError#errorCode} attribute
- * - Else a {@link genericError}
- */
-export const defaultJsonErrorMapper: JsonErrorMapper = (response: Response, json) => {
-  if (typeof json.errorCode === 'undefined') {
-    logger.warn('Unrecognized JSON error', { response });
-    return { error: genericError };
-  }
-  return { error: json };
-};
-
-/**
- * A {@link FetchResponseHandler} that tries to convert the {@link Response} JSON body
- * to an {@link HttpResponse}:
- * - If the {@link Response} body is not a valid JSON object,
- * {@link HttpResponse#error} will contain a {@link genericError}
- * - If the HTTP response is successful (status code is 2xx),
- * {@link HttpResponse#response} will contain the JSON parsed object
- * - If the HTTP response is not successful (status code is not 2xx),
- * the {@link JsonErrorMapper} will be executed to return a {@link HttpResponse}
- *
- * @param response The {@link Response} to parse
- * @param jsonErrorMapper The {@link JsonErrorMapper} that will handle the parsed JSON object in case
- * the HTTP response is not successful (status code is not 2xx)
- */
-export const toJsonResponse = (
+export const jsonContentTypeValidator: FetchResponseHandler = (
   response: Response,
-  jsonErrorMapper: JsonErrorMapper = defaultJsonErrorMapper,
-): Promise<HttpResponse<unknown>> => response
-  .json()
-  .then((json) => {
-    if (response.ok) {
-      return {
-        response: json,
-      };
-    }
-    return jsonErrorMapper(response, json);
-  })
-  .catch((error) => {
-    logger.error('Cannot parse JSON', { error });
-    return {
-      error: genericError,
-    };
-  });
+) => validateContentType(response, 'json');
 
 /**
  * A {@link HttpClient} that executes an {@link HttpRequest} that returns JSON responses.