Github-action-input-parser NPM

Helper for parsing inputs in a GitHub Action

⭐ Features

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 inputs
Supports Typescript
Supports parsing multiple inputs

🚀 Get started

Install github-action-input-parser via npm:

npm install github-action-input-parser

📚 Usage

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

Javascript:

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

JS Modules/Typescript:

import * as parser from 'github-action-input-parser';

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 an array of String type:

const value = parser.getInput({
    input: 'names',
    type: <const>[String],
});

// [ 'Maximilian', 'Richard' ]

github-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 object to getInput to tell github-action-input-parser what to parse:

const options = {
    input: 'names',
    type: <const>[String],
    default: <const>['maximilian'],
};

parser.getInput(options);

All options

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

Name	Description	Required	Default	See more
`input`	The input name (can also be an array of inputs)	Yes	N/A	Input
`type`	The type of the input value	No	`String`	Types
`required`	Specify if the input is required	No	false	Required Inputs
`default`	Specify a default value for the input	No	undefined	Default Values

Input

You can either specify a single input as a string, or multiple inputs as an array of strings. This options declares which input(s) should be parsed. When using an array of inputs the first input defined will be picked for parsing.

Note: Even when the chosen input can not be parsed for the given type, github-action-input-parser will not try another input and instead throw an error

See example

Types

You can specify one of the following basic types (BaseTypes) 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
(value: string) => any / Function - Will call the function specified to parse an input. Use this for custom types

Note: String, Boolean and Number are literals of type StringConstructor, BooleanConstructor and NumberConstructor respectively
Note: if the input can not be converted to the specifed type, an error is thrown

Additionally you can specifiy an array with the 4 BaseTypes as elements. When using typescript it is recommended to prefix the array with <const> or suffix it with as const for optimal type-hinting. The meaning of the array type depends on the amount of its elements:

0 elements - not allowed, github-action-input-parser will throw an error
1 element - github-action-input-parser will treat this type as an Array Type and tries parsing the input for any number of elements separated by a comma or a newline using the parser specified by the BaseType inside the type array
2+ elements - github-action-input-parser will treat this type as a Tuple Type and tries parsing the input for as many elements separated by a comma or a newline as the number of elements in the type array. The parser used depends on the type at the equivalent index in the type array

See example

Required inputs

When you set required to true and the input(s) are not set or could not be parsed, github-action-input-parser will throw an error. When using an array type github-action-input-parser will check each element of the resulting array and if any of them could not be parsed github-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. How this default value will be used depends on its type and the type of the parsed content:

`type` option	default value type	behavior
BaseTypes	any	The default value replaces the parsed value if the parsed value is `undefined`
ArrayType or TupleType	any non-array	The default value replaces any `undefined` elements of the parsed array. However the default value will not replace the parsed value itself if it ends up being `undefined` (e.g. when the input is not set)
ArrayType or TupleType	any array	The elements of the default value replace any `undefined` element at the same index in the parsed array. If the parsed array is longer than the default value array this can result in `undefined` elements beyond the length of the default value array. The default value array will replace the parsed array if it is `undefined`

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. github-action-input-parser will use them as the inputs automatically.

Typescript

This library has Typescript support but to get the most out of it you have to prefix any array passed to the configuration options type and default with <const> or suffix them with as const.

See example

`getInputs`

To parse multiple inputs with different configurations into one options you can use the getInputs() function. It takes an object where each element is either an argument for getInput() (string | string[] | Options) or undefined. When an element is undefined the key will be used as the input name.

See example

📖 Examples

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

See README.test.ts

Basic example

Action Workflow:

uses: username/action
with:
    name: Maximilian

Action code:

const value = parser.getInput('name');

// value -> Maximilian

const value = parser.getInput({
    input: 'name',
});

// value -> Maximilian

Specify a type

Action Workflow:

uses: username/action
with:
    dry_run: true

Action code:

const value = parser.getInput({ 
    input: 'dry_run',
    type: Boolean,
});

// Without setting the type to boolean, the value would have been 'true'

Action Workflow:

uses: username/action
with:
    stages: |
        'dev'
        'prod'

Action code:

const value = parser.getInput({ 
    input: 'stages',
    type: <const>[String],
});

// ['dev', 'prod']

Action Workflow:

uses: username/action
with:
    fruits: |
        10
        apples

Action code:

const value = parser.getInput({ 
    input: 'fruits',
    type: <const>[Number, String],
});

// [10, 'apples']

Specify a default value

Action Workflow:

uses: username/action
with:

Action code:

const value = parser.getInput({ 
    input: 'name',
    default: 'Maximilian',
});

// As name is not set, Maximilian will be returned as the name

Action Workflow:

uses: username/action
with:
    command: |
        bring me

        apples

Action code:

const value = parser.getInput({ 
    input: 'command',
    type: <const>[String, Number, String],
    default: <const>[undefined, 10],
});

// ['bring me', 10, 'apples']

Set an input to be required

Action Workflow:

uses: username/action
with:

Action code:

const value = parser.getInput({
    input: 'name',
    required: true,
});

// Will throw an error if name is not set

Pick from multiple inputs

Action Workflow:

uses: username/action
with:
    GH_PAT: 'abcdefghijklmnopqrstuvwxyz';

Action code:

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

// The first input available takes precedence -> GH_PATs value will be parsed

Parse multiple inputs

Action code:

Javascript:

uses: username/action
with:
    greeting: 'Hello world!'
    GH_PAT: 'abcdefghijklmnopqrstuvwxyz'

const {value1, value2, value3} = parser.getInputs({
    value1: 'greeting',
    value2: {
        input: [ 'GITHUB_TOKEN', 'GH_PAT' ],
        required: true,
    },
    value3: {
        input: 'max retires',
        type: Number,
        default: 3,
    },
});

// value1 = 'Hello world!', value2 = 'abcdefghijklmnopqrstuvwxyz', value3 = 3

Advanced example

Action Workflow:

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

Action code:

const config = getInputs({
    githubToken: {
        input: 'github_token',
        required: true,
    },
    repository: {
        input: 'repository',
        type: (val) => {
            const [user, repo] = val.split('/')
            return { user, repo }
        },
    },
    labels: {
        input: 'labels',
        type: <const>[String],
    },
    dryRun: {
        input: 'dry_run',
        type: Boolean,
        default: false,
    },
});

// parsed config:
{
    githubToken: 'TOKEN',
    repository: {
        name: 'username',
        repo: 'reponame'
    },
    labels: [ 'merged', 'ready' ],
    dryRun: false,
}