• Similar API to core.getInput()
• Parses string, booleans, numbers and arrays to correct JS types
• Supports default values if no input was provided
• Throws errors if input is set to required and is missing
• Uses local environment variables (and .env files) during development
• Specify a custom function for advanced parsing
• Supports array of keys

Install action-input-parser via npm:

npm install action-input-parser

Import action-input-parser and use it like this:

const parser = require('action-input-parser') const value = parser.getInput('name')

Let's say you have the following workflow file (see below on how to specify inputs during development):

uses: username/action with: names: |  Maximilian  Richard

Pass an options object to the getInput function to specify the array type:

const parser = require('action-input-parser') const value = parser.getInput('names', { type: 'array' }) // [ 'Maximilian', 'Richard' ]

action-input-parser will parse the names input and return an array.

See below for all options or checkout a few more examples.

You can pass the following JavaScript object to getInput as the first or second parameter to tell action-input-parser what to parse:

const options = { key: 'names', type: 'array', default: [ 'maximilian' ] } parser.getInput(options)

Here are all the options you can use and there default values:

You can either specify a single key as a string, or multiple keys as an array of strings.

See example

You can specify one of the following types which will determine how the input is parsed:

• string - default type, the input value will only be trimmed
• boolean - will parse a boolean based on the yaml 1.2 specification
• number - will convert the input to a number
• array - will parse line or comma seperated values to an array

Note: if the input can not be converted to the specifed type, an error is thrown

See example

When you set required to true and the input is not set, action-input-parser will throw an error.

See example

You can specify a default value for the input which will be used when the input is not set.

See example

If you have an input with a default value but you still want the user to be able to unset the input, set the disableable option to true.

When the input is then set to false, action-input-parser will return undefined instead of your default value.

See example

If your input needs additional processing you can specify a function which will be passed the parsed input value.

See example

If you run your Action locally during development, you can set the inputs as environment variables or specify them in a .env file. action-input-parser will use them as the inputs automatically.

Here are some examples on how to use action-input-parser:

Action Workflow:

uses: username/action with: name: Maximilian

Action code:

const parser = require('action-input-parser') const value = parser.getInput('name') // value -> Maximilian

or

const parser = require('action-input-parser') const value = parser.getInput({ key: 'name' }) // value -> Maximilian

Action Workflow:

uses: username/action with: dry_run: true

Action code:

const parser = require('action-input-parser') const value = parser.getInput({ key: 'dry_run', type: 'boolean' }) // Without setting the type to boolean, the value would have been 'true'

Action code:

const parser = require('action-input-parser') const value = parser.getInput({ key: 'name', default: 'Maximilian' }) // If name is not set, Maximilian will be returned as the name

Action code:

const parser = require('action-input-parser') const value = parser.getInput({ key: 'name', required: true }) // Will throw an error if name is not set

Action Workflow:

uses: username/action with: labels: false

Action code:

const parser = require('action-input-parser') const value = parser.getInput({ key: 'labels', default: [ 'merged', 'ready' ], disableable: true }) // Value will be undefined because labels was set to false

Action code:

const parser = require('action-input-parser') const value = parser.getInput({ key: [ 'GITHUB_TOKEN', 'GH_PAT' ] }) // The first key takes precedence

Action Workflow:

uses: username/action with: name: Maximilian

Action code:

const parser = require('action-input-parser') const value = parser.getInput({ key: 'name', modifier: (val) => { return val.toLowerCase() } }) // Value will be maximilian

Action Workflow:

uses: username/action with: github_token: TOKEN repository: username/reponame labels: |  merged  ready

Action code:

const { getInput } = require('action-input-parser') const config = { githubToken: getInput({ key: 'github_token', required: true }), repository: getInput({ key: 'repository', modifier: (val) => { const [user, repo] = val.split('/') return { user, repo } } }), labels: getInput({ key: 'labels', type: 'array' }), dryRun: getInput({ key: 'dry_run', type: 'boolean', default: false }), } // parsed config: { githubToken: 'TOKEN', repository: { name: 'username', repo: 'reponame' }, labels: [ 'merged', 'ready' ], dryRun: false }

Issues and PRs are very welcome!

The actual source code of this library is in the src folder.

• run yarn lint or npm run lint to run eslint.
• run yarn build or npm run build to produce a compiled version in the lib folder.

This project was developed by me (@betahuhn) in my free time. If you want to support me:

Copyright 2021 Maximilian Schiller

This project is licensed under the MIT License - see the LICENSE file for details.