meta-mapper

Class based type(object) - mapper(shaper) via meta-data (reflect).

Install

npm install --save meta-mapper

Use scenario

• Map & sharp the data from request.

  Example: data { name: "shadow", val: "456", date: "2022-01-01", others: "..." } send from client, we'll need to map & sharp it to { name: string, val: number, date: Date }.

• Db access need to convert your define class object to db object.

  Example: a defined object { myName: "shadow" } wanna to map to db object { my_name: "shadow" } & save in Db, or vice versa.

Feature

• Support basic type Number | String | Boolean | Object.
• Support instance type Enum | Any | Date | Array.
• Support nest structure.
• Support super class.
• Support validation function on property.
• Use stragety try map as much as possible, the errors indicates the runtime mapping issues.
• Support generic type w/ Generic class/keyword since v0.2.0

  Use a name (the meta-name) to represent the type wannt, example paging.offset.date, for array structure try to use example paging.data.$ please.
  Check more details in test case in generic.test.ts please.

Limitation

• Support class definition instead of object type constraint definition.
• Now support enum int 2 ways, define an enum or via array type.

  A. enum XXX w/ @mp("", Enum, () => XXX)
  B. array w/ @mp("", Enum, () => [......])

• Do not support cycle structure.

  If the structure can't use JSON.stringify, then don't use meta-mapper please.

• Do not support custom map function yet.

Exception & Error

• Most of the Exception was thrown for the definiation error, which means you might correct it on the program phase instead of runtime phase.
• Error returned from $rtn.errors which represent the map runtime error. It's an array structure since we use try map as much as possible stragety.

  $rtn.errors[$idx].name is the meta name by default, example paging.offset. When there's array structure it could be like paging.detail.data[2].value etc.

Performance

Below performance test based on: 2.4 GHz 8-Core Intel Core i9 + 64G Memory.

• A simple class structure - map action would cost 10 ~ 30(us).
• A complex class structure - map action would cost about 100+(us) depends your data structure.

ref: check $/test/performance.test.ts for more details please.

Others

• Null/Undefined is allowed & supported by default as "values" instead of "types".
• Less dependency, only depends on "reflect-metadata"

API

• @mc(name: string, types: ClassConstructor[])

  when define a class, attach @mc on the class as a meta class data.
  Example: @mc("my_class", ClassBase) for class class MyClass extends ClassBase.

  • name: meta-name (alias) of your class. By default null | "" indicates the same as the class-name.
  • type: super types of the class.
• @mp(name: string, types: ClassConstructor[] | Function[])

  when define a property, attach @mp on the property as a meta property data.

  • name: meta-name (alias) of your property. By default null | "" indicates the same as thhe property-name.
  • types: internal nest types of the property.
    • Any: means should ignore the map action on this property, keep as it is.
    • Array: when it's an array, need to define as Array, and the internal element type of the Array.

      Example: @mp("custom_array", Array, MyCustomClass) for property custom_array: MyCustomClass[].

    • Enum: when it's an enum defined w/ enum XXX {...}, need to set as Enum and the real enum object type.

      Example: @mp("my_enum", Enum, () => MyEnum) for property my_enum: MyEnum.

• @mv_???

  Validation function. Use mv_custom to define customized validation function please.

• new(opt: MetaMapperOption)

  Define your mapper w/ custom mapper options.

  • opt: check the option below please.
• map(type: ClassConstructorGeneric<T>, obj: any, genericTypes?: Array<GenericNameType>): MapperRtn<T>

  map from any object input to defined class data type.
  Example: @mp("my_enum", Enum, () => MyEnum) for property my_enum: MyEnum.

  • type: the class type you wanna to map to.
  • obj: the object you wanna to map from.
  • genericTypes: If any generic type, indicate it here please. for Array<T> indicate the name as $ (i.e. xx.$.xxx) please.

Mapper Option

Option | Default Value | Description --- | --- | --- from | PropertyKey | map from the property-key field, otherwise set as MetaName if from the meta-name please. to | PropertyKey | map to the property-key field, otherwise set as MetaName if to the meta-name please. validate | true | global swith: run validation check or not validateUndefined | false | global swith: when validate, should we validate undefined value or not. validateNull | true | global swith: when validate, should we validate null value or not. keepArrayLengthMatch | true | when map failed on an array item, should we still set as "undefined" to keep the array length or not. keepNullVal | false | if the value is null then keep the key or property conversion. keepOriginVal | false | no matter whate the value was just keep it the same, note when this flag set the keepNullVal will be ignored.

Code Example

ref: $/test/readme.test.ts as well pleae.

//1. define your class w/ meta
//@mc short for Meta-Class
//@mp short for Meta-Property
//@mv short for Meta-Validation
@mc
class PagingData {
    @mp
    code: string;

    //meta-alias is "value" instead of "val"
    //Note here mark the real data-type of the "val" | "value" as "Number" (instead of the define type "String")
    //In later map action, no matter what data-type of the "val" | "value" is, the mapper would try to conver it to "Number" type.
    @mp("value", Number)
    val: string;
}

@mc
class Paging {
    @mp
    @mv_number(0, 100, false, "test.paging.offset", "Must between [0 ~ 100]")
    offset: number;

    @mp
    @mv_number(1, 20, false, "test.paging.limit", "Must between [0 ~ 20]")
    limit: number;

    @mp
    date: Date;

    //first parameter is "" or null indicates the meta-name is same as the property name, here it's "data" as well.
    @mp("", Array, PagingData)
    data: PagingData[];
}

//2. create a meta-mapper (w/ default option)
//Which a meta-mapper instance can be shared among the application, but if you need different mapper option you might init multiple instance.
//Note by default the opt is from PropertyKey -> PropertyKey
//Here we wanna to test the map from propertyKey to MetaName, so we set "opt.to" to "Meta"
const mapper = new MetaMapper({ to: MetaMapOn.Meta });

//3. indicate the class-type to map the object via calling .map() method.
let obj = {
    offset: 0,
    limit: "20",
    date: "2022-01-01 09:10:00+08:00",
    value: 100,
    data: [{ code: "s-001", val: "001" },
        { code: "s-002", val: "002" }
    ]
};
let p = mapper.map(Paging, obj);

//4. verify the ouput, here the return "p.rtn" would be like:
let pAssert = {
    offset: 0,
    limit: 20,  //convert from String to Number
    date: new Date("2022-01-01T01:10:00.000Z"),     //convert from String to Date
    data: [
        //nest data convert from "val" to "value", and type from String to Number
        { code: "s-001", value: 1 },
        { code: "s-002", value: 2 }
    ]
};
assert.strictEqual(JSON.stringify(p.rtn), JSON.stringify(pAssert));
assert.strictEqual(p.rtn.date instanceof Date, true);

Design

• MetaMapper-Flow:

• MetaMapper-DataType: