Tunnel-Cast/tunnel-cast

Overview

The way (order) that cast-process execute the field-procedures is a key feature in this module. each field-procedures have a type that indicate in what order it will be execute in relation to others.

Field-procedures types :

• Conditional Handling - implemented using FieldConditionalHandlingProcedure class.
• Default Assignment - implemented using FieldDefaultAssignmentProcedure class.
• Parser - implemented using FieldParserProcedure class.
• Constraint - implemented using FieldConstraintProcedure class.
• Transformer - implemented using FieldTransformerProcedure class.

Multiple field-procedures of the same type are, by default, executed in the order that they are decorated the processed fields.

Quick flow review :

1. [Conditional Handling] - run each conditional-handling, if all resolved ⟶ (2), else ⟶ (done).
2. [Default Assignment] - run first default-assignment, if the field found to not be existed the default value is assigned ⟶ (done), else ⟶ (3).
3. [Parser] - run each parser ⟶ (4).
4. [Constraint] - run each constraint, if all passed ⟶ (5), else ⟶ (done with error).
5. [Transformer] - run each transformer ⟶ (done).

Example :

class ExampleModel {
  package: string;

  @SkipIf((v, k, ctx) => v === "" )               // A - Conditional Handling
  @SkipIf((v, k, ctx) => ctx.package === "HBO" )  // B - Conditional Handling
  @Default("00001")                               // C - Default Assignment
  @IsString()                                     // D - Constraint
  @Length(5)                                      // E - Constraint
  @IsNumberString()                               // F - Constraint
  serial: string;
}

const { messages, resolvedValue } = cast(
    ExampleModel, 
    { serial: "30010", package: "DTV" }
);

console.log(messages)       // undefined
console.log(resolvedValue)  // { serial: "30010", package: "DTV" }

Lets review the example by step :

1. A & B all resolved.
2. C not apply because field value is exists.
3. non provided.
4. D, E, & F all resolved.
5. non provided.

Api Documentation

Cast

cast

function cast<T>(model: (new (...args: any[]) => T), target: any, options?: CastOptions): CastResult<T>

• Description : Apply the rules embedded in the model class on the target, and in case of success return the resolvedValue, and in case of failure return the messages list.

castOrReject

function castOrReject<T=any>(model: new (...args: any[]) => T, target: any, options?: CastOptions): T

• Description : Dose the same as cast (invoke it internally), but in case of failure throw the messages list, and in case of success return the resolvedValue directly (not wrapped in an object).

Decorators / constraint / common

IsEnum

function IsEnum(list: Array<string>, options?: FieldConstraintProcedureOptions);
function IsEnum(enumObj: Object, options?: FieldConstraintProcedureOptions);

• Description :

• Arguments :
  • list -
  • enumObj -
  • options - constraint options object.

IsEquals

function IsEquals(value: any, strict: boolean , options?: FieldConstraintProcedureOptions);
function IsEquals(value: any, options?: FieldConstraintProcedureOptions);

• Description : validate (assert) the value of the field against the argument value.

• Arguments :
  • value - the value to assert to.
  • strict - if true, the assertion is done using assert.deepStrictEqual, else the assertion is done using ==.
  • options - constraint options object.

Length

function Length(len: number, options?: FieldConstraintProcedureOptions);
function Length(min: number, max: number, options?: FieldConstraintProcedureOptions);

• Description : validate that the expected value has the property length and it's value - exact or the range, commonly used to validate length of string or array, but technically is could validate a property name length of any object.

• Arguments :
  • len - the exact length of the expect string or array value.
  • min - the min (gte) length of the expect string or array value.
  • max - the max (lte) length of the expect string or array value.
  • options - constraint options object.

Required

function Required(options?: FieldConstraintProcedureOptions);

• Description : validate that the expected value isn't equal to the values null, undefined of ''.

• Arguments :
  • options - constraint options object.

Decorators / constraint / sequence

EndsWith

function EndsWith(value: (Array<any> | string | any), options?: FieldConstraintProcedureOptions);

• Description : validate that the expected field value end with the provided value argument (array of values of single), if the field value is an array the constrain will pass if it's end with the value argument an item(s), if the field value is a string the constrain will pass if it's end with the value argument as a substring.

• Arguments :
  • value - the value(s) that the field value to be end with.
  • options - constraint options object.

