@edirect/template

TemplateModule is a library that provides methods to transform a payload based on a given template. The transformation includes mapping fields, applying transformers, setting default values and so on.

Installation

$ npm i --save @edirect/template

Import

import { TemplateModule } from "./TemplateModule";

Methods

`Constructor`

The TemplateModule class does not have a constructor.

`setContext(context): void`

Sets the context object to be used during the transformation.

`setTemplate(template): void`

Sets the template object that describes the transformation to be performed.

`setTransformers(transformers: ITransformer): void`

Sets the transformers to be used during the transformation.

`setOptions(transformers: ITemplateOptions): void`

Sets the options to be used during and after the transformation.

`verifyTransformer(transformer: ITransformer, methodName: string): boolean`

Verifies if a given transformer method exists.

`runTransformer(transformer: string, value?: unknown): unknown | null`

Runs a transformer on a given value.

transformer - The name of the transformer to be used.
value - The value to be transformed.

`checkValue(value: any): boolean`

Checks if a given value is not null, undefined, or an empty string.

`setValueByCondition(object, key: string, value: unknown)`

Sets a value in an object after verify using the checkValue() method.

object - The object to be modified.
key - The key of the value to be set.
value - The value to be set.

`transformPayload<T, U>(obj: T, template = this.template): U`

Transforms a payload object on a given template.

Simple example

import { TemplateModule } from "@edirect/template";

const template = {
  edirect_firstname: "subscriber.firstName",
  edirect_lastname: "subscriber.lastName",
};

const dataSource = {
  subscriber: {
    firstName: "template",
    lastName: "service",
  },
};

const templateModule = new TemplateModule();
templateModule.setTemplate(template);

const result = templateModule.transformPayload(dataSource);

console.log(result);

// {
//   edirect_firstname: "template",
//   edirect_lastname: "service",
// }

Example with transformers

First of all, what's a transformer?

A transformer is a way to handle values with more detail and freedom.

For example:

Mapping
Validation
Formatting
Business rules
and so on ...

Each transformer receives two parameters:

value: specific value that you want to handle
context: all context (payload) that you can use to build any logical

To map a value that you'd like to use some transformer feature, you can use these options:

fields: it's an array with a data source path, and the first value that is found will be used.
transformer: it's a JS function, where you receive value and context as parameters and have all freedom to handle and return a value
defaultValue it's an option if the engine doesn't find any value in the fields data source array or the transformer doesn't return a value.

File name: baseTransformers.ts

import { ITransformer, ITransformerParams } from "@edirect/template";

const upperCase = ({ value }: ITransformerParams): string | null => {
  return value ? String(value).toUpperCase() : null;
};

const fullName = ({ context }: ITransformerParams): string | null => {
  try {
    const { firstName, lastName } = context.subscriber;
    return `${firstName} ${lastName}`;
  } catch (error) {
    return null;
  }
};

const transformers: ITransformer = {
  upperCase,
  fullName,
};

export default transformers;

File name: index.ts

import { TemplateModule } from "@edirect/template";
import baseTransformers from "./baseTransformers";

const template = {
  edirect_firstname: {
    fields: ["firstName", "subscriber.firstName"],
    transformer: "upperCase",
    defaultValue: "First Name - Default",
  },
  edirect_lastname: {
    fields: ["lastName", "subscriber.lastName"],
  },
  edirect_fullname: {
    transformer: "fullName",
  },
  edirect_phone: {
    fields: ["phoneNumber", "subscriber.phoneNumber"],
    defaultValue: "999999999",
  },
  timeZone: {
    defaultValue: "Time zone in Porto (GMT+1)",
  },
};

const dataSource = {
  subscriber: {
    firstName: "template",
    lastName: "service",
  },
};

const templateModule = new TemplateModule();

templateModule.setTemplate(template);
templateModule.setContext(dataSource);
templateModule.setTransformers(baseTransformers);

