Action-input-parser NPM

David

Helper for parsing inputs in a GitHub Action

⭐ Features

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

🚀 Get started

npm install action-input-parser

📚 Usage

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

const parser = require('action-input-parser')

const value = parser.getInput('name')

Example

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.

⚙️ Configuration

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)

All options

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

Name	Description	Required	Default
`key`	The key of the input option (can also be an array of keys)	Yes	N/A
`type`	The type of the input value (`string`/`boolean`/`number`/`array`)	No	`string`
`required`	Specify if the input is required	No	false
`default`	Specify a default value for the input	No	N/A
`disableable`	Specify if the input should be able to be disabled by setting it to `false`	No	`false`
`modifier`	A function which gets passed the parsed value as a parameter and returns another value	No	N/A

Key

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

See example

Types

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

Required inputs

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

See example

Default values

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

See example

Disableable input

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

Modifier function

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

See example

Development

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.

📖 Examples

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

Basic example

Action Workflow:

uses: username/action
with:
    name: Maximilian

Action code:

const parser = require('action-input-parser')

const value = parser.getInput('name')

// value -> Maximilian

const parser = require('action-input-parser')

const value = parser.getInput({
    key: 'name'
})

// value -> Maximilian

Specify a type

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'

Specify a default value

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

Set an input to be required

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

Disable an input

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

Multiple Keys

Action code:

const parser = require('action-input-parser')

const value = parser.getInput({ 
    key: [ 'GITHUB_TOKEN', 'GH_PAT' ]
})

// The first key takes precedence

Modify the parsed input

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

Advanced example

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
}