StartsWith

function StartsWith(value: (Array<any> | string | any), options?: FieldConstraintProcedureOptions);

• Description : validate that the expected field value start with the provided value argument (array of values of single), if the field value is an array the constrain will pass if it's start with the value argument an item(s), if the field value is a string the constrain will pass if it's start with the value argument as a substring.

• Arguments :
  • value - the value(s) that the field value to be start with.
  • options - constraint options object.

Includes

function Includes(value: any, options?: FieldConstraintProcedureOptions);

• Description : validate that the expected field value includes the provided value argument, if the field value is an array the constrain will pass if the value argument includes in it as an item, if the field value is a string the constrain will pass if the value argument includes in it as a substring.

• Arguments :
  • value - the value to be included in the field value.
  • options - constraint options object.

Decorators / constraint / string

IsDateString

function IsDateString(options? : FieldConstraintProcedureOptions);

• Description :

• Arguments :
  • options - constraint options object.

IsEmail

function IsEmail(domains: Array<string> ,options?: FieldConstraintProcedureOptions);
function IsEmail(options?: FieldConstraintProcedureOptions);

• Description :

• Arguments :
  • domains - expectable email domains list.
  • options - constraint options object.

IsISODate

function IsISODate(options? : FieldConstraintProcedureOptions);

• Description :

• Arguments :
  • options - constraint options object.

IsNumberString

function IsNumberString(options? : FieldConstraintProcedureOptions);

• Description :

• Arguments :
  • options - constraint options object.

IsUUID

function IsUUID(options? : FieldConstraintProcedureOptions);

• Description :

• Arguments :
  • options - constraint options object.

Matches

function Matches(pattern: RegExp, options?: FieldConstraintProcedureOptions);

• Description :

• Arguments :
  • pattern - pattern to metch the againt the field value.
  • options - constraint options object.

Decorators / constraint / type

IsArray

function IsArray(options? : FieldConstraintProcedureOptions);

• Description : validate that the expected field value is an array.

• Arguments :
  • options - constraint options object.

IsBoolean

function IsBoolean(options? : FieldConstraintProcedureOptions);

• Description : validate that the expected field value is of boolean type.

• Arguments :
  • options - constraint options object.

IsInstanceOf

function IsInstanceOf(instanceofType: any, options?: FieldConstraintProcedureOptions);

• Description : validate that the expected field value is an instance-of the type provided in the argument instanceofType.

• Arguments :
  • options - constraint options object.

IsNumber

function IsNumber(options? : FieldConstraintProcedureOptions);

• Description : validate that the expected field value is of number type.

• Arguments :
  • options - constraint options object.

IsObject

function IsObject(options? : FieldConstraintProcedureOptions);

• Description : validate that the expected field value is of object type.

• Arguments :
  • options - constraint options object.

IsString

function IsString(options? : FieldConstraintProcedureOptions);

• Description : validate that the expected field value is of string type.

• Arguments :
  • options - constraint options object.

IsTypeOf

function IsTypeOf(typeofString: string, options?: FieldConstraintProcedureOptions);

• Description : validate that the expected field value is a type-of the type-string provided in the argument typeofString.

• Arguments :
  • options - constraint options object.

Decorators / conditional

Nullable

function Nullable(options? : FieldConditionalHandlingProcedureOptions);

• Description : A field decorated with this decorator

• Arguments :
  • options - constraint options object.

SkipIf

function SkipIf(cond: ((value, name, context) => boolean), options?: FieldConditionalHandlingProcedureOptions);

• Description :

• Arguments :
  • cond - a condition function, if it return true the field will be processed, otherwise it will be skipped.
  • options - constraint options object.

Internal api

decoratorAdapter

function decoratorAdapter(fieldProcedure: FieldProcedure): PropertyDecorator;

Field-Procedure

All the decorators are internally define a cast procedure over the field they decorating, the procedure can be looked as the decorator type. The procedure define the nature of the decorator it's purpose and part it takes in the cast process. Technically, a procedure class is a simple wrapper for the metadata needed be the cast process to apply is on the handled value.

Field-procedure classes :

• FieldConstraintProcedure
• FieldConditionalHandlingProcedure
• FieldDefaultAssignmentProcedure
• FieldParserProcedure
• FieldTransformerProcedure