README.md

Paramplate

Paramplate is a node CLI tool for code generation. It takes in values from parameter files, parses the template files and produces output files with rendered strings. The benefit of the tool is that you can use centralized parameter files and template files for scaffolding which reduces repetitive work and avoids manual errors.

How it works

Here is a basic setup.

projct
|-- param.json
|-- input
    |-- template.yaml.pp
|-- output

project/param.json contains all the parameters.

{
  "app": {
    "name": "app1"
  },
  "envs": [
    "dev",
    "staging",
    "prod"
  ]
}

project/input/template.yaml.pp is the template file.

name: {{ app.name }}
envs:
  - {{ envs.[0] }}
  - {{ envs.[1] }}
  - {{ envs.[2] }}

Run the paramplate command.

npx paramplate --params project/param.json --src project/input --dest project/output

It generates a new file with values rendered: project/output/template.yaml

name: app1
envs:
  - dev
  - staging
  - prod

The CLI does a few things here:

1. Read the param.json, flatten the objects and store them in a map.
2. Find the template file: template.yaml.pp which has the template file extension in the source directory.
3. Parse the template file, remove the template file extension and write to destintion directory.

Install & Run

Prerequisites

• node installed
• create your parameter json files, template files and define input/output directories

Use npx

npx paramplate --params param.json --src /input --dest /output

Use npm

npm install paramplate -g
paramplate --params param.json --src /input --dest /output

Cli arguments

--params

Required. Accept a list of json files which contain the parameters used for templating. The values in the parameter files are loaded by order and can be overwritten. For example

--params /home/project/param1.json,/home/project/param2.json

--src

Required. The source directory where the input files are read. For example,

--src /home/project/input

--dest

Required. The destination directory where the output files are written. For example,

--dest /home/project/output

--ext

Optional. Define the template file extension. After the template file is parsed, the template file extension will be removed in the destination directory. The default value is ".pp". For example, the template file can be my-config.yaml.customExt. After being parsed, the file generated is my-config.yaml.

--ext .customExt

--debug

Optional. Turn on debug logging. Disabled by default.

--debug

--overwrite

Optional. Allow the parameters to be overwritten in parameter files and validator files. Disabled by default.

--overwrite

--validator

Optional. Accept a list of json files which contain the regular expressions used for validating the parameters loaded from the parameter files. The values in the validator files are loaded by order and can be overwritten. For example

--validator /home/project/validator1.json,/home/project/validator2.json

Templating

All objects defined in the parameter json files are flattened and stored in a Map which are used to match the mustache styled template. Json objects and array are supported.

param.json

{
  "app": {
    "name": "app1"
  },
  "envs": [
    "dev",
    "staging",
    "prod"
  ]
}

template.yaml.pp

name: {{ app.name }}
envs:
  - {{ envs.[0] }}
  - {{ envs.[1] }}
  - {{ envs.[2] }}

Overwrite parameters

If there is more than one parameter file, the parameters defined earlier can be overwritten by later values with the same key. For example,

param1.json

{
  "param": {
    "nestedParam2": {
      "nestedParam3": "nestedParam3"
    }
  },
  "array": [
    "element1",
    "element2"
  ],
  "notAffected": "This will not be overwritten because it doesn't exist in param2.json"
}

param2.json

{
  "param": {
    "nestedParam2": {
      "nestedParam3": "overwritten"
    }
  },
  "array": [
    "element1",
    "overwritten",
  ],
}

If we import parameter files in this order

npx paramplate --params param1.json,param2.json ...

Two vaules are overwritten here.

{{ array.[1] }}  # overwritten
{{ param.nestedPram2.nestedPram3 }} # overwritten

Validate parameters

The parameters loaded from parameter files can be validated against given regular expressions. The json path of the object needs to match in both parameter file and validator file so the regular expression logic can kick in to search for a match.

param.json

{
  "param": {
    "nestedParam2": {
      "nestedParam3": "nestedParam3"
    }
  },
  "notValidated": "This will not be validated because it doesn't exist in validator.json"
}

validator.json

{
  "param": {
    "nestedParam2": {
      "nestedParam3": "n*3"
    }
  }
}

If we load the param.json and validator.json, "nestedParam3" will be validated against the regular expression: "n*3". If the validation fails, the program will display an error and exit.

npx paramplate --params param.json --validator validator.json ...

Development

# Build
npm run build
# Test
npm run test

License

MIT