Expose async-function argument type

We are exposing the async-function argument type for jsDoc
type declaration support. This means that we now could do:
"npm i -D @types/github-script@github:actions/github-script"
and the add:
"@param {import('@types/github-script').AsyncFunctionArguments}
AsyncFunctionArguments".

This could obviously be done in other ways too, like using
"@typed-actions/github-script" instead. But it seems better
to use the actual source repository instead of a third-party
library to import the type declaration.

Author: viktorlott

README.md

@@ -419,6 +419,26 @@ jobs:
             await printStuff()
 ```
 
+### Use scripts with jsDoc support
+
+If you want type support for your scripts, you could use the the command below to install the
+`github-script` type declaration.
+```sh
+$ npm i -D @types/github-script@github:actions/github-script
+```
+
+And then add the `jsDoc` declaration to you script like this:
+```js
+// @ts-check
+/** @param {import('@types/github-script').AsyncFunctionArguments} AsyncFunctionArguments */
+export default async ({ core, context }) => {
+  core.debug("Running something at the moment");
+  return context.actor;
+};
+```
+For an alternative setup, please read (alternative-setup)[./docs/alternative-setup.md].
+
+
 ### Use env as input
 
 You can set env vars to use them in your script:

docs/alternative-setup.md

@@ -0,0 +1,153 @@
+## Alternative setup
+
+### Example repository structure
+In this example we're using the repo structure below, but you are free
+to structure it how ever you like. 
+```
+root # Your repository
+ ├── .github
+ │   ├── ...
+ │   └── workflows
+ │       ├── ...
+ │       └── ci-workflow.yml
+ ├── ...
+ ├── actions
+ │  ├── action.yml    (optional)
+ │  └── ci-test.js
+ ├── ...
+ └── package.json
+```
+
+### 1. Install the github-script type
+```sh
+$ npm i -D @types/github-script@github:actions/github-script
+```
+
+
+### 2. Create `ci-test.js` file
+
+```js
+// @ts-check
+/** @param {import('@types/github-script').AsyncFunctionArguments} AsyncFunctionArguments */
+export default async ({ core, context }) => {
+  core.debug("Running something at the moment");
+  return context.actor;
+};
+```
+
+### 3. Create `ci-workflow.yml` file
+```yml
+on: push
+
+permissions:
+  pull-requests: read
+  contents: read
+
+jobs:
+  example:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 16
+          
+      - run: npm ci
+      - uses: actions/github-script@v6
+          with:
+            github-token: ${{ secrets.GITHUB_TOKEN }}
+            result-encoding: string
+            script: |
+              const { default: script } = await import('${{ github.workspace }}/actions/ci-test.js');
+              return await script({ github, context, core, exec, glob, io, fetch, __original_require__ });
+```
+
+
+## Cleaner setup (Optional)
+
+Note that the `ci-workflow.yml` example above can be kind of tedious once you add more of them. So
+to address this, one could instead use `composite` actions. 
+
+### The `action.yml` file
+```yml
+name: Typed GitHub Script
+author: GitHub
+description: Run simple scripts using the GitHub client
+branding:
+  color: blue
+  icon: code
+inputs:
+  script:
+    description: The path to script (e.g actions/ci-test.js)
+    required: true
+  github-token:
+    description: The GitHub token used to create an authenticated client
+    default: ${{ github.token }}
+    required: false
+  debug:
+    description: Whether to tell the GitHub client to log details of its requests. true or false. Default is to run in debug mode when the GitHub Actions step debug logging is turned on.
+    default: ${{ runner.debug == '1' }}
+  user-agent:
+    description: An optional user-agent string
+    default: actions/github-script
+  previews:
+    description: A comma-separated list of API previews to accept
+  result-encoding:
+    description: Either "string" or "json" (default "json")—how the result will be encoded
+    default: json
+  retries:
+    description: The number of times to retry a request
+    default: "0"
+  retry-exempt-status-codes:
+    description: A comma separated list of status codes that will NOT be retried e.g. "400,500". No effect unless `retries` is set
+    default: 400,401,403,404,422 # from https://github.com/octokit/plugin-retry.js/blob/9a2443746c350b3beedec35cf26e197ea318a261/src/index.ts#L14
+
+outputs:
+  result:
+    description: The return value of the script, stringified with `JSON.stringify`
+    value: ${{ steps.github-script-result.outputs.result }}
+
+runs:
+  using: "composite"
+  steps:
+    - uses: actions/github-script@v6
+      id: github-script-result
+      with:
+        github-token: ${{ inputs.github-token }}
+        result-encoding: ${{ inputs.result-encoding }}
+        debug: ${{ inputs.debug }}
+        user-agent: ${{ inputs.script }}
+        previews: ${{ inputs.previews }}
+        retries: ${{ inputs.retries }}
+        retry-exempt-status-codes: ${{ inputs.retry-exempt-status-codes }}
+        script: |
+          const { default: script } = await import('${{ github.workspace }}/${{ inputs.script }}');
+          return await script({ github, context, core, exec, glob, io, fetch, __original_require__ });
+```
+
+
+### The `ci-workflow.yml` file
+```yml
+on: push
+
+permissions:
+  pull-requests: read
+  contents: read
+
+jobs:
+  example:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 16
+          
+      - run: npm ci
+      - uses: ./actions
+          with:
+            github-token: ${{ secrets.GITHUB_TOKEN }}
+            result-encoding: string
+            script: actions/ci-test.js
+```
+

package.json

@@ -5,9 +5,11 @@
   "author": "GitHub",
   "license": "MIT",
   "main": "dist/index.js",
+  "types": "types/async-function.d.ts",
   "private": true,
   "scripts": {
-    "build": "ncc build src/main.ts",
+    "build": "npm run build:types && ncc build src/main.ts",
+    "build:types": "tsc src/async-function.ts -t es5 --declaration --allowJs --emitDeclarationOnly --outDir types",
     "format:check": "prettier --check src __test__",
     "format:write": "prettier --write src __test__",
     "lint": "eslint src __test__",

src/async-function.ts

@@ -8,7 +8,7 @@ import fetch from 'node-fetch'
 
 const AsyncFunction = Object.getPrototypeOf(async () => null).constructor
 
-type AsyncFunctionArguments = {
+export declare type AsyncFunctionArguments = {
   context: Context
   core: typeof core
   github: InstanceType<typeof GitHub>

types/async-function.d.ts

@@ -0,0 +1,20 @@
+/// <reference types="node" />
+import * as core from '@actions/core';
+import * as exec from '@actions/exec';
+import { Context } from '@actions/github/lib/context';
+import { GitHub } from '@actions/github/lib/utils';
+import * as glob from '@actions/glob';
+import * as io from '@actions/io';
+import fetch from 'node-fetch';
+export declare type AsyncFunctionArguments = {
+    context: Context;
+    core: typeof core;
+    github: InstanceType<typeof GitHub>;
+    exec: typeof exec;
+    glob: typeof glob;
+    io: typeof io;
+    fetch: typeof fetch;
+    require: NodeRequire;
+    __original_require__: NodeRequire;
+};
+export declare function callAsyncFunction<T>(args: AsyncFunctionArguments, source: string): Promise<T>;