From 5fc529ead2ce3feb38cf96612c19abe06dda6ff2 Mon Sep 17 00:00:00 2001 From: Nicolas Froidure Date: Fri, 29 Sep 2023 09:42:16 +0200 Subject: [PATCH] docs(readme): improve documentation Add better explanations and add some lacking types --- packages/whook-http-router/src/index.ts | 14 ++++++++---- packages/whook-http-server/README.md | 19 ++++++++++------ packages/whook-http-transaction/README.md | 27 +++++++++++++---------- 3 files changed, 37 insertions(+), 23 deletions(-) diff --git a/packages/whook-http-router/src/index.ts b/packages/whook-http-router/src/index.ts index 7f17ea81..404d4d6a 100644 --- a/packages/whook-http-router/src/index.ts +++ b/packages/whook-http-router/src/index.ts @@ -514,8 +514,8 @@ async function initHTTPRouter({ if (castedResponse.body && 'head' === request.method) { log( - 'warning', - 'Body stripped:', + 'debug', + '💇 - Body stripped:', castedResponse.body instanceof Stream ? 'Stream' : castedResponse.body, @@ -545,7 +545,10 @@ async function initHTTPRouter({ } } -function _explodePath(path, parameters) { +function _explodePath( + path: string, + parameters: DereferencedParameterObject[], +): (string | DereferencedParameterObject)[] { return path .split(PATH_SEPARATOR) .filter(identity) @@ -631,7 +634,10 @@ async function _createRouters({ routers[method] = routers[method] || new Siso(); routers[method].register( - _explodePath(BASE_PATH + path, pathParameters), + _explodePath( + BASE_PATH + path, + pathParameters as unknown[] as DereferencedParameterObject[], + ), _prepareRoute({ ajv }, operation, handler, ammendedParameters), ); }); diff --git a/packages/whook-http-server/README.md b/packages/whook-http-server/README.md index 342c7477..c91845be 100644 --- a/packages/whook-http-server/README.md +++ b/packages/whook-http-server/README.md @@ -12,13 +12,18 @@ [//]: # (::contents:start) -The [Whook](https://github.com/nfroidure/whook)'s `httpServer` service - is responsible for instanciating the NodeJS HTTP Server and handling - its start/shutdown. - -It can be easily replaced by any other HTTP server (an HTTPS one for - instance if you cannot use a gateway or a proxy to handle HTTPS - connections). +The [Whook](https://github.com/nfroidure/whook)'s `httpServer` service is +responsible for instanciating the NodeJS HTTP Server and handling its +start/shutdown. + +It can be easily replaced by any other HTTP server (an HTTPS one for instance if +you cannot use a gateway or a proxy to handle HTTPS connections). + +The server takes in charge graceful shutdown by awaiting connections to be +closed before shutting down which can take a long time (basically if a browser +is still maintaining an open socket with it). You can short circuit this +behavior, basically for development, by setting the `DESTROY_SOCKETS=1` +environment variable. [//]: # (::contents:end) diff --git a/packages/whook-http-transaction/README.md b/packages/whook-http-transaction/README.md index 8839263e..aa03b5c5 100644 --- a/packages/whook-http-transaction/README.md +++ b/packages/whook-http-transaction/README.md @@ -12,18 +12,21 @@ [//]: # (::contents:start) -[Whook](https://github.com/nfroidure/whook) takes a very unusual direction - when it comes to dealing with HTTP transactions. It makes requests and - responses serializable to: -- only work with functions that take request and return responses ( - allowing your handlers to be pure functions), -- have [easily unit testable](https://github.com/nfroidure/whook/blob/e7470fed860a8e1644b15625c9db4dd8198b70a6/packages/whook-example/src/handlers/putEcho.test.js) - handlers thanks to concise snapshots. - -This service is intended to build those objects from Node HTTP ones - before passing them to the handlers. It also keeps track of running - queries and ensure it is well handled by the server before releasing - it. +[Whook](https://github.com/nfroidure/whook) takes a very unusual direction when +it comes to dealing with HTTP transactions. It makes requests and responses +serializable (thanks to `WhookRequest` and `WhookResponse` types) to: + +- only work with functions that take request and return responses ( allowing + your handlers to be pure functions), +- have + [easily unit testable](https://github.com/nfroidure/whook/blob/e7470fed860a8e1644b15625c9db4dd8198b70a6/packages/whook-example/src/handlers/putEcho.test.js) + handlers thanks to concise snapshots. + +This service is intended to build those litteral objects from Node HTTP ones +(famously known as req/res) before passing them to the handlers. It also keeps +track of running queries and ensure it is well handled by the server before +releasing it. If not, the transaction is resolved with an error response (for +timeouts or when an error were catched). [//]: # (::contents:end)