01alchemist/sls-yaml

Serverless framework yaml extension compiler and more

Serverless YAML extension parser

This tiny library will parse YAML extensions used in serverless framework.

Usage

npm install sls-yaml

import yaml from "sls-yaml";
const compiledYamlAsJsonObject = yaml(YAML_FILE_PATH_OR_BUFFER);

Supported sls extensions

• Include external file ${file(path/to/file.yml)}
• Inject environment variable ${env:NODE_ENV}
• Inject global variables ${global:path.to.variable}
• Inject local variables ${self:path.to.variable}

New extensions*

• Inject current git branch ${git:branch}
• Inject last git commit hash ${git:sha1}
• String replace ${replace(str, searchPattern, replaceValue )}

* - New extension not present in serverless yaml

Custom extensions

const context = {
  custom: ([arg]: string[]) => {
    return `${arg}-beta`;
  }
};
const result = yaml(content, null, context);

name: service
version: v1.0.2
subset: service@${custom(${self:version})}

• output

name: service
version: v1.0.2
subset: [email protected]

Include external file

This extension will include content of external yaml files.

• config.yml

version: 1
env: dev
config: ${file(./common.yml)}

• common.yml

endpoint: http://service-url

• Generated final yaml

version: 1
env: dev
config:
  endpoint: http://service-url

Inject environment variable

This extension will inject envronment values

• config.yml export NODE_ENV = development

version: 1
env: ${env:NODE_ENV}

• Generated final yaml

version: 1
env: development

Inject global variables

This extension will inject variable from global scope.

• config.yml

version: 1
env: stage
config: ${file(./common.yml)}

• common.yml

endpoint: http://service-${global:env}

• Generated final yaml

version: 1
env: stage
config:
  endpoint: http://service-stage

Inject local variables

This extension will inject variable from local scope.

• config.yml

version: 1
env: stage
config: ${file(./common.yml)}

• common.yml

port: 8080
endpoint: http://service:${self:port}

• Generated final yaml

version: 1
env: stage
config:
  port: 8080
  endpoint: http://service:8080

Inject current git branch

This extension will inject current git branch name

• config.yml

branch: ${git:branch}

Inject last git commit hash

This extension will inject last git commit hash

• config.yml

image.tag: ${git:sha1}

String replace

replace(str:string, searchPattern:RegExp|string, replaceValue:string )

This extension will returns a new string with some or all matches of a pattern replaced by a replacement. The pattern can be a string or a RegExp, and the replacement can be a string or a function to be called for each match. If pattern is a string, only the first occurrence will be replaced.

• config.yml

version: v1.0.0
name: ServiceName@${replace(${ self : version }, /\\./gi, - )}

• output

version: v1.0.0
name: ServiceName@v1-0-0

sls-yaml's Issues

Add support for opt reference

It would be really nice to add support for the opt reference, i.e.:
${opt:stage}

I think the only way to really do this would be to allow users to pass a cliOptions object to readYamlSync. Then you could treat it very similarly to the env reference.

Ideally, the following would be possible:

options: ${opt:}
.......
field: ${self:options.stage}

If the serverless file uses the opt reference, everything breaks, which is very unfortunate.

Recursively reference properties do not work

Documentation from the serverless framework

reference-properties-in-other-files

The following example doesn't work

provider:
  name: aws
  environment:
    MY_SECRET: ${file(./config.${opt:stage, 'dev'}.json):CREDS}

The :CREDS is appended to the file path resulting in a file not found exception

Using env reference within file reference doesn't work

The following cannot be parsed:
"${file(${env:FILE_PATH}/config.global.yml)}"

This could be fixed in a hacky way by doing something like:

if (
    functionName === "file" &&
    _arguments.length >= 1 &&
    typeof _arguments[_arguments.length - 1] === "string" &&
    _arguments[_arguments.length - 1].includes(path.sep) &&
    child.value[0] === path.sep
) {
    let previousValue = _arguments.pop()
    _arguments.push(previousValue + child.value)

on line 484 of src/template-compiler/index.ts, but I imagine you'd have a more elegant solution. I'm not real good with javascript/typescript.