const result = templateModule.transformPayload(dataSource);
console.log(result);

// {
//   edirect_firstname: "TEMPLATE",
//   edirect_lastname: "service",
//   edirect_fullname: "template service",
//   edirect_phone: "999999999",
//   timeZone: "Time zone in Porto (GMT+1)",
// }

Example with nested object + transformers

Note: the transformer notation uses three keys to identify an object as being a transformer: fields, transformer, and defaultValue, if there are at least 1 of these keys, the engine will consider the object as being a transformer, on the other hand, if there isn't, the engine will consider as a nested object to mapper all information.

File name: baseTransformers.ts

import { ITransformer, ITransformerParams } from "@edirect/template";

const upperCase = ({ value }: ITransformerParams): string | null => {
  return value ? String(value).toUpperCase() : null;
};

const transformers: ITransformer = {
  upperCase,
};

export default transformers;

File name: index.ts

import { TemplateModule } from "@edirect/template";
import baseTransformers from "./baseTransformers";

const template = {
  order: {
    date: "order.date",
    value: "order.value",
    subscriber: {
      name: "sub.name",
      phone: "sub.phone",
      email: {
        fields: ["email", "sub.email"],
      },
      address: {
        street: "sub.add.stt",
        number: "sub.add.num",
        city: {
          fields: ["sub.add.city"],
          transformer: "upperCase",
        },
        state: {
          fields: ["sub.add.stt"],
          transformer: "upperCase",
        },
        zip: {
          fields: ["sub.add.zip"],
          defaultValue: "0000-000",
        },
      },
    },
  },
};

const dataSource = {
  order: {
    value: 1000.0,
    date: "2000-01-01",
  },
  sub: {
    name: "name-test",
    phone: "999999999",
    email: "template.service@bolltech.io",
    add: {
      st: "st-test",
      num: 100,
      city: "city-test",
      stt: "state-test",
      zip: "zip-test",
    },
  },
};

const templateModule = new TemplateModule();

templateModule.setTemplate(template);
templateModule.setContext(dataSource);
templateModule.setTransformers(baseTransformers);

const result = templateModule.transformPayload(dataSource);
console.log(result);

// {
//   order: {
//     date: "2000-01-01",
//     value: 1000,
//     subscriber: {
//       name: "name-test",
//       phone: "999999999",
//       email: "template.service@bolltech.io",
//       address: {
//         street: "state-test",
//         number: 100,
//         city: "CITY-TEST",
//         state: "STATE-TEST",
//         zip: "zip-test",
//       },
//     },
//   },
// }

Example with arrays + transformers

Note: When it comes to arrays mapper, we need to have in mind that is required use this two keys: arraySource and arrayTemplate.

arraySource: source path where the engine will seek the information to mapper
arrayTemplate: template that will be used for each object within the array

File name: baseTransformers.ts

import { ITransformer, ITransformerParams } from "@edirect/template";

const upperCase = ({ value }: ITransformerParams): string | null => {
  return value ? String(value).toUpperCase() : null;
};

const transformers: ITransformer = {
  upperCase,
};

export default transformers;

File name: index.ts

import { TemplateModule } from "@edirect/template";
import baseTransformers from "./baseTransformers";

const template = {
  quote: {
    orders: {
      arraySource: "order",
      arrayTemplate: {
        value: "value",
        date: "date",
        products: {
          arraySource: "products",
          arrayTemplate: {
            id: "id",
            value: "value",
            description: {
              fields: ["description"],
              transformer: "upperCase",
              defaultValue: "Default description",
            },
            categories: "categories",
          },
        },
      },
    },
  },
};

const dataSource = {
  order: [
    {
      value: 1000.0,
      date: "2000-01-01",
      products: [
        {
          id: "id-test-1",
          value: 1000,
          description: "description-test 1",
          categories: ["category-1"],
        },
        {
          id: "id-test-2",
          value: 2000,
          description: "description-test 2",
          categories: ["category-1", "category-2"],
        },
        {
          id: "id-test-3",
          value: 3000,
          categories: ["category-1", "category-2", "category-3"],
        },
      ],
    },
  ],
};

