refactor: @/express and @/fastify

CHANGELOG.md

@@ -1,15 +1,43 @@
 # ⏭ vNext
 
 - Documentation improvements
+- Factors out Express and Fastify specific code to `@alterior/express` and `@alterior/fastify`. As part of this, 
+  you must now import `@alterior/express` or `@alterior/fastify` and specify it as the web server engine from this 
+  version on. For example:
+  ```typescript
+  // main.ts
+  import { WebServerEngine } from '@alterior/web-server';
+  import { ExpressEngine } from '@alterior/express';
+
+  WebServerEngine.default = ExpressEngine;
+  ```
+  Alternatively you can specify an engine via dependency injection:
+  ```typescript
+  @WebService({
+      providers: [
+          { provide: WebServerEngine, useClass: ExpressEngine }
+      ]
+  })
+  export class MyService {
+      // ...
+  }
+  ```
+  This change reduces the complexity of Alterior's dependency tree by ensuring that excess web server dependencies 
+  will not be present (ie fastify on an express app or express on a fastify app). It also fixes an issue where Alterior
+  users were required to install a lot of Express-related `@types/*` packages to avoid Typescript errors during 
+  development.
 
 `@/runtime`
 - The `--self-test` option no longer starts the application (so the `OnStart` lifecycle method does not execute)
 
 `@/web-server`
 - Adds support for automatic conversion of boolean values when using `@QueryParam()` on a parameter of type `boolean`.
-The values `''`, `'no'`, `'0'`, `'false'`, and `'off'` produce `false`, all other values produce `true`.
-- Adds support for receiving the ID for the request from a request header (ie `X-Trace` or so). Not enabled by default. Use `requestIdHeader` option when configuring the web server to enable this functionality.
+  The values `''`, `'no'`, `'0'`, `'false'`, and `'off'` produce `false`, all other values produce `true`.
+- Adds support for receiving the ID for the request from a request header (ie `X-Trace` or so). Not enabled by default. 
+  Use `requestIdHeader` option when configuring the web server to enable this functionality.
 - Fixes an issue where request ID was wastefully generated twice
+- Removed the `engine` option from `WebServerOptions`. Either set `WebServerEngine.default` or provide `WebServerEngine` 
+  as a dependency to specify the web engine. See above for details.
 
 # 🚀 3.0.0-rc.4
 

packages/express/README.md

@@ -0,0 +1,26 @@
+# @/express
+
+Access Express state within an Alterior app. 
+
+# Why?
+
+`@alterior/web-server` provides `WebEvent.request` which exposes the HTTP request object of the underlying web server framework being used. Alterior supports more than one framework, including `express` and `fastify`. Technically the minimum shape of `WebEvent.request` is that of the `request` object defined by the Node.js `http` module. As an app developer which uses Express as the server framework in my Alterior app, I want to access `WebEvent.request` with a Typescript type that exposes all that Express provides, not just as a generic Node.js `http` request object. I don't want to manually cast this object whenever I use it.
+
+Since `WebEvent.request` is static (using the HTTP request's Zone to determine the appropriate value), we can create new ways to access this value which are appropriately typed.
+
+Splitting this functionality into a specific package lets us remove unused code when not using Express.
+
+# How
+
+```typescript
+import { ExpressContext } from '@alterior/express';
+// ...
+
+@WebService() 
+export class MyService {
+    @Get()
+    info() {
+        console.log(`user agent is: ${ExpressContext.request.header('User-Agent')}`);
+    }
+}
+```