@tunnel-cast/tunnel-cast

# 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 :* ```ts 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` ```ts 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` ```ts 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` ```ts function IsEnum(list: Array<string>, options?: FieldConstraintProcedureOptions); function IsEnum(enumObj: Object, options?: FieldConstraintProcedureOptions); ``` + Description : + Arguments : + `list` - + `enumObj` - + `options` - constraint options object. ### `IsEquals` ```ts 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` ```ts 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` ```ts 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` ```ts 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` ```ts 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` ```ts 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` ```ts function IsDateString(options? : FieldConstraintProcedureOptions); ``` + Description : + Arguments : + `options` - constraint options object. ### `IsEmail` ```ts function IsEmail(domains: Array<string> ,options?: FieldConstraintProcedureOptions); function IsEmail(options?: FieldConstraintProcedureOptions); ``` + Description : + Arguments : + `domains` - expectable email domains list. + `options` - constraint options object. ### `IsISODate` ```ts function IsISODate(options? : FieldConstraintProcedureOptions); ``` + Description : + Arguments : + `options` - constraint options object. ### `IsNumberString` ```ts function IsNumberString(options? : FieldConstraintProcedureOptions); ``` + Description : + Arguments : + `options` - constraint options object. ### `IsUUID` ```ts function IsUUID(options? : FieldConstraintProcedureOptions); ``` + Description : + Arguments : + `options` - constraint options object. ### `Matches` ```ts 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` ```ts function IsArray(options? : FieldConstraintProcedureOptions); ``` + Description : validate that the expected field value is an array. + Arguments : + `options` - constraint options object. ### `IsBoolean` ```ts function IsBoolean(options? : FieldConstraintProcedureOptions); ``` + Description : validate that the expected field value is of boolean type. + Arguments : + `options` - constraint options object. ### `IsInstanceOf` ```ts 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` ```ts function IsNumber(options? : FieldConstraintProcedureOptions); ``` + Description : validate that the expected field value is of number type. + Arguments : + `options` - constraint options object. ### `IsObject` ```ts function IsObject(options? : FieldConstraintProcedureOptions); ``` + Description : validate that the expected field value is of object type. + Arguments : + `options` - constraint options object. ### `IsString` ```ts function IsString(options? : FieldConstraintProcedureOptions); ``` + Description : validate that the expected field value is of string type. + Arguments : + `options` - constraint options object. ### `IsTypeOf` ```ts 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` ```ts function Nullable(options? : FieldConditionalHandlingProcedureOptions); ``` + Description : A field decorated with this decorator + Arguments : + `options` - constraint options object. ### `SkipIf` ```ts 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` ```ts 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`