@travetto/web 6.0.0-rc.5 → 6.0.0

package/README.md

@@ -2,7 +2,7 @@
 <!-- Please modify https://github.com/travetto/travetto/tree/main/module/web/DOC.tsx and execute "npx trv doc" to rebuild -->
 # Web API
 
-## Declarative api for Web Applications with support for the dependency injection.
+## Declarative support creating for Web Applications
 
 **Install: @travetto/web**
 ```bash
@@ -16,11 +16,10 @@ yarn add @travetto/web
 The module provides a declarative API for creating and describing a Web application.  Since the framework is declarative, decorators are used to configure almost everything. The general layout of an application is a collection of [@Controller](https://github.com/travetto/travetto/tree/main/module/web/src/decorator/controller.ts#L9)s that employ some combination of [WebInterceptor](https://github.com/travetto/travetto/tree/main/module/web/src/types/interceptor.ts#L15)s to help manage which functionality is executed before the [Endpoint](https://github.com/travetto/travetto/tree/main/module/web/src/decorator/endpoint.ts#L14) code, within the [@Controller](https://github.com/travetto/travetto/tree/main/module/web/src/decorator/controller.ts#L9). This module will look at:
    *  Request/Response Pattern
    *  Defining a [@Controller](https://github.com/travetto/travetto/tree/main/module/web/src/decorator/controller.ts#L9)
-   *  Defining an [Endpoint](https://github.com/travetto/travetto/tree/main/module/web/src/decorator/endpoint.ts#L14)s
-   *  Using [WebInterceptor](https://github.com/travetto/travetto/tree/main/module/web/src/types/interceptor.ts#L15)s
+   *  Defining an [Endpoint](https://github.com/travetto/travetto/tree/main/module/web/src/decorator/endpoint.ts#L14)
+   *  Using a [WebInterceptor](https://github.com/travetto/travetto/tree/main/module/web/src/types/interceptor.ts#L15)
    *  Creating a Custom [WebInterceptor](https://github.com/travetto/travetto/tree/main/module/web/src/types/interceptor.ts#L15)
    *  Cookies
-   *  Error Handling
 
 ## Request/Response Pattern
 Unlike other frameworks (e.g. [express](https://expressjs.com), [fastify](https://www.fastify.io/)), this module takes an approach that is similar to [AWS Lambda](https://aws.amazon.com/lambda/)'s model for requests and responses. What you can see here is that [WebRequest](https://github.com/travetto/travetto/tree/main/module/web/src/types/request.ts#L11) and [WebResponse](https://github.com/travetto/travetto/tree/main/module/web/src/types/response.ts#L3) are very simple objects, with the focus being on the `payload` and `body`.  This is intended to provide maximal compatibility with non-HTTP sources.  The driving goal is to support more than just standard HTTP servers but also allow for seamless integration with tools like event queues, web sockets, etc.
@@ -57,7 +56,6 @@ export interface WebRequestContext {
 
 /**
  * Web Request object
- * @web_contextual
  */
 export class WebRequest<B = unknown> extends BaseWebMessage<B, Readonly<WebRequestContext>> {
 
@@ -74,7 +72,6 @@ export interface WebResponseContext {
 
 /**
  * Web Response as a simple object
- * @web_invalid_parameter
  */
 export class WebResponse<B = unknown> extends BaseWebMessage<B, WebResponseContext> {
 
@@ -729,7 +726,28 @@ export class SimpleAuthInterceptor implements WebInterceptor {
 ```
 
 ## Cookie Support