const templateModule = new TemplateModule();

templateModule.setTemplate(template);
templateModule.setContext(dataSource);
templateModule.setTransformers(baseTransformers);

const result = templateModule.transformPayload(dataSource);
console.log(result);

//{
//  quote: {
//     orders: [
//       {
//         value: 1000,
//         date: "2000-01-01",
//         products: [
//           {
//             id: "id-test-1",
//             value: 1000,
//             description: "DESCRIPTION-TEST 1",
//             categories: ["category-1"],
//           },
//           {
//             id: "id-test-2",
//             value: 2000,
//             description: "DESCRIPTION-TEST 2",
//             categories: ["category-1", "category-2"],
//           },
//           {
//             id: "id-test-3",
//             value: 3000,
//             description: "Default description",
//             categories: ["category-1", "category-2", "category-3"],
//           },
//         ],
//       },
//     ],
//   },
// }

Example with arrays + ignoreIndexs

Note: When it comes to arrays mapper, we need to have in mind that is required use this two keys: arraySource and arrayTemplate.

arraySource: source path where the engine will seek the information to mapper
arrayTemplate: template that will be used for each object within the array
ignoreIndexs: array with the index position that must be ignore

File name: baseTransformers.ts

import { ITransformer, ITransformerParams } from "@edirect/template";

const upperCase = ({ value }: ITransformerParams): string | null => {
  return value ? String(value).toUpperCase() : null;
};

const transformers: ITransformer = {
  upperCase,
};

export default transformers;

File name: index.ts

import { TemplateModule } from "@edirect/template";
import baseTransformers from "./baseTransformers";

const template = {
  quote: {
    orders: {
      arraySource: "order",
      arrayTemplate: {
        value: "value",
        date: "date",
        products: {
          arraySource: "products",
          arrayTemplate: {
            id: "id",
            value: "value",
            description: {
              fields: ["description"],
              transformer: "upperCase",
              defaultValue: "Default description",
            },
            categories: "categories",
          },
          ignoreIndexs: [0]
        },
      },
    },
  },
};

const dataSource = {
  order: [
    {
      value: 1000.0,
      date: "2000-01-01",
      products: [
        {
          id: "id-test-1",
          value: 1000,
          description: "description-test 1",
          categories: ["category-1"],
        },
        {
          id: "id-test-2",
          value: 2000,
          description: "description-test 2",
          categories: ["category-1", "category-2"],
        },
        {
          id: "id-test-3",
          value: 3000,
          categories: ["category-1", "category-2", "category-3"],
        },
      ],
    },
  ],
};

const templateModule = new TemplateModule();

templateModule.setTemplate(template);
templateModule.setContext(dataSource);
templateModule.setTransformers(baseTransformers);

const result = templateModule.transformPayload(dataSource);
console.log(result);

//{
//  quote: {
//     orders: [
//       {
//         value: 1000,
//         date: "2000-01-01",
//         products: [
//           {
//             id: "id-test-2",
//             value: 2000,
//             description: "DESCRIPTION-TEST 2",
//             categories: ["category-1", "category-2"],
//           },
//           {
//             id: "id-test-3",
//             value: 3000,
//             description: "Default description",
//             categories: ["category-1", "category-2", "category-3"],
//           },
//         ],
//       },
//     ],
//   },
// }

Template example with transformer + transformerParams

File name: baseTransformers.ts

import { ITransformer, ITransformerParams } from "@edirect/template";

const concat = (
  { value }: ITransformerParams,
  ...itensToConcat: string[]
): string => {
  const arrayToConcat = [value, ...itensToConcat];
  return arrayToConcat.join("");
};

