{"id":15090158,"url":"https://github.com/pdamianik/github-action-input-parser","last_synced_at":"2025-10-05T23:31:36.761Z","repository":{"id":62665475,"uuid":"557579241","full_name":"pdamianik/github-action-input-parser","owner":"pdamianik","description":"🎬🛠️ Helper for parsing inputs in a GitHub Action","archived":false,"fork":true,"pushed_at":"2022-11-09T16:15:50.000Z","size":396,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-01-17T09:43:28.043Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://mxis.ch","language":"TypeScript","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"BetaHuhn/action-input-parser","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pdamianik.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"ko_fi":"betahuhn","github":"betahuhn"}},"created_at":"2022-10-25T23:51:14.000Z","updated_at":"2022-10-28T19:22:12.000Z","dependencies_parsed_at":"2023-01-22T10:30:54.126Z","dependency_job_id":null,"html_url":"https://github.com/pdamianik/github-action-input-parser","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pdamianik%2Fgithub-action-input-parser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pdamianik%2Fgithub-action-input-parser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pdamianik%2Fgithub-action-input-parser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pdamianik%2Fgithub-action-input-parser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pdamianik","download_url":"https://codeload.github.com/pdamianik/github-action-input-parser/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235461368,"owners_count":18994068,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-09-25T09:22:39.909Z","updated_at":"2025-10-05T23:31:31.419Z","avatar_url":"https://github.com/pdamianik.png","language":"TypeScript","funding_links":["https://ko-fi.com/betahuhn","https://github.com/sponsors/betahuhn","https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick\u0026hosted_button_id=394RTSBEEEFEE","https://ko-fi.com/F1F81S2RK"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \n# Github Action Input Parser\n\n[![GitHub](https://img.shields.io/github/license/mashape/apistatus.svg)](https://github.com/pdamianik/github-action-input-parser/blob/master/LICENSE)\n\nHelper for parsing inputs in a GitHub Action\n\n\u003c/div\u003e\n\n## ⭐ Features\n\n- Parses [string, booleans, numbers and arrays](#types) to correct JS types\n- Supports [default values](#default-values) if no input was provided\n- Throws errors if input is set to [required](#required-inputs) and is missing\n- Uses local environment variables and `.env` files during [development](#development)\n- Specify a [custom function](#types) for advanced parsing\n- Supports [array of inputs](#input)\n- Supports [Typescript](#typescript)\n- Supports parsing [multiple inputs](#getInputs)\n\n## 🚀 Get started\n\nInstall [github-action-input-parser](https://github.com/pdamianik/github-action-input-parser) via npm:\n\n```shell\nnpm install github-action-input-parser\n```\n\n## 📚 Usage\n\nImport `github-action-input-parser` and use it like this:\n\nJavascript:\n\n```js\nconst parser = require('github-action-input-parser');\n```\n\nJS Modules/Typescript:\n\n```js\nimport * as parser from 'github-action-input-parser';\n```\n\n### Example\n\nLet's say you have the following workflow file (see [below](#development) on how to specify inputs during development):\n\n```yml\nuses: username/action\nwith:\n    names: |\n        Maximilian\n        Richard\n```\n\nPass an options object to the `getInput` function to specify an array of `String` type:\n\n```ts\nconst value = parser.getInput({\n    input: 'names',\n    type: \u003cconst\u003e[String],\n});\n\n// [ 'Maximilian', 'Richard' ]\n```\n\n[github-action-input-parser](https://github.com/pdamianik/github-action-input-parser) will parse the `names` input and return an array.\n\nSee below for [all options](#all-options) or checkout a few more [examples](#-examples).\n\n## ⚙️ Configuration\n\nYou can pass the following object to `getInput` to tell [github-action-input-parser](https://github.com/pdamianik/github-action-input-parser) what to parse:\n\n```ts\nconst options = {\n    input: 'names',\n    type: \u003cconst\u003e[String],\n    default: \u003cconst\u003e['maximilian'],\n};\n\nparser.getInput(options);\n\n```\n\n### All options\n\nHere are all the options you can use and there default values:\n\n| Name | Description | Required | Default | See more |\n| ------------- | ------------- | ------------- | ------------- | ------------- |\n| `input` | The input name (can also be an array of inputs) | **Yes** | N/A | [Input](#input) |\n| `type` | The type of the input value | **No** | `String` | [Types](#types) |\n| `required` | Specify if the input is required | **No** | false | [Required Inputs](#required-inputs) |\n| `default` | Specify a default value for the input | **No** | undefined | [Default Values](#default-values) |\n\n### Input\n\nYou 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.\n\n\u003e Note: Even when the chosen input can not be parsed for the given type, [github-action-input-parser](https://github.com/pdamianik/github-action-input-parser) will not try another input and instead throw an error\n\n[See example](#pick-from-multiple-inputs)\n\n### Types\n\nYou can specify one of the following basic types (BaseTypes) which will determine how the input is parsed:\n\n- `String` - Default type, the input value will only be trimmed\n- `Boolean` - Will parse a boolean based on the [yaml 1.2 specification](https://yaml.org/spec/1.2/spec.html#id2804923)\n- `Number` - Will convert the input to a number\n- `(value: string) =\u003e any` / `Function` - Will call the function specified to parse an input. Use this for custom types\n\n\u003e Note: `String`, `Boolean` and `Number` are literals of type `StringConstructor`, `BooleanConstructor` and `NumberConstructor` respectively\n\n\u003e Note: if the input can not be converted to the specifed type, an error is thrown\n\nAdditionally you can specifiy an array with the 4 BaseTypes as elements. When using typescript it is recommended to prefix the array with `\u003cconst\u003e` or suffix it with `as const` for optimal type-hinting. The meaning of the array type depends on the amount of its elements:\n\n - 0 elements - not allowed, [github-action-input-parser](https://github.com/pdamianik/github-action-input-parser) will throw an error\n - 1 element - [github-action-input-parser](https://github.com/pdamianik/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\n - 2+ elements - [github-action-input-parser](https://github.com/pdamianik/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\n\n[See example](#specify-a-type)\n\n### Required inputs\n\nWhen you set required to true and the input(s) are not set or could not be parsed, [github-action-input-parser](https://github.com/pdamianik/github-action-input-parser) will throw an error. When using an array type [github-action-input-parser](https://github.com/pdamianik/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](https://github.com/pdamianik/github-action-input-parser) will throw an error.\n\n[See example](#set-an-input-to-be-required)\n\n### Default values\n\nYou 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](#types) of the parsed content:\n\n| `type` option | default value type | behavior |\n| ------------- | ------------- | ------------- |\n| BaseTypes | any | The default value replaces the parsed value if the parsed value is `undefined` |\n| 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) |\n| 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`\n\n[See example](#specify-a-default-value)\n\n### Development\n\nIf 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](https://github.com/pdamianik/github-action-input-parser) will use them as the inputs automatically.\n\n## Typescript\n\nThis library has Typescript support but to get the most out of it you have to prefix any array passed to the configuration options [type](#types) and [default](#default-values) with `\u003cconst\u003e` or suffix them with `as const`.\n\n[See example](#specify-a-type)\n\n## `getInputs`\n\nTo 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.\n\n[See example](#parse-multiple-inputs)\n\n## 📖 Examples\n\nHere are some examples on how to use [github-action-input-parser](https://github.com/pdamianik/github-action-input-parser):\n\nSee [README.test.ts](https://github.com/pdamianik/github-action-input-parser/blob/master/test/README.test.ts)\n\n### Basic example\n\nAction Workflow:\n\n```yml\nuses: username/action\nwith:\n    name: Maximilian\n```\n\nAction code:\n\n```js\nconst value = parser.getInput('name');\n\n// value -\u003e Maximilian\n```\n\nor \n\n```js\nconst value = parser.getInput({\n    input: 'name',\n});\n\n// value -\u003e Maximilian\n```\n\n### Specify a type\n\nAction Workflow:\n\n```yml\nuses: username/action\nwith:\n    dry_run: true\n```\n\nAction code:\n\n```js\nconst value = parser.getInput({ \n    input: 'dry_run',\n    type: Boolean,\n});\n\n// Without setting the type to boolean, the value would have been 'true'\n```\n\nAction Workflow:\n\n```yml\nuses: username/action\nwith:\n    stages: |\n        'dev'\n        'prod'\n```\n\nAction code:\n\n```ts\nconst value = parser.getInput({ \n    input: 'stages',\n    type: \u003cconst\u003e[String],\n});\n\n// ['dev', 'prod']\n```\n\nAction Workflow:\n\n```yml\nuses: username/action\nwith:\n    fruits: |\n        10\n        apples\n```\n\nAction code:\n\n```ts\nconst value = parser.getInput({ \n    input: 'fruits',\n    type: \u003cconst\u003e[Number, String],\n});\n\n// [10, 'apples']\n```\n\n### Specify a default value\n\nAction Workflow:\n\n```yml\nuses: username/action\nwith:\n```\n\nAction code:\n\n```js\nconst value = parser.getInput({ \n    input: 'name',\n    default: 'Maximilian',\n});\n\n// As name is not set, Maximilian will be returned as the name\n```\n\nAction Workflow:\n\n```yml\nuses: username/action\nwith:\n    command: |\n        bring me\n\n        apples\n```\n\nAction code:\n\n```ts\nconst value = parser.getInput({ \n    input: 'command',\n    type: \u003cconst\u003e[String, Number, String],\n    default: \u003cconst\u003e[undefined, 10],\n});\n\n// ['bring me', 10, 'apples']\n```\n\n### Set an input to be required\n\nAction Workflow:\n\n```yml\nuses: username/action\nwith:\n```\n\nAction code:\n\n```js\nconst value = parser.getInput({\n    input: 'name',\n    required: true,\n});\n\n// Will throw an error if name is not set\n```\n\n### Pick from multiple inputs\n\nAction Workflow:\n\n```yml\nuses: username/action\nwith:\n    GH_PAT: 'abcdefghijklmnopqrstuvwxyz';\n```\n\nAction code:\n\n```js\nconst value = parser.getInput({ \n    input: [ 'GITHUB_TOKEN', 'GH_PAT' ]\n});\n\n// The first input available takes precedence -\u003e GH_PATs value will be parsed\n```\n\n### Parse multiple inputs\n\nAction code:\n\nJavascript:\n\n```yml\nuses: username/action\nwith:\n    greeting: 'Hello world!'\n    GH_PAT: 'abcdefghijklmnopqrstuvwxyz'\n```\n\n```js\nconst {value1, value2, value3} = parser.getInputs({\n    value1: 'greeting',\n    value2: {\n        input: [ 'GITHUB_TOKEN', 'GH_PAT' ],\n        required: true,\n    },\n    value3: {\n        input: 'max retires',\n        type: Number,\n        default: 3,\n    },\n});\n\n// value1 = 'Hello world!', value2 = 'abcdefghijklmnopqrstuvwxyz', value3 = 3\n```\n\n### Advanced example\n\nAction Workflow:\n\n```yml\nuses: username/action\nwith:\n    github_token: TOKEN\n    repository: username/reponame\n    labels: |\n        merged\n        ready\n```\n\nAction code:\n\n```ts\nconst config = getInputs({\n    githubToken: {\n        input: 'github_token',\n        required: true,\n    },\n    repository: {\n        input: 'repository',\n        type: (val) =\u003e {\n            const [user, repo] = val.split('/')\n            return { user, repo }\n        },\n    },\n    labels: {\n        input: 'labels',\n        type: \u003cconst\u003e[String],\n    },\n    dryRun: {\n        input: 'dry_run',\n        type: Boolean,\n        default: false,\n    },\n});\n\n// parsed config:\n{\n    githubToken: 'TOKEN',\n    repository: {\n        name: 'username',\n        repo: 'reponame'\n    },\n    labels: [ 'merged', 'ready' ],\n    dryRun: false,\n}\n```\n\n## 📖 Extended Examples\n\nSee [index.test.ts](https://github.com/pdamianik/github-action-input-parser/blob/master/src/index.test.ts)\n\n## 💻 Development\n\nIssues and PRs are very welcome!\n\nThe actual source code of this library is in the `src` folder.\n\n- run `yarn lint` or `npm run lint` to run eslint.\n- run `yarn build` or `npm run build` to produce a compiled version in the `lib` folder.\n\n## ❔ About\n\nThis project was originally developed by ([@betahuhn](https://github.com/BetaHuhn)) and was heavily modified by ([@pdamianik](https://github.com/pdamianik/)) in their free time. If you want to support [@betahuhn](https://github.com/BetaHuhn):\n\n[![Donate via PayPal](https://img.shields.io/badge/paypal-donate-009cde.svg)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick\u0026hosted_button_id=394RTSBEEEFEE)\n\n[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/F1F81S2RK)\n\n## 📄 License\n\nCopyright 2021 Maximilian Schiller\u003cbr\u003e\nCopyright 2022 Philip Damianik\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpdamianik%2Fgithub-action-input-parser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpdamianik%2Fgithub-action-input-parser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpdamianik%2Fgithub-action-input-parser/lists"}