@travetto/schema 3.1.0-rc.1 → 3.1.0-rc.2

package/README.md

@@ -62,25 +62,25 @@ 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
-   *  [@Match](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L106) defines a regular expression that the field value should match
-   *  [@MinLength](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L114) enforces min length of a string
-   *  [@MaxLength](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L124) enforces max length of a string
-   *  [@Min](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L114) enforces min value for a date or a number
-   *  [@Max](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L124) enforces max value for a date or a number
-   *  [@Email](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L151) ensures string field matches basic email regex
-   *  [@Telephone](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L158) ensures string field matches basic telephone regex
-   *  [@Url](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L165) ensures string field matches basic url regex
-   *  [@Ignore](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L204) exclude from auto schema registration
-   *  [@Integer](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L179) ensures number passed in is only a whole number
-   *  [@Float](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L185) ensures number passed in allows fractional values
-   *  [@Currency](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L197) provides support for standard currency
-   *  [@Text](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L93) indicates that a field is expecting natural language input, not just discrete values
-   *  [@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
+   *  [@Field](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L31) defines a field that will be serialized.
+   *  [@Required](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L71) defines a that field should be required
+   *  [@Enum](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L78) defines the allowable values that a field can have
+   *  [@Match](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L99) defines a regular expression that the field value should match
+   *  [@MinLength](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L107) enforces min length of a string
+   *  [@MaxLength](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L117) enforces max length of a string
+   *  [@Min](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L107) enforces min value for a date or a number
+   *  [@Max](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L117) enforces max value for a date or a number
+   *  [@Email](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L144) ensures string field matches basic email regex
+   *  [@Telephone](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L151) ensures string field matches basic telephone regex
+   *  [@Url](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L158) ensures string field matches basic url regex
+   *  [@Ignore](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L197) exclude from auto schema registration
+   *  [@Integer](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L172) ensures number passed in is only a whole number
+   *  [@Float](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L178) ensures number passed in allows fractional values
+   *  [@Currency](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L190) provides support for standard currency
+   *  [@Text](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L86) indicates that a field is expecting natural language input, not just discrete values
+   *  [@LongText](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L91) same as text, but expects longer form content
+   *  [@Readonly](https://github.com/travetto/travetto/tree/main/module/schema/src/decorator/field.ts#L58) 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#L52) 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. 
 
 Just like the class, all fields can be defined with
@@ -88,6 +88,22 @@ Just like the class, all fields can be defined with
    *  `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.
 
+### Parameters
+Parameters are available in certain scenarios (e.g. [RESTful API](https://github.com/travetto/travetto/tree/main/module/rest#readme "Declarative api for RESTful APIs with support for the dependency injection module.") endpoints and [Command Line Interface](https://github.com/travetto/travetto/tree/main/module/cli#readme "CLI infrastructure for Travetto framework") main methods).  In these scenarios, all of the field decorators are valid, but need to be called slightly differently to pass the typechecker. The simple solution is to use the `Arg` field of the decorator to convince Typescript its the correct type.
+
+**Code: Sample Parameter Usage**
+```typescript
+import { Match, Min } from '../__index__';
+
+const NAME_REGEX = /[A-Z][a-z]+(\s+[A-Z][a-z]+)*/;
+
+export class ParamUsage {
+  main(@Match(NAME_REGEX).Param name: string, @Min(20).Param age?: number) {
+    console.log('Valid name and age!', { name, age });
+  }
+}
+```
+
 ## Binding/Validation
 At runtime, once a schema is registered, a programmer can utilize this structure to perform specific operations. Specifically binding and validation.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travetto/schema",
-  "version": "3.1.0-rc.1",
+  "version": "3.1.0-rc.2",
   "description": "Data type registry for runtime validation, reflection and binding.",
   "keywords": [
     "schema",
@@ -30,7 +30,7 @@
     "@travetto/registry": "^3.1.0-rc.0"
   },
   "peerDependencies": {
-    "@travetto/transformer": "^3.1.0-rc.0"
+    "@travetto/transformer": "^3.1.0-rc.1"
   },
   "peerDependenciesMeta": {
     "@travetto/transformer": {

package/src/decorator/field.ts

@@ -4,30 +4,23 @@ import { SchemaRegistry } from '../service/registry';
 import { CommonRegExp } from '../validate/regexp';
 import { ClassList, FieldConfig } from '../service/types';
 
-function prop(obj: Partial<FieldConfig>) {
-  return (t: ClassInstance, k: string, idx?: number | PropertyDescriptor): void => {
+type PropType<V> = (<T extends Partial<Record<K, V>>, K extends string>(t: T, k: K, idx?: number) => void) & {
+  Param: (t: unknown, k: string, idx: number) => void;
+};
+
+function prop<V>(obj: Partial<FieldConfig>): PropType<V> {
+  const fn = (t: ClassInstance, k: string, idx?: number): void => {
     if (idx !== undefined && typeof idx === 'number') {
       SchemaRegistry.registerPendingParamFacet(t.constructor, k, idx, obj);
     } else {
       SchemaRegistry.registerPendingFieldFacet(t.constructor, k, obj);
     }
   };
-}
-
-// eslint-disable-next-line max-len
-const stringArrProp: (obj: Partial<FieldConfig>) => <T extends Partial<Record<K, string | unknown[]>>, K extends string>(t: T, k: K, idx?: number | PropertyDescriptor) => void = prop;
-
-// eslint-disable-next-line max-len
-const stringArrStringProp: (obj: Partial<FieldConfig>) => <T extends Partial<Record<K, string | string[]>>, K extends string>(t: T, k: K, idx?: number | PropertyDescriptor) => void = prop;
+  fn.Param = fn;  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
 
-// eslint-disable-next-line max-len
-const numberProp: (obj: Partial<FieldConfig>) => <T extends Partial<Record<K, number>>, K extends string>(t: T, k: K, idx?: number | PropertyDescriptor) => void = prop;
-
-// eslint-disable-next-line max-len
-const stringNumberProp: (obj: Partial<FieldConfig>) => <T extends Partial<Record<K, string | number>>, K extends string>(t: T, k: K, idx?: number | PropertyDescriptor) => void = prop;
-
-// eslint-disable-next-line max-len
-const dateNumberProp: (obj: Partial<FieldConfig>) => <T extends Partial<Record<K, Date | number>>, K extends string>(t: T, k: K, idx?: number | PropertyDescriptor) => void = prop;
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+  return fn as PropType<V>;
+}
 
 /**
  * Registering a field
@@ -36,7 +29,7 @@ const dateNumberProp: (obj: Partial<FieldConfig>) => <T extends Partial<Record<K
  * @augments `@travetto/schema:Field`
  */
 export function Field(type: ClassList, config?: Partial<FieldConfig>) {
-  return (f: ClassInstance, k: string, idx?: number | PropertyDescriptor): void => {
+  return (f: ClassInstance, k: string, idx?: number): void => {
     if (idx !== undefined && typeof idx === 'number') {
       SchemaRegistry.registerPendingParamConfig(f.constructor, k, idx, type, config);
     } else {
@@ -50,52 +43,52 @@ export function Field(type: ClassList, config?: Partial<FieldConfig>) {
  * @param aliases List of all aliases for a field
  * @augments `@travetto/schema:Field`
  */
-export function Alias(...aliases: string[]): ReturnType<typeof prop> { return prop({ aliases }); }
+export function Alias(...aliases: string[]): PropType<unknown> { return prop({ aliases }); }
 /**
  * Mark a field as writeonly
  * @param active This determines if this field is readonly or not.
  * @augments `@travetto/schema:Field`
  */
-export function Writeonly(active = true): ReturnType<typeof prop> { return prop({ access: 'writeonly' }); }
+export function Writeonly(active = true): PropType<unknown> { return prop({ access: 'writeonly' }); }
 /**
  * Mark a field as readonly
  * @param active This determines if this field is readonly or not.
  * @augments `@travetto/schema:Field`
  */
-export function Readonly(active = true): ReturnType<typeof prop> { return prop({ access: 'readonly' }); }
+export function Readonly(active = true): PropType<unknown> { return prop({ access: 'readonly' }); }
 /**
  * Mark a field as sensitive
  * @param active This determines if this field is sensitive or not.
  * @augments `@travetto/schema:Field`
  */
-export function Secret(active = true): ReturnType<typeof prop> { return prop({ secret: active }); }
+export function Secret(active = true): PropType<unknown> { return prop({ secret: active }); }
 /**
  * Mark a field as required
  * @param active This determines if this field is required or not.
  * @param message The error message when a the constraint fails.
  * @augments `@travetto/schema:Field`
  */
-export function Required(active = true, message?: string): ReturnType<typeof prop> { return prop({ required: { active, message } }); }
+export function Required(active = true, message?: string): PropType<unknown> { return prop({ required: { active, message } }); }
 /**
  * Define a field as a set of enumerated values
  * @param values The list of values allowed for the enumeration
  * @param message The error message to show when the constraint fails
  * @augments `@travetto/schema:Field`
  */
-export function Enum(values: string[], message?: string): ReturnType<typeof stringNumberProp> {
+export function Enum(values: string[], message?: string): PropType<string | number> {
   message = message || `{path} is only allowed to be "${values.join('" or "')}"`;
-  return stringNumberProp({ enum: { values, message } });
+  return prop({ enum: { values, message } });
 }
 /**
  * Mark the field as indicating it's storing textual data
  * @augments `@travetto/schema:Field`
  */
-export function Text(): ReturnType<typeof stringArrStringProp> { return stringArrStringProp({ specifier: 'text' }); }
+export function Text(): PropType<string | string[]> { return prop({ specifier: 'text' }); }
 /**
  * Mark the field to indicate it's for long form text
  * @augments `@travetto/schema:Field`
  */
-export function LongText(): ReturnType<typeof stringArrStringProp> { return stringArrStringProp({ specifier: 'text-long' }); }
+export function LongText(): PropType<string | string[]> { return prop({ specifier: 'text-long' }); }
 
 /**
  * Require the field to match a specific RegExp
@@ -103,7 +96,7 @@ export function LongText(): ReturnType<typeof stringArrStringProp> { return stri
  * @param message The message to show when the constraint fails
  * @augments `@travetto/schema:Field`
  */
-export function Match(re: RegExp, message?: string): ReturnType<typeof stringArrStringProp> { return stringArrStringProp({ match: { re, message } }); }
+export function Match(re: RegExp, message?: string): PropType<string | string[]> { return prop({ match: { re, message } }); }
 
 /**
  * The minimum length for the string or array
@@ -111,8 +104,8 @@ export function Match(re: RegExp, message?: string): ReturnType<typeof stringArr
  * @param message The message to show when the constraint fails
  * @augments `@travetto/schema:Field`
  */
-export function MinLength(n: number, message?: string): ReturnType<typeof stringArrProp> {
-  return stringArrProp({ minlength: { n, message }, ...(n === 0 ? { required: { active: false } } : {}) });
+export function MinLength(n: number, message?: string): PropType<string | unknown[]> {
+  return prop({ minlength: { n, message }, ...(n === 0 ? { required: { active: false } } : {}) });
 }
 
 /**
@@ -121,7 +114,7 @@ export function MinLength(n: number, message?: string): ReturnType<typeof string
  * @param message The message to show when the constraint fails
  * @augments `@travetto/schema:Field`
  */
-export function MaxLength(n: number, message?: string): ReturnType<typeof stringArrProp> { return stringArrProp({ maxlength: { n, message } }); }
+export function MaxLength(n: number, message?: string): PropType<string | unknown[]> { return prop({ maxlength: { n, message } }); }
 
 /**
  * The minimum value
@@ -129,8 +122,8 @@ export function MaxLength(n: number, message?: string): ReturnType<typeof string
  * @param message The message to show when the constraint fails
  * @augments `@travetto/schema:Field`
  */
-export function Min<T extends number | Date>(n: T, message?: string): ReturnType<typeof dateNumberProp> {
-  return dateNumberProp({ min: { n, message } });
+export function Min<T extends number | Date>(n: T, message?: string): PropType<Date | number> {
+  return prop({ min: { n, message } });
 }
 
 /**
@@ -139,8 +132,8 @@ export function Min<T extends number | Date>(n: T, message?: string): ReturnType
  * @param message The message to show when the constraint fails
  * @augments `@travetto/schema:Field`
  */
-export function Max<T extends number | Date>(n: T, message?: string): ReturnType<typeof dateNumberProp> {
-  return dateNumberProp({ max: { n, message } });
+export function Max<T extends number | Date>(n: T, message?: string): PropType<Date | number> {
+  return prop({ max: { n, message } });
 }
 
 /**
@@ -148,21 +141,21 @@ export function Max<T extends number | Date>(n: T, message?: string): ReturnType
  * @param message The message to show when the constraint fails
  * @augments `@travetto/schema:Field`
  */
-export function Email(message?: string): ReturnType<typeof Match> { return Match(CommonRegExp.email, message); }
+export function Email(message?: string): PropType<string | string[]> { return Match(CommonRegExp.email, message); }
 
 /**
  * Mark a field as an telephone number
  * @param message The message to show when the constraint fails
  * @augments `@travetto/schema:Field`
  */
-export function Telephone(message?: string): ReturnType<typeof Match> { return Match(CommonRegExp.telephone, message); }
+export function Telephone(message?: string): PropType<string | string[]> { return Match(CommonRegExp.telephone, message); }
 
 /**
  * Mark a field as a url
  * @param message The message to show when the constraint fails
  * @augments `@travetto/schema:Field`
  */
-export function Url(message?: string): ReturnType<typeof Match> { return Match(CommonRegExp.url, message); }
+export function Url(message?: string): PropType<string | string[]> { return Match(CommonRegExp.url, message); }
 
 /**
  * Determine the numeric precision of the value
@@ -170,31 +163,31 @@ export function Url(message?: string): ReturnType<typeof Match> { return Match(C
  * @param decimals The number of decimal digits to support
  * @augments `@travetto/schema:Field`
  */
-export function Precision(digits: number, decimals?: number): ReturnType<typeof numberProp> { return numberProp({ precision: [digits, decimals] }); }
+export function Precision(digits: number, decimals?: number): PropType<number> { return prop({ precision: [digits, decimals] }); }
 
 /**
  * Mark a number as an integer
  * @augments `@travetto/schema:Field`
  */
-export function Integer(): ReturnType<typeof numberProp> { return Precision(0); }
+export function Integer(): PropType<number> { return Precision(0); }
 
 /**
  * Mark a number as a float
  * @augments `@travetto/schema:Field`
  */
-export function Float(): ReturnType<typeof numberProp> { return Precision(10, 7); }
+export function Float(): PropType<number> { return Precision(10, 7); }
 
 /**
  * Mark a number as a long value
  * @augments `@travetto/schema:Field`
  */
-export function Long(): ReturnType<typeof numberProp> { return Precision(19, 0); }
+export function Long(): PropType<number> { return Precision(19, 0); }
 
 /**
  * Mark a number as a currency
  * @augments `@travetto/schema:Field`
  */
-export function Currency(): ReturnType<typeof numberProp> { return Precision(13, 2); }
+export function Currency(): PropType<number> { return Precision(13, 2); }
 
 /**
  * Mark a field as ignored