docs(readme): improve documentation

packages/whook-http-router/src/index.ts

@@ -514,8 +514,8 @@ async function initHTTPRouter<T extends WhookHandler>({
 
           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<T extends WhookHandler>({
   }
 }
 
-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<T extends WhookHandler>({
 
     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),
     );
   });

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)
 

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)