@travetto/schema 3.0.2 → 3.1.0-rc.0

package/README.md

@@ -1,6 +1,7 @@
 <!-- This file was generated by @travetto/doc and should not be modified directly -->
-<!-- Please modify https://github.com/travetto/travetto/tree/main/module/schema/DOC.ts and execute "npx trv doc" to rebuild -->
+<!-- Please modify https://github.com/travetto/travetto/tree/main/module/schema/DOC.tsx and execute "npx trv doc" to rebuild -->
 # Schema
+
 ## Data type registry for runtime validation, reflection and binding.
 
 **Install: @travetto/schema**
@@ -12,23 +13,18 @@ npm install @travetto/schema
 yarn add @travetto/schema
 ```
 
-This module's purpose is to allow for proper declaration and validation of data types, in the course of running a program.  The framework defined here, is 
-leveraged in the [Configuration](https://github.com/travetto/travetto/tree/main/module/config#readme "Configuration support"), [Application](https://github.com/travetto/travetto/tree/main/module/app#readme "Application registration/management and run support."), [RESTful API](https://github.com/travetto/travetto/tree/main/module/rest#readme "Declarative api for RESTful APIs with support for the dependency injection module."), [OpenAPI Specification](https://github.com/travetto/travetto/tree/main/module/openapi#readme "OpenAPI integration support for the Travetto framework") and [Data Modeling Support](https://github.com/travetto/travetto/tree/main/module/model#readme "Datastore abstraction for core operations.") modules.  The schema is the backbone of all data transfer, as it helps to
-provide validation on correctness of input, whether it is a rest request, command line inputs, or a configuration file.
+This module's purpose is to allow for proper declaration and validation of data types, in the course of running a program.  The framework defined here, is leveraged in the [Configuration](https://github.com/travetto/travetto/tree/main/module/config#readme "Configuration support"), [Command Line Interface](https://github.com/travetto/travetto/tree/main/module/cli#readme "CLI infrastructure for Travetto framework"), [RESTful API](https://github.com/travetto/travetto/tree/main/module/rest#readme "Declarative api for RESTful APIs with support for the dependency injection module."), [OpenAPI Specification](https://github.com/travetto/travetto/tree/main/module/openapi#readme "OpenAPI integration support for the Travetto framework") and [Data Modeling Support](https://github.com/travetto/travetto/tree/main/module/model#readme "Datastore abstraction for core operations.") modules.  The schema is the backbone of all data transfer, as it helps to provide validation on correctness of input, whether it is a rest request, command line inputs, or a configuration file. 
 
 This module provides a mechanism for registering classes and field level information as well the ability to apply that information at runtime.
 
 ## Registration
-The registry's schema information is defined by [Typescript](https://typescriptlang.org) AST and only applies to classes registered with the [@Schema](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/schema.ts#L14) decoration. 
+The registry's schema information is defined by [Typescript](https://typescriptlang.org) AST and only applies to classes registered with the [@Schema](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/schema.ts#L14) decoration.
 
 ### Classes
 The module utilizes AST transformations to collect schema information, and facilitate the registration process without user intervention. The class can also be described using providing a:
-
-   
    *  `title` - definition of the schema
    *  `description` - detailed description of the schema
    *  `examples` - A set of examples as [JSON](https://www.json.org) or [YAML](https://en.wikipedia.org/wiki/YAML)
-
 The `title` will be picked up from the [JSDoc](http://usejsdoc.org/about-getting-started.html) comments, and additionally all fields can be set using the [@Describe](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/common.ts#L15) decorator.
 
 **Code: Sample User Schema**
@@ -66,8 +62,6 @@ User:
 
 ### Fields
 This schema provides a powerful base for data binding and validation at runtime.  Additionally there may be types that cannot be detected, or some information that the programmer would like to override. Below are the supported field decorators:
-
-   
    *  [@Field](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L38) defines a field that will be serialized.
    *  [@Required](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L78) defines a that field should be required
    *  [@Enum](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L85) defines the allowable values that a field can have
@@ -87,15 +81,11 @@ This schema provides a powerful base for data binding and validation at runtime.
    *  [@LongText](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L98) same as text, but expects longer form content
    *  [@Readonly](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L65) defines a that field should not be bindable external to the class
    *  [@Writeonly](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L59) defines a that field should not be exported in serialization, but that it can be bound to
-
-Additionally, schemas can be nested to form more complex data structures that are able to bound and validated.
+Additionally, schemas can be nested to form more complex data structures that are able to bound and validated. 
 
 Just like the class, all fields can be defined with
-
-   
    *  `description` - detailed description of the schema
    *  `examples` - A set of examples as [JSON](https://www.json.org) or [YAML](https://en.wikipedia.org/wiki/YAML)
-
 And similarly, the `description` will be picked up from the [JSDoc](http://usejsdoc.org/about-getting-started.html) comments, and additionally all fields can be set using the [@Describe](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/common.ts#L15) decorator.
 
 ## Binding/Validation
@@ -156,7 +146,6 @@ Person {
 **Note**: Binding will attempt to convert/coerce types as much as possible to honor the pattern of Javascript and it's dynamic nature.
 
 ### Validation
-
 Validation is very similar to binding, but instead of attempting to assign values, any mismatch or violation of the schema will result in errors. All errors will be collected and returned. Given the same schema as above,
 
 **Code: Sub Schemas via Address**
@@ -214,12 +203,13 @@ Validation Failed {
   "errors": [
     {
       "kind": "type",
+      "type": "number",
       "message": "age is not a valid number",
-      "path": "age",
-      "type": "number"
+      "path": "age"
     },
     {
       "kind": "required",
+      "active": true,
       "message": "address.street2 is required",
       "path": "address.street2"
     }
@@ -228,7 +218,6 @@ Validation Failed {
 ```
 
 ### Custom Validators