const concatWithSeparator = (
  { value }: ITransformerParams,
  separator: string,
  ...itensToConcat: string[]
): string => {
  const arrayToConcat = [value, ...itensToConcat];
  return arrayToConcat.join(separator);
};

const transformers: ITransformer = {
  concat,
  concatWithSeparator,
};

export default transformers;

File name: index.ts

import { TemplateModule } from "@edirect/template";
import baseTransformers from "./baseTransformers";

const template = {
  status: "status",
  concatenated_result: {
    fields: ["lead_id"],
    transformer: "concat",
    transformerParams: [
      "-",
      "${person_number}",
      "/",
      "${person_number2}",
      "_",
      "${person_number3}",
    ],
  },
  concatenated_result2: {
    fields: ["lead_id"],
    transformer: "concatWithSeparator",
    transformerParams: [
      "-",
      "${person_number}",
      "${person_number2}",
      "${person_number3}",
    ],
  },
};

const dataSource = {
  status: true,
  lead_id: "FR-14af3f",
  person_number: 123,
  person_number2: 456,
  person_number3: 789,
};

const templateModule = new TemplateModule();

templateModule.setTemplate(template);
templateModule.setContext(dataSource);
templateModule.setTransformers(baseTransformers);

const result = templateModule.transformPayload(dataSource);
console.log(result);

// {
//   status: true,
//   concatenated_result: "FR-14af3f-123/456_789",
//   concatenated_result2: "FR-14af3f-123-456-789"
// }

Template example with transformer + transformerParams + complexParams

File name: baseTransformers.ts

import { ITransformer, ITransformerParams } from "@edirect/template";

const translator = ({ value }: ITransformerParams, translateDict: Record<string, string>): string => {
    const translated = translateDict.?[value];
    if (!translated) return null;
    return translated;
};

const transformers: ITransformer = {
    translator,
};

export default transformers;

File name: index.ts

import { TemplateModule } from "@edirect/template";
import baseTransformers from "./baseTransformers";

const template = {
  status: {
    fields: ["status"],
    transformer: "translator",
    transformerParams: [
      {
        ERROR: "ERROR",
        RECHAZADA: "REJECTED",
      },
    ],
  },
};

const dataSource = {
  status: "RECHAZADA",
};

const templateModule = new TemplateModule();

templateModule.setTemplate(template);
templateModule.setContext(dataSource);
templateModule.setTransformers(baseTransformers);

const result = templateModule.transformPayload(dataSource);
console.log(result);

// {
//   status: "REJECTED",
// }

Example with Sequential Transformers

The library now supports applying multiple transformers sequentially to a single field. This is particularly useful for more complex transformations that require multiple steps.

Each transformer in the sequence will receive the output of the previous transformer as its input value. The allowNull property of the last transformer in the sequence determines whether null values are allowed in the final output.

File name: baseTransformers.ts

import { ITransformer, ITransformerParams } from "@edirect/template";

