Tweaks to tasks documentation for clarity and consistency (#522)

Author: benjie

src/index.ts

@@ -129,8 +129,8 @@ declare global {
 
       /**
        * A list of file extensions (in priority order) that Graphile Worker
-       * should attempt to import directly when loading task executors from the
-       * file system.
+       * should attempt to import as Node modules when loading task executors from
+       * the file system.
        *
        * @defaultValue `[".js", ".cjs", ".mjs"]`
        */

src/interfaces.ts

@@ -134,7 +134,7 @@ export type AddJobsFunction = <TSpecs extends readonly AddJobsJobSpec[]>(
 
 export interface Helpers {
   /**
-   * A Logger instance.
+   * A `Logger` instance.
    */
   logger: Logger;
 
@@ -145,30 +145,30 @@ export interface Helpers {
   withPgClient: WithPgClient;
 
   /**
-   * Adds a job into our queue.
+   * Adds a job into the Graphile Worker queue.
    */
   addJob: AddJobFunction;
 
   /**
-   * Adds multiple jobs into our queue.
+   * Adds multiple jobs into the Graphile Worker queue.
    */
   addJobs: AddJobsFunction;
 }
 
 export interface JobHelpers extends Helpers {
   /**
-   * A Logger instance, scoped to this job.
+   * A `Logger` instance, scoped to this job.
    */
   logger: Logger;
 
   /**
-   * The currently executing job.
+   * The whole, currently executing job.
    */
   job: Job;
 
   /**
-   * Get the queue name of the give queue ID (or the currently executing job if
-   * no queue id is specified).
+   * Get the queue name of the given queue ID (or of the currently executing job
+   * if no queue ID is specified).
    */
   getQueueName(queueId?: number | null): PromiseOrDirect<string | null>;
 
@@ -181,7 +181,8 @@ export interface JobHelpers extends Helpers {
   ): Promise<QueryResult<R>>;
 
   /**
-   * An AbortSignal that will be triggered when the job should exit.
+   * An `AbortSignal` that will be triggered when the job should exit. It is used,
+   * for example, for a graceful shutdown request.
    *
    * @experimental
    */

website/docs/config.md

@@ -177,6 +177,10 @@ Here are the options under the `worker` key as defined by
 }
 ```
 
+See the
+[Graphile Worker source](https://github.com/jcgsville/worker/blob/85c36ac4e684a3a782fc528dca95c8ba6177fa8a/src/config.ts#L13)
+for the default `worker` options set by the default Worker Preset.
+
 ### worker.concurrentJobs
 
 Type: `number | undefined`
@@ -211,7 +215,8 @@ resolved.)
 Type: `string[] | undefined`
 
 A list of file extensions (in priority order) that Graphile Worker should
-attempt to import directly when loading task executors from the file system.
+attempt to import as Node modules when loading task executors from the file
+system.
 
 ### worker.getQueueNameBatchDelay
 

website/docs/tasks.md

@@ -26,48 +26,32 @@ failure and the task is rescheduled using an exponential-backoff algorithm.
 
 Each task function is passed two arguments:
 
-- `payload` — the (JSON) payload you passed when calling
+- `payload` — the JSON payload you passed when calling
   `graphile_worker.add_job(...)` in the database, or `addJob(...)` via the JS
   API
-- `helpers` (see [`helpers`](#helpers) below) — an object containing:
-  - `logger` — a scoped [Logger](/docs/library/logger) instance, to aid
-    tracing/debugging
-  - `job` — the whole job (including `uuid`, `attempts`, etc) — you
-    shouldn't need this
-  - `getQueueName()` — get the name of the queue the job is in (may or may
-    not return a promise - recommend you always `await` it)
-  - `abortSignal` — could be an `AbortSignal`, or `undefined` if not
-    supported by this release of worker; if set, use this to abort your task
-    early on graceful shutdown (can be passed to a number of asynchronous
-    Node.js methods)
-  - `abortPromise` — if present, a promise that will reject when
-    `abortSignal` aborts; convenient for exiting your task when the abortSignal
-    fires: `Promise.race([abortPromise, doYourThing()])`
-  - `withPgClient` — a helper to use to get a database client
-  - `query(sql, values)` — a convenience wrapper for
-    `withPgClient(pgClient => pgClient.query(sql, values))`
-  - `addJob` — a helper to schedule a job
+- `helpers` see [`helpers`](#helpers) below
 
 :::warning Important
 
-Your jobs must wait for all asynchronous work to be completed before returning,
-otherwise we might think they were successful prematurely. Every promise that a
-task executor triggers must be `await`-ed; task executors _should not_ create
-“untethered” promises.
+Your task executors must wait for all asynchronous work for a job to be
+completed before returning, otherwise Graphile Worker might think they were
+successful prematurely. Every promise that a task executor triggers must be
+`await`-ed; task executors _should not_ create “untethered”
+promises.
 
 :::
 
 :::tip
 
-We automatically retry the job if it fails, so it's often sensible to split
-a large job into multiple smaller jobs, this also allows them to run in parallel
-resulting in faster execution. This is particularly important for tasks that are
-not idempotent (i.e. running them a second time will have extra side effects)
-— for example sending emails.
+Graphile Worker automatically retries the job if it fails, so it's often
+sensible to split a large job into multiple smaller jobs, this also allows them
+to run in parallel resulting in faster execution. This is particularly important
+for tasks that are not idempotent (i.e. running them a second time will have
+extra side effects) — for example sending emails.
 
 :::
 
-## Example task executors
+## Example JS task executors
 
 ```js title="tasks/task_1.js"
 module.exports = async (payload) => {
@@ -82,44 +66,39 @@ module.exports = async (payload, helpers) => {
 };
 ```
 
-## The `tasks/` folder
+## The task directory
 
-When you run `graphile-worker`, it will look in the current directory for a
-folder called `tasks`, and it will recursively look for files suitable to run as
-tasks. File names excluding the extension and folder names must only use
-alphanumeric characters, underscores and dashes (`/^[A-Za-z0-9_-]+$/`) to be
-recognized. Graphile Worker will then attempt to load the file as a task
-executor; the task identifier for this will be all the folders and the file name
-(excluding the extension) joined with `/` characters; e.g.
-`tasks/send_notification.js` would get the identifier `send_notification` and
-`tasks/users/emails/verify.js` would get the identifier `users/emails/verify`.
-How the file is loaded as a task executor will depend on the file in question
-and the plugins you have loaded.
+When you run Graphile Worker, it will look in the configured
+[`taskDirectory`](./config#workertaskdirectory) for files suitable to run as
+tasks.
 
-```
-current directory
-├── package.json
-├── node_modules
-└── tasks
-    ├── send_notification.js
-    ├── generate_pdf.js
-    └── users
-        ├── congratulate.js
-        └── emails
-            ├── verify.js
-            └── send_otp.js
-```
+File names excluding the extension and folder names must only use alphanumeric
+characters, underscores, and dashes (`/^[A-Za-z0-9_-]+$/`) to be recognized.
+
+Graphile Worker will then attempt to load the file as a task executor; the task
+identifier for this task will be all the folders and the file name (excluding
+the extension) joined with `/` characters:
+
+- `${taskDirectory}/send_notification.js` would get the task identifier
+  `send_notification`.
+- `${taskDirectory}/users/emails/verify.js` would get the task identifier
+  `users/emails/verify`.
+
+How the file is loaded as a task executor will depend on the specific file and
+the plugins you have loaded.
 
 ## Loading JavaScript files
 
-Out of the box, Graphile Worker will load `.js`, `.cjs` and `.mjs` files using
-the `import()` function. If the file is a CommonJS module then Worker will
-expect `module.exports` to be the task executor function; if the file is an
-ECMAScript module (ESM) then Worker will expect the default export to be the
-task executor function.
+With the default preset, Graphile Worker will load `.js`, `.cjs` and `.mjs`
+files as task executors using the `import()` function. If the file is a CommonJS
+module, then Worker will expect `module.exports` to be the task executor
+function; if the file is an ECMAScript module (ESM) then Worker will expect the
+default export to be the task executor function.
 
-Via plugins, support for other ways of loading task files can be added; look at
-the source code of `LoadTaskFromJsPlugin.ts` for inspiration.
+You can add support for other ways of loading task executors via plugins; look
+at the source code of
+[`LoadTaskFromJsPlugin.ts`](https://github.com/graphile/worker/blob/main/src/plugins/LoadTaskFromJsPlugin.ts)
+for inspiration.
 
 ### Loading TypeScript files
 
@@ -130,19 +109,19 @@ TypeScript files to JS and then have Graphile Worker load the JS files.
 
 :::
 
-To load TypeScript files directly as tasks (without precompilation), one way is
-to:
+To load TypeScript files directly as task executors (without precompilation),
+one way is to do the following:
 
-1. install `ts-node`,
-2. add `".ts"` to the `worker.fileExtensions` list in your `graphile.config.ts`,
-3. run Graphile Worker with the environmental variable
+1. Install `ts-node`.
+2. Add `".ts"` to the `worker.fileExtensions` list in your preset.
+3. Run Graphile Worker with the environment variable
    `NODE_OPTIONS="--loader ts-node/esm"` set.
 
 ```ts title="Example graphile.config.ts"
-import type { GraphileConfig } from "graphile-config";
-import type {} from "graphile-worker";
+import { WorkerPreset } from "graphile-worker";
 
 const preset: GraphileConfig.Preset = {
+  extends: [WorkerPreset],
   worker: {
     connectionString: process.env.DATABASE_URL,
     concurrentJobs: 5,
@@ -167,16 +146,21 @@ This feature is currently experimental.
 :::
 
 If you're running on Linux or Unix (including macOS) then if Graphile Worker
-finds an executable file inside of `tasks/` it will create a task executor for
-it. When a task of this kind is found, Graphile Worker will execute the file
-setting the relevant environmental variables and passing in the payload
+finds an executable file inside of the `taskDirectory` it will create a task
+executor for it. When a task of this kind is found, Graphile Worker will execute
+the file with the relevant environment variables and pass in the payload
 according to the encoding. If the executable exits with code `0` then Graphile
-Worker will see this as success, all other exit codes are seen as failure.
+Worker will see this as success. All other exit codes are seen as failure.
 
-### Environmental variables
+This feature is added via the
+[LoadTaskFromExecutableFilePlugin plugin](https://github.com/graphile/worker/blob/main/src/plugins/LoadTaskFromExecutableFilePlugin.ts)
+in the default
+[Worker Preset](https://github.com/graphile/worker/blob/main/src/preset.ts).
+
+### Environment variables
 
 - `GRAPHILE_WORKER_PAYLOAD_FORMAT` — the encoding that Graphile Worker
-  uses to pass the payload to the binary. Currently this will be the string
+  used to pass the payload to the binary. Currently this will be the string
   `json`, but you should check this before processing the payload in case the
   format changes.
 - `GRAPHILE_WORKER_TASK_IDENTIFIER` — the identifier for the task this
@@ -198,40 +182,69 @@ Worker will see this as success, all other exit codes are seen as failure.
 
 In the JSON payload format, your binary will be fed via stdin
 `JSON.stringify({payload})`; for example, if you did
-`addJob('myScript', {mol: 42})` then your `myScript` task would be sent
+`addJob('my_script', {mol: 42})` then your `my_script` task would be sent
 `{"payload":{"mol":42}}` via stdin.
 
 ## Handling batch jobs
 
-If the payload is an array, then _optionally_ your task may choose to return an
-array of the same length, the entries in which are promises. Should any of these
-promises reject, then the job will be re-enqueued, but the payload will be
-overwritten to only contain the entries associated with the rejected promises
-— i.e. the successful entries will be removed.
+If the payload is an array, then _optionally_ your task executor may choose to
+return an array of the same length, the entries in which are promises. Should
+any of these promises reject, then the job will be re-enqueued, but the payload
+will be overwritten to only contain the entries associated with the rejected
+promises — i.e. the successful entries will be removed.
 
 ## `helpers`
 
+### `helpers.abortPromise`
+
+**Experimental**
+
+This is a promise that will reject when [`abortSignal`](#helpersabortsignal)
+aborts. This makes it convenient for exiting your task when the abortSignal
+fires: `Promise.race([abortPromise, doYourAsyncThing()])`.
+
+### `helpers.abortSignal`
+
+**Experimental**
+
+This is a `AbortSignal` that will be triggered when the job should exit early.
+It is used, for example, for a graceful shutdown request. `AbortSignal`s can be
+passed to a number of asynchronous Node.js methods like
+[`http.request()`](https://nodejs.org/api/http.html#httprequesturl-options-callback).
+
+### `helpers.addJob()`
+
+See [`addJob`](/library/add-job.md).
+
+### `helpers.addJobs()`
+
+See [`addJobs`](/library/add-job.md#add-jobs).
+
+### `helpers.getQueueName()`
+
+Get the queue name of the given queue ID (or of the currently executing job if
+no queue ID is specified). This function may or may not return a promise. We
+recommend that you always `await` it.
+
+### `helpers.job`
+
+The whole, currently executing job, including `uuid`, `attempts`, etc.
+
 ### `helpers.logger`
 
-So that you may redirect logs to your preferred logging provider, we have
-enabled you to supply your own logging provider. Overriding this is currently
-only available in library mode (see [Logger](/library/logger.md)). We then wrap
-this logging provider with a helper class to ease debugging; the helper class
-has the following methods:
+A logger instance scoped to this job. See [Logger](./library/logger)
 
-- `error(message, meta?)`: for logging errors, similar to `console.error`
-- `warn(message, meta?)`: for logging warnings, similar to `console.warn`
-- `info(message, meta?)`: for logging informational messages, similar to
-  `console.info`
-- `debug(message, meta?)`: to aid with debugging, similar to `console.log`
-- `scope(additionalScope)`: returns a new `Logger` instance with additional
-  scope information
+### `helpers.query()`
+
+This is a convenience wrapper for
+`withPgClient(pgClient => pgClient.query(sql, values))`. See
+[`withPgClient()`](#helperswithpgclient)
 
 ### `helpers.withPgClient()`
 
-`withPgClient` gets a `pgClient` from the pool, calls
-`await callback(pgClient)`, and finally releases the client and returns the
-result of `callback`. This workflow can make testing your tasks easier.
+`withPgClient` gets a `pgClient` from the pool that Graphile Worker uses. It
+calls `await callback(pgClient)`, and finally releases the client and returns
+the result of `callback`. This workflow can make testing your tasks easier.
 
 Example:
 
@@ -249,19 +262,3 @@ keeping transactions open may decrease Graphile Worker's performance due to
 increasing contention over the pool of database clients.
 
 :::
-
-### `helpers.addJob()`
-
-```ts
-await helpers.addJob(identifier, payload, options);
-```
-
-See [`addJob`](/library/add-job.md).
-
-### `helpers.addJobs()`
-
-```ts
-await helpers.addJobs(specs, preserveRunAt);
-```
-
-See [`addJobs`](/library/add-job.md#add-jobs).