-[express](https://expressjs.com)/[koa](https://koajs.com/)/[fastify](https://www.fastify.io/) all have their own cookie implementations that are common for each framework but are somewhat incompatible.  To that end, cookies are supported for every platform, by using [cookies](https://www.npmjs.com/package/cookies).  This functionality is exposed onto the [WebRequest](https://github.com/travetto/travetto/tree/main/module/web/src/types/request.ts#L11) object following the pattern set forth by Koa (this is the library Koa uses).  This choice also enables better security support as we are able to rely upon standard behavior when it comes to cookies, and signing.
+Cookies are a unique element, within the framework, as they sit on the request and response flows.  Ideally we would separate these out, but given the support for key rotation, there is a scenario in which reading a cookie on the request, will result in a cookie needing to be written on the response.  Because of this, cookies are treated as being outside the normal [WebRequest](https://github.com/travetto/travetto/tree/main/module/web/src/types/request.ts#L11) activity, and is exposed as the [@ContextParam](https://github.com/travetto/travetto/tree/main/module/web/src/decorator/param.ts#L61) [CookieJar](https://github.com/travetto/travetto/tree/main/module/web/src/util/cookie.ts#L11).  The [CookieJar](https://github.com/travetto/travetto/tree/main/module/web/src/util/cookie.ts#L11) has a fairly basic contract:
+
+**Code: CookieJar contract**
+```typescript
+export class CookieJar {
+  static parseCookieHeader(header: string): Cookie[];
+  static parseSetCookieHeader(header: string): Cookie;
+  static responseSuffix(c: Cookie): string[];
+  constructor({ keys, ...options }: CookieJarOptions = {});
+  import(cookies: Cookie[]): this;
+  has(name: string, opts: CookieGetOptions = {}): boolean;
+  get(name: string, opts: CookieGetOptions = {}): string | undefined;
+  set(cookie: Cookie): void;
+  getAll(): Cookie[];
+  importCookieHeader(header: string | null | undefined): this;
+  importSetCookieHeader(headers: string[] | null | undefined): this;
+  exportCookieHeader(): string;
+  exportSetCookieHeader(): string[];
+}
+```
+
+`.get()`/`.set()` will be the most commonly used methods, and should align with standard cookie reading/writing behavior.
 
 **Code: Sample Cookie Usage**
 ```typescript
@@ -760,6 +778,3 @@ export class SimpleEndpoints {
   }
 }
 ```
-
-## Full Config
-The entire [WebConfig](https://github.com/travetto/travetto/tree/main/module/web/src/config.ts#L7) which will show the full set of valid configuration parameters for the web module.

package/package.json

@@ -1,10 +1,9 @@
 {
   "name": "@travetto/web",
-  "version": "6.0.0-rc.5",
-  "description": "Declarative api for Web Applications with support for the dependency injection.",
+  "version": "6.0.0",
+  "description": "Declarative support creating for Web Applications",
   "keywords": [
     "web",
-    "dependency-injection",
     "decorators",
     "travetto",
     "typescript"
@@ -26,12 +25,12 @@
     "directory": "module/web"
   },
   "dependencies": {
-    "@travetto/config": "^6.0.0-rc.2",
-    "@travetto/context": "^6.0.0-rc.2",
-    "@travetto/di": "^6.0.0-rc.2",
-    "@travetto/registry": "^6.0.0-rc.2",
-    "@travetto/runtime": "^6.0.0-rc.2",
-    "@travetto/schema": "^6.0.0-rc.2",
+    "@travetto/config": "^6.0.0",
+    "@travetto/context": "^6.0.0",
+    "@travetto/di": "^6.0.0",
+    "@travetto/registry": "^6.0.0",
+    "@travetto/runtime": "^6.0.0",
+    "@travetto/schema": "^6.0.0",
     "@types/fresh": "^0.5.2",
     "@types/keygrip": "^1.0.6",
     "@types/negotiator": "^0.6.3",
@@ -41,9 +40,9 @@
     "negotiator": "^1.0.0"
   },
   "peerDependencies": {
-    "@travetto/cli": "^6.0.0-rc.3",
-    "@travetto/test": "^6.0.0-rc.3",
-    "@travetto/transformer": "^6.0.0-rc.3"
+    "@travetto/cli": "^6.0.0",
+    "@travetto/test": "^6.0.0",
+    "@travetto/transformer": "^6.0.0"
   },
   "peerDependenciesMeta": {
     "@travetto/transformer": {

package/src/types/request.ts

@@ -18,7 +18,6 @@ export interface WebRequestContext {
 
 /**
  * Web Request object
- * @web_contextual
  */
 export class WebRequest<B = unknown> extends BaseWebMessage<B, Readonly<WebRequestContext>> {
 

package/src/types/response.ts

@@ -6,7 +6,6 @@ export interface WebResponseContext {
 
 /**
  * Web Response as a simple object
- * @web_invalid_parameter
  */
 export class WebResponse<B = unknown> extends BaseWebMessage<B, WebResponseContext> {
 

package/support/transformer.web.ts

@@ -56,10 +56,10 @@ export class WebTransformer {
       config.name = '';
     }
 
-    if (paramType.key === 'managed' && paramType.original) {
-      if (DocUtil.hasDocTag(paramType.original, 'web_contextual')) {
+    if (paramType.key === 'managed' && paramType.importName.startsWith('@travetto/')) {
+      if (paramType.name === 'WebResponse') {
         throw new Error(`${paramType.name} must be registered using @ContextParam`);
-      } else if (DocUtil.hasDocTag(paramType.original, 'web_invalid_parameter')) {
+      } else if (paramType.name === 'WebRequest') {
         throw new Error(`${paramType.name} is an invalid endpoint parameter`);
       }
     }