# Serverless Plugin Template Function Calls

This package is a plugin for the [serverless framework](https://serverless.com/). It provides an extension to the serverless template files to include function calls to javascript node modules.

## Installation
Install the package with npm via `npm install serverless-template-function-calls` and add `serverless-template-function-calls` to the plugins list. For Yaml that would look like this:
```
plugins:
   - serverless-template-function-calls
```

## Usage

Functions are loaded from in the config specified module files and support nested functions in objects. Long function names are resolved via the dot notation. Short function names are available as aliases via the name behind the last dot (long name: module.nested.func1, short name: func1) (be aware that long function names will replace short ones in case of identical names).

There are two ways functions are called:

#### Inline Replacement:
In the template string values will be replaced if a string has the format ```[function_prefix][function_name]("[arg1]", "[arg2]", ...)``` by the function return value if supplied with the arguments.

Example: ``prop: +module.func1("hello ")``

#### Object Replacement:

In the template if the child key of an object has the format ```[function_prefix][function_name](...)``` the parent will be replaced by the function return value if supplied with the child value as the argument.

Example:
```
prop:
	+module.func1(...): "hello "
```



### Example

#### Modules
single_function.js
```
module.exports = () => "hello";
```

multi_function.js
```
module.exports.func0 = (a) => paresInt(a) * 2,
module.exports.some_namespace = {
   func1: (x, y) => x + " and " + y,
   nested_namespace: {
      func2: (a, b) => ({ a, b }),
      func4: ({a1, a2}) => a1 + a2
   }
};
```

### Input Template (in YAML)

```
custom:
   ref_prop: 1000
   some_prop: +single_function()
   other_prop: '+multi_function.some_namespace.nested_namespace.func2("valA", "valB")'
   nested_prop:
      - something
      - +multi_function.func0("${self:custom.ref_prop}")
   object_prop:
	   +multi_function.some_namespace.nested_namespace.func4(...):
		   a1: 5
		   a2: 10
```
which is equivalent to (with short function names)
```
custom:
   ref_prop: 1000
   some_prop: +single_function()
   other_prop: '+func2("valA", "valB")'
   nested_prop:
      - something
      - +func0("${self:custom.ref_prop}")
   object_prop:
	   +func4(...):
		   a1: 5
		   a2: 10
```

### Output Template (in YAML)

```
custom:
   ref_prop: 1000
   some_prop: "hello"
   other_prop:
      a: "valA"
      b: "valB"
   nested_prop:
      - "something"
      - 2000
   object_prop: 15
```

Also note that strings are trimmed for the interpretation as a function call string.

## Configuration

The configuration is read from the serverless template in the custom.templateFunctionCalls object. Like this:
```
custom:
   templateFunctionCalls:
      some_config_property: some_config_value
      ...
```
The possible properties and values follow now.

### Properties

#### modules (default value: [ ], expected type: string array)
These are the module files from which the functions are read. The paths have to be specified relative to the template file or absolute and need to be conforment to the require node syntax (.js can therefore be omitted).

#### functionPrefix (default value: "+", expected type: string)

The prefix that needs to be before any function name in order to be recognized. Can be any string (including "") .

#### roots (default value: ["resources", "functions", "custom", "layers", "service", "provider", "plugins", "outputs"], expected type: string array)

These are the template root properties to which the replacement of function call strings are applied.

##### Example Config
In this example config, functions would be recognized without having any prefix. The functions are loaded from module1.js and the module file in the dir2 directory. And any function string call on properties other from resources are ignored. Therefore the template:
```
custom:
   templateFunctionCalls:
         functionPrefix: ""
         modules: ["module1.js", "dir2/module"]
         roots: ["resources"]

   some_prop: module1.hello()
   other_prop: module.test()

resources:
   Resources:
      resource1: ${self:custom.some_prop}
      resource2: module.test()
```

assuming module1.hello() = 5 and module.test() = "some string", the template would result in:

```
custom:
   templateFunctionCalls:
         functionPrefix: ""
         modules: ["module1.js", "dir2/module"]
         roots: ["resources"]

   some_prop: module1.hello()
   other_prop: module.test()

resources:
   Resources:
      resource1: 5
      resource2: "some string"
```