{"_id":"@action-class/core","name":"@action-class/core","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@action-class/core","version":"1.0.0","description":"Framework to write object oriented GitHub Actions","author":{"name":"Jan Günter","email":"jan.guenter@googlemail.com"},"keywords":["github","actions"],"homepage":"https://github.com/jan-guenter/actions-class/tree/main/packages/core","license":"MIT","main":"lib/index.js","types":"lib/index.d.ts","type":"module","directories":{"lib":"lib","test":"__tests__"},"bin":{"generate-action-yml":"lib/generate-action-yml.js"},"publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/jan-guenter/actions-class.git","directory":"packages/core"},"bugs":{"url":"https://github.com/jan-guenter/actions-class/issues"},"dependencies":{"@actions/core":"^1.10.0","find-up":"^6.3.0","js-yaml":"^4.1.0","yargs":"^17.7.1","@action-class/action-yml":"^1.0.0"},"devDependencies":{"@jest/globals":"^29.5.0","@types/js-yaml":"^4.0.5","@types/node":"~16.18.23","@types/yargs":"^17.0.24"},"scripts":{"test":"echo \"Error: run tests from root\" && exit 1","tsc":"tsc"},"_id":"@action-class/core@1.0.0","_integrity":"sha512-X13B62z9v2Yv7WLIFx91dFtnGA/0RTPmL5a0r3meO8gpBqL/RmIq8TvmnE08+3sA5ucIVjcQeacPj29dB+xiNg==","_resolved":"/tmp/b3fcc97a849d01a55e931e5591c65ba5/action-class-core-1.0.0.tgz","_from":"file:action-class-core-1.0.0.tgz","_nodeVersion":"16.19.1","_npmVersion":"9.6.4","dist":{"integrity":"sha512-X13B62z9v2Yv7WLIFx91dFtnGA/0RTPmL5a0r3meO8gpBqL/RmIq8TvmnE08+3sA5ucIVjcQeacPj29dB+xiNg==","shasum":"c88eb1c99ed76d347e391bbd90888336d1baa425","tarball":"https://registry.npmjs.org/@action-class/core/-/core-1.0.0.tgz","fileCount":15,"unpackedSize":56169,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCIAL1erG09WCKhc5KMrFaBsKGM21+5Reg7VlMKKojtcy9AiA1YbI7HqIcVfH3pJWaXAv6HHYQh/MSaGoKnazfPqjN4g=="}],"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v4.10.10\r\nComment: https://openpgpjs.org\r\n\r\nwsFzBAEBCAAGBQJkPXVAACEJED1NWxICdlZqFiEECWMYAoorWMhJKdjhPU1b\r\nEgJ2VmoDOBAAnlwRkhBKolzIZNLz841xedNybz+RUtUim9MdPN94dEMx6Yrk\r\nnxg5tAimTG6F3HkCcJ5cSzeJ0vdRlBa9smoWKrC2IhJ0mFOqztZkN+uS8ok6\r\n+gnO58YJG7jsFpAcsH+slzO3OA8kRs/6psrIiObq0Q4MFcRfUpxdzMClEfaZ\r\nd82KJ1vux8eDFKssvuWeFzij0PxmdFe69MMRDgjmvUpcMD3DOh8Aup/ZUqQ3\r\np26JsV/mt1i5M8JKRswFpiv75t+vUINGdxq3ytxYauPyt5bou/G6lWgXMSQQ\r\nBdHL1Meip5cYZWdYe6ChKyrliVAfH8J35nwVRHstNVKPyKIhgidIPvm3dlvB\r\n2y6zPZNaeN53WjkDvLhbsWuXd/eBim/ItOF6Gz+UoSNGY/fXmib5wkR2oxxO\r\nkJgLlV5yFikxH4O0jgX8JUI/HcEVH01Wlb7BkSUNXwqxveLtjzSzFx9DDEGt\r\nyrwrYphF6TpR0armd/hFgAzCVA2Q3JajxoFxGzbTx3ZLtq6y0qNZacLl45vy\r\nYjitO1LOtkpXjKDzSM4aqaOl0rX0zTJ70vHXN1LRIW0DCE9k60aTf1ctN6re\r\nitEEa4TkXO1AvpChY+G8iJXe4uc0J6mbA5Rbj1fcPZhZsblrmkEYCB9iqt7l\r\n5nHMC21Z/OTBpPzz81TibjFlv/jcdjq8B+0=\r\n=e1BN\r\n-----END PGP SIGNATURE-----\r\n"},"_npmUser":{"name":"jan-guenter","email":"jan.guenter@googlemail.com"},"maintainers":[{"name":"jan-guenter","email":"jan.guenter@googlemail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/core_1.0.0_1681749312074_0.9486010313723929"},"_hasShrinkwrap":false}},"time":{"created":"2023-04-17T16:35:12.008Z","1.0.0":"2023-04-17T16:35:12.254Z","modified":"2023-04-17T16:35:12.446Z"},"maintainers":[{"name":"jan-guenter","email":"jan.guenter@googlemail.com"}],"description":"Framework to write object oriented GitHub Actions","homepage":"https://github.com/jan-guenter/actions-class/tree/main/packages/core","keywords":["github","actions"],"repository":{"type":"git","url":"git+https://github.com/jan-guenter/actions-class.git","directory":"packages/core"},"author":{"name":"Jan Günter","email":"jan.guenter@googlemail.com"},"bugs":{"url":"https://github.com/jan-guenter/actions-class/issues"},"license":"MIT","readme":"# `@action-class/core`\n\n> A library for creating GitHub Actions with a class-based approach.  \n> This library simplifies the process of defining inputs, outputs, and other action properties,\n> as well as handling the pre, main, and post steps of the action.\n\n## Installation\n\n```bash\nnpm install @action-class/core\n```\n\n## Usage\n\nCreate a new GitHub Action class by extending the constructor returned by the `action` call from '@action-class/core'.\nDefine action properties, inputs, and outputs in the `action` call argument.\nTo complete a runnable action you need to implement at least a `main` and optionally a `pre`, and a `post` method.\n\n```typescript\nimport { action, runAction } from '@action-class/core';\n\nexport class ExampleAction extends action({\n  name: 'name',\n  description: 'description',\n  author: 'author',\n  branding: {\n    color: 'orange',\n    icon: 'sunset',\n  },\n  inputs: {\n    // Define your inputs here\n  },\n  outputs: {\n    // Define your outputs here\n  },\n}) {\n  // Define your class properties and constructor here\n\n  async pre(): Promise<void> {\n    // Define the pre step logic here\n  }\n\n  async main(): Promise<void> {\n    // Define the main step logic here\n  }\n\n  async post(): Promise<void> {\n    // Define the post step logic here\n  }\n}\n\n// Execute the action with the constructor arguments\nrunAction(TestAction, 'test');\n```\n\n## API\n\n### `action(options: ActionOptions): constructor`\n\nThe action function is a higher-order function that takes an `ActionOptions` object as an argument and returns a class\nconstructor. The `ActionOptions` object defines the properties, inputs, outputs, and branding for the action.\n\n### `runAction(ActionClass: Class, ...args: any[]): Promise<void>`\n\nThe `runAction` function takes a GitHub Action class and its constructor arguments, then executes the action.\nThis async function needs to be called at the end of the action file and not being awaited.\n\n### `ActionOptions`\n\n- `name` _(optional)_: The name of the action. Defaults to the name from the `package.json`.\n- `description` _(optional)_: A short description of the action. Defaults to the description from the `package.json`.\n- `author` _(optional)_: The author of the action. Defaults to the author from the `package.json` if present.\n- `branding` _(optional)_: An object with branding properties for the action. See\n  [GitHub branding guidelines](https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions#branding)\n  for valid values.\n- `inputs` _(optional)_: An object with the action inputs. See [Inputs](#inputs) for more information.\n- `outputs` _(optional)_: An object with the action outputs. See [Outputs](#outputs) for more information.\n\n#### Inputs and Outputs\n\nThe `inputs` and `outputs` properties of the `ActionOptions` object define the inputs and outputs of your GitHub Action.\nInputs and outputs are defined using key-value pairs, where the key is the name of the input or output, and the value is\nan object with specific properties.\n\n##### Inputs\n\nInputs are defined in the `inputs` property of the `ActionOptions` object.\nEach input is represented by an object with the following properties:\n\n- `description`: A string describing the input.\n- `required` (optional): A boolean indicating whether the input is required. Defaults to `false`.\n- `defaultValue` (optional): The default value for the input if it's not provided.\n- `trimWhitespace` (optional): A boolean indicating whether to trim whitespace from the input value. Defaults to `true`.\n- `validate` (optional): A validation function for the input value. It takes the input value as an argument and returns\n  either `true` if the value is valid or an error message string if it's not.\n\nAs well as maximum of one of the following mutually exclusive properties:\n\n- `type`: The data type of the input. Can be one of 'string', 'number', 'boolean', or 'string[]'.\n- `converter`: An object with `fromInput` and `toInput` methods for converting the input value from a string to a custom\n  type and vice versa.\n\n##### Outputs\n\nOutputs are defined in the `outputs` property of the `ActionOptions` object. Each output is represented by an object\nwith the following properties:\n\n- `description`: A string describing the output.\n- `type` (optional): The data type of the output. Can be one of 'string', 'number', 'boolean', or 'string[]'. Defaults\n  to 'string'\n- `initValue` (optional): The initial value for the output.\n- `converter` (optional): A conversion function for the output value. It takes the output value as an argument and\n  returns the converted value.\n\n##### Example\n\n```typescript\nexport class ExampleAction extends action({\n  inputs: {\n    a: { description: 'description a', required: true },\n    b: { description: 'description b', trimWhitespace: false, type: 'string[]' },\n    c: { description: 'description c', defaultValue: true, type: 'boolean' },\n    d: {\n      description: 'description d',\n      defaultValue: 123,\n      validate: (value?: number) => (!!value && value > 0 ? true : 'Value must be greater than 0'),\n    },\n    e: { description: 'description e', type: 'number', deprecationMessage: 'e is deprecated' },\n    f: {\n      description: 'description f',\n      required: true,\n      converter: {\n        fromInput: (value: string) => JSON.parse(value) as Repo,\n        toInput: (value: Repo) => JSON.stringify(value),\n      },\n    },\n    g: {\n      description: 'description g',\n      required: true,\n      converter: {\n        fromInput: (value: string) => new Date(value),\n        toInput: (value: Date) => value.toISOString(),\n      },\n    },\n  },\n  outputs: {\n    a: { description: 'description a' },\n    b: { description: 'description b', type: 'boolean' },\n    c: { description: 'description c', type: 'number' },\n    d: { description: 'description d', converter: (value: Repo) => JSON.stringify(value) },\n    e: { description: 'description e', type: 'number', initValue: 123 },\n  },\n}) {\n  /// rest of the action class\n}\n```\n\nAll input values are evaluated before the `main` method is called and stored in a readonly `inputs` property of the\naction class. The `inputs` property is an object with the same keys as the `inputs` property of the `ActionOptions`.\nAll validations for required inputs and input values are performed during this initialization and error messages are\nproduced if any of the validations fail. If an input marked as deprecated, but a value is supplied by the user, a \nwarning message will be produced.\n\nAll output values are stored in a readonly `outputs` property of the action class. The `outputs` property is an object\nwith the same keys as the `outputs` property of the `ActionOptions`. The `outputs` property is initialized with the\n`initValue` property of each output, if present.\nWhen a value is assigned to an output property, the value is converted to a string using the `converter` property of\nthe output, if present, and automatically send to back to the workflow as the actions output.\n\n```typescript\nexport class ExampleAction {\n  async main(): Promise<void> {\n    console.log(this.inputs);\n\n    this.outputs.a = this.inputs.a;\n    this.outputs.b = this.inputs.c;\n    this.outputs.c = this.inputs.d;\n    this.outputs.d = this.inputs.f;\n\n    console.log(JSON.stringify(this.outputs));\n  }\n}\n```\n\n## Fluent API\n\nAlternatively, you can use the `ActionBuilder` class to define your action. This class provides a fluent API for\ndefining the action properties, inputs, and outputs.\n\n### `actionBuilder(): ActionBuilder`\n\nThe `actionBuilder` function returns a new `ActionBuilder` instance.\n\n### `ActionBuilder`\n\nThe `ActionBuilder` class provides a fluent API for defining the action properties, inputs, and outputs.\n\n#### `name(name: string): ActionBuilder`\n\nSets the name of the action.\n\n#### `description(description: string): ActionBuilder`\n\nSets the description of the action.\n\n#### `author(author: string, email?: string): ActionBuilder`\n\nSets the author of the action.\nIf the `email` argument is provided, it will be added to the author string using the format `author <email>`.\n\n#### `branding(color: ActionYmlBranding['color'], icon: ActionYmlBranding['icon']): ActionBuilder`\n\nSets the branding properties of the action.\nThe `color` and `icon` arguments are restricted to the values defined in\n[GitHub branding guidelines](https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions#branding).\n\n#### `input(name: string, description: string, options?: ActionInputOptions): ActionBuilder`\n\nAdds an input to the action. The `options` argument recognizes the same properties as described in [Inputs](#inputs)\nexcept for `description`.\nIf the `options` argument is not provided, the input will be defined as an optional string input.\n\n#### `inputs(inputs: { [name]: ActionInputOptions }): ActionBuilder`\n\nAdds multiple inputs to the action. The `inputs` argument is an object with the input names as keys and the input\noptions as values. This structure is equivalent to the `inputs` property of the `ActionOptions` object as described in\n[Inputs](#inputs).\n\n#### `output(name: string, description: string, options?: ActionOutputOptions): ActionBuilder`\n\nAdds an output to the action. The `options` argument recognizes the same properties as described in [Outputs](#outputs)\nexcept for `description`.\nIf the `options` argument is not provided, the output will be of type string.\n\n#### `outputs(outputs: { [name]: ActionOutputOptions }): ActionBuilder`\n\nAdds multiple outputs to the action. The `outputs` argument is an object with the output names as keys and the output\noptions as values. This structure is equivalent to the `outputs` property of the `ActionOptions` object as described in\n[Outputs](#outputs).\n\n#### `build(): ActionConstructor`\n\nBuilds the action class and returns it.\n\n### Fluent Example\n\n```typescript\nimport { actionBuilder } from '@action-class/core';\n\nexport class ExampleAction extends actionBuilder()\n  .name('name')\n  .description('description')\n  .author('author')\n  .branding('orange', 'sunset')\n  .input('a', 'description a', { required: true })\n  .input('b', 'description b', { trimWhitespace: false, type: 'string[]' })\n  .input('c', 'description c')\n  .output('a', 'description a')\n  .output('b', 'description b', { type: 'boolean' })\n  .build() {\n  // Define your class properties and constructor here\n\n  async pre(): Promise<void> {\n    // Define the pre step logic here\n  }\n\n  async main(): Promise<void> {\n    // Define the main step logic here\n  }\n\n  async post(): Promise<void> {\n    // Define the post step logic here\n  }\n}\n```\n\n## Generating the `action.yml` with `generate-action-yml` tool\n\n`generate-action-ym`l is a utility script provided by the '@action-class/action-yml' package.\nIt helps you automatically generate an `action.yml` file from your action class definition.\nThis ensures that your action's metadata stays in sync with the actual code, reducing the chance of errors and\ninconsistencies.\n\nTo integrate the generate-action-yml tool into your action project, follow these steps:\n\n1. Add a script to your `package.json` file that calls the `generate-action-yml` tool.\n   You'll need to provide the action class name and, optionally, the paths to your `package.json` and main JavaScript\n   file.\n\n   In your `package.json`, add the following line under the scripts section:\n\n   ```json\n   {\n     \"scripts\": {\n       \"action-yml\": \"generate-action-yml ExampleAction\"\n     }\n   }\n   ```\n\n   Replace `ExampleAction` with the name of your action class.\n\n   In this example, the `generate-action-yml` tool will automatically locate your `package.json` and main JavaScript\n   file (using the `main` field in your `package.json`).\n   If you need to specify custom paths, you can do so using the `--package-json | -p` and `--action-js | -a` options:\n\n   ```json\n   {\n     \"scripts\": {\n       \"action-yml\": \"generate-action-yml -p <path-to-package-json> -a <path-to-action-js> ExampleAction\"\n     }\n   }\n   ```\n\n   Replace `<path-to-package-json>` with the path to your `package.json` file and `<path-to-action-js>` with the path to\n   your main JavaScript file relative to the location of the `package.json`.\n\n2. Run the script to generate the `action.yml` file:\n   ```bash\n   npm run action-yml\n   ```\n   This command will execute the `generate-action-yml` script and create an `action.yml` file in the directory of your\n   `package.json` file. The generated `action.yml` file will contain the metadata from your action class, such as the\n   name, description, inputs, and outputs.\n\nWith the `generate-action-yml` tool integrated into your action project, you can easily keep your `action.yml` file\nup-to-date with your action class definition. Make sure to run the script every time you make changes to your action\nclass to ensure that the `action.yml` file remains consistent with your code.\n\n## License\n\nThis library is published under the [MIT license](LICENSE).\n","readmeFilename":"README.md"}