const findKeyInArrayGetField = (
    { value, context }: ITransformerParams,
    key: string,
    valueToFind: string,
    field: string,
    transformer: any,
    ...params: any
): any | null => {
    const listToFind = findKeyInArray({ value }, key, valueToFind);
    if (typeof transformer !== "undefined") {
        value = _.get(listToFind, field, null);
        let transformerParams = params;
        if (field === "#") {
            transformerParams = [];
            for (const fieldItem of params) {
                let item = fieldItem;
                if (fieldItem.includes("#")) {
                    item = _.get(listToFind, fieldItem.replace(/\#\{(.*)\}/, "$1"), null);
                }
                transformerParams.push(item);
            }
        }
        if (typeof baseTransformers[transformer] !== "undefined") {
            return baseTransformers[transformer]({ value, context }, ...transformerParams);
        }
    }
    return _.get(listToFind, field, null);
};

const calculateAgeByBirthdate = ({ value }: ITransformerParams, ...formatDate: string[]): string | null => {
    if (!value) return null;

    if (!formatDate.length) formatDate.push("dd/MM/yyyy");

    for (const format of formatDate) {
        const date = parse(value, format, new Date());
        if (isValid(date)) {
            return differenceInYears(new Date(), date).toString();
        }
    }
    return null;
};

const transformers: ITransformer = {
  findKeyInArrayGetField,
  calculateAgeByBirthdate
};

export default transformers;

File name: index.ts

import { TemplateModule } from "@edirect/template";
import baseTransformers from "./baseTransformers";

const template = {
  age: {
    transformers: [
      {
        fields: [
          "data.externalReferences"
        ],
        transformer: "findKeyInArrayGetField",
        transformerParams: [
          "type",
          "birthDate",
          "value"
        ]
      },
      {
        transformer: "calculateAgeByBirthdate",
        transformerParams: [
          "yyyy-MM-dd'T'HH:mm:ss.SSSXXX"
        ]
      }
    ]
  }
};

const dataSource = {
  data: {
    externalReferences: [
      {
        type: "randomKey",
        value: "randomValue"
      },
      {
        type: "birthDate",
        value: "1995-12-27T15:22:32.511+00:00"
      }
    ]
  }
};

const templateModule = new TemplateModule();

templateModule.setTemplate(template);
templateModule.setContext(dataSource);
templateModule.setTransformers(baseTransformers);

const result = templateModule.transformPayload(dataSource);
console.log(result);

// {
//   age: "29"
// }

In this example:

The first transformer (findKeyInArrayGetField) extracts the birthdate value from the array of external references
The second transformer (calculateAgeByBirthdate) calculates the age from the birthdate

The transformers are applied sequentially, with each one receiving the result of the previous transformation as its input value.

Example inferring types to transformPayload

import { TemplateModule } from "@edirect/template";

interface DataSource {
  subscriber: {
    firstName: string;
    lastName: string;
  };
}

interface TransformedData {
  edirect_firstname: string;
  edirect_lastname: string;
}

function transformData(dataSource: DataSource): TransformedData {
  const template = {
    edirect_firstname: "subscriber.firstName",
    edirect_lastname: "subscriber.lastName",
  };

  const templateModule = new TemplateModule();
  templateModule.setTemplate(template);

  return templateModule.transformPayload<TransformedData>(dataSource);
}

const dataSource = {
  subscriber: {
    firstName: "template",
    lastName: "service",
  },
};

console.log(transformData(dataSource));

// {
//   edirect_firstname: "template",
//   edirect_lastname: "service",
// }

Example with Options

Options:

omitEmptyFields?: boolean;

import { TemplateModule } from "@edirect/template";

const template = {
  edirect_firstname: "subscriber.firstName",
  edirect_lastname: "subscriber.lastName",
  edirect_age: "subscriber.age",
};

const dataSource = {
  subscriber: {
    firstName: "template",
    lastName: "service",
    age: "",
  },
};

const options = { omitEmptyFields: true };

const templateModule = new TemplateModule();
templateModule.setTemplate(template);
templateModule.setOptions(options);

const result = templateModule.transformPayload(dataSource);

console.log(result);

// {
//   edirect_firstname: "template",
//   edirect_lastname: "service",
// }

Example using simple arrays

import { TemplateModule } from "@edirect/template";

const template = {
  emails: {
    arraySource: "subscriber.emails",
    simpleArray: true,
    arrayTemplate: {
      type: {
        defaultValue: "personal",
      },
      value: "value",
    },
  },
};

const dataSource = {
  subscriber: {
    emails: ["johndoe@example.com", "janedoe@example.com"],
  },
};

const templateModule = new TemplateModule();
templateModule.setTemplate(template);

const result = templateModule.transformPayload(dataSource);

console.log(result);

/*
  {
    "emails": [
      {
        "type": "personal",
        "value": "johndoe@example.com"
      },
      {
        "type": "personal",
        "value": "janedoe@example.com"
      }
    ]
  }
*/