-
 Within the schema framework, it is possible to add custom validators class level.  This allows for more flexibility when dealing with specific situations (e.g. password requirements or ensuring two fields match)
 
 **Code: Password Validator**
@@ -281,6 +270,10 @@ export interface ValidationError {
    * Regular expression to match
    */
   re?: string;
+  /**
+   * Number to compare against
+   */
+  n?: number | Date;
   /**
    * The type of the field
    */
@@ -289,7 +282,7 @@ export interface ValidationError {
 ```
 
 ## Custom Types
-When working with the schema, the basic types are easily understood, but some of [Typescript](https://typescriptlang.org)'s more complex constructs are too complex to automate cleanly.
+When working with the schema, the basic types are easily understood, but some of [Typescript](https://typescriptlang.org)'s more complex constructs are too complex to automate cleanly. 
 
 To that end, the module supports two concepts:
 
@@ -324,8 +317,6 @@ export class PointImpl {
 ```
 
 What you can see here is that the `Point` type is now backed by a class that supports:
-
-   
    *  `validateSchema` - Will run during validation for this specific type.
    *  `bindSchema` - Will run during binding to ensure correct behavior.
 
@@ -355,9 +346,9 @@ Validation Failed {
   "errors": [
     {
       "kind": "type",
+      "type": "PointImpl",
       "message": "point is not a valid PointImpl",
-      "path": "point",
-      "type": "PointImpl"
+      "path": "point"
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travetto/schema",
-  "version": "3.0.2",
+  "version": "3.1.0-rc.0",
   "description": "Data type registry for runtime validation, reflection and binding.",
   "keywords": [
     "schema",
@@ -27,10 +27,10 @@
     "directory": "module/schema"
   },
   "dependencies": {
-    "@travetto/registry": "^3.0.2"
+    "@travetto/registry": "^3.1.0-rc.0"
   },
   "peerDependencies": {
-    "@travetto/transformer": "^3.0.2"
+    "@travetto/transformer": "^3.1.0-rc.0"
   },
   "peerDependenciesMeta": {
     "@travetto/transformer": {

package/src/service/registry.ts

@@ -233,7 +233,7 @@ class $SchemaRegistry extends MetadataRegistry<ClassConfig, FieldConfig> {
       const { fields, schema } = this.getViewSchema(cls);
       const out = [];
       for (const el of fields) {
-        if (el.startsWith(`${method}.`)) {
+        if (el.startsWith(`${method}.`) && schema[el].forMethod) {
           out.push(schema[el]);
         }
       }
@@ -302,6 +302,7 @@ class $SchemaRegistry extends MetadataRegistry<ClassConfig, FieldConfig> {
   registerPendingParamConfig(target: Class, method: string, idx: number, type: ClassList, conf?: Partial<FieldConfig>): Class {
     conf ??= {};
     conf.index = idx;
+    conf.forMethod = true;
     return this.registerPendingFieldConfig(target, `${method}.${idx}`, type, conf);
   }
 

package/src/service/types.ts

@@ -160,6 +160,10 @@ export interface FieldConfig extends DescribableConfig {
    * Is this field a getter or setter
    */
   accessor?: string;
+  /**
+   * Is the field for a method
+   */
+  forMethod?: boolean;
 }
 
 export type ViewFieldsConfig<T> = { with: Extract<(keyof T), string>[] } | { without: Extract<(keyof T), string>[] };

package/src/validate/types.ts

@@ -25,6 +25,10 @@ export interface ValidationError {
    * Regular expression to match
    */
   re?: string;
+  /**
+   * Number to compare against
+   */
+  n?: number | Date;
   /**
    * The type of the field
    */
@@ -55,6 +59,10 @@ export interface ValidationResult {
    * Potential regular expression for the result
    */
   re?: RegExp;
+  /**
+   * Number to compare against
+   */
+  n?: number | Date;
 }
 
 /**

package/src/validate/validator.ts

@@ -40,7 +40,7 @@ export class SchemaValidator {
 
     const fields = TypedObject.keys<SchemaConfig>(schema);
     for (const field of fields) {
-      if (schema[field].access !== 'readonly') { // Do not validate readonly fields
+      if (schema[field].access !== 'readonly' && !schema[field].forMethod) { // Do not validate readonly fields
         // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
         errors = errors.concat(this.#validateFieldSchema(schema[field], o[field as keyof T], relative));
       }
@@ -202,6 +202,7 @@ export class SchemaValidator {
     const out: ValidationError[] = [];
     for (const res of results) {
       const err: ValidationError = {
+        ...res,
         kind: res.kind,
         value: res.value,
         message: '',
@@ -311,7 +312,7 @@ export class SchemaValidator {
    * @param method The method being invoked
    * @param params The params to validate
    */
-  static validateMethod<T>(cls: Class<T>, method: string, params: unknown[]): void {
+  static async validateMethod<T>(cls: Class<T>, method: string, params: unknown[]): Promise<void> {
     const errors: ValidationError[] = [];
     for (const field of SchemaRegistry.getMethodSchema(cls, method)) {
       errors.push(...this.#validateFieldSchema(field, params[field.index!]));

package/support/transform-util.ts

@@ -128,6 +128,12 @@ export class SchemaTransformUtil {
       }
     }
 
+    const tags = ts.getJSDocTags(node);
+    const aliases = tags.filter(x => x.tagName.getText() === 'alias');
+    if (aliases.length) {
+      attrs.push(state.factory.createPropertyAssignment('aliases', state.fromLiteral(aliases.map(x => x.comment).filter(x => !!x))));
+    }
+
     const params: ts.Expression[] = [];
 
     const existing = state.findDecorator('@travetto/schema', node, 'Field', FIELD_MOD);