Update options script to reliably fetch options (#521)

Author: benjie

package.json

@@ -6,7 +6,7 @@
   "main": "dist/index.js",
   "scripts": {
     "build:sql": "node scripts/buildSqlModule.mjs",
-    "website:update": "node scripts/options.mjs",
+    "website:update": "yarn prepack && node scripts/options.mjs",
     "prepack": "rm -Rf dist && npm run build:sql && tsc && chmod +x dist/cli.js",
     "watch": "mkdir -p dist && touch dist/cli.js && chmod +x dist/cli.js && npm run build:sql && tsc --watch",
     "lint": "yarn prettier:check && eslint --ext .js,.jsx,.ts,.tsx,.graphql .",

scripts/options.mjs

@@ -1,20 +1,48 @@
 #!/usr/bin/env zx
+// @ts-check
 import "zx/globals";
+
 import * as fs from "fs/promises";
 
-// Create a symlink so `import "graphile-worker"` works
-await $`ln -s .. node_modules/graphile-worker || true`;
+await $`yarn link`;
+
+// Create a temporary instance so we can read the options
+const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "gwdu-"));
+const prev = process.cwd();
+cd(tmp);
+await $`yarn link graphile-worker`;
+await $`yarn add typescript graphile`;
+await fs.writeFile(
+  `graphile.config.ts`,
+  `\
+import type {} from "graphile-worker";
+
+const preset: GraphileConfig.Preset = {
+  worker: {},
+};
+
+export default preset;
+`,
+);
 
 // Get the markdown output for options
 const output = await $`graphile config options`;
 
+// Go back and destroy our tempdir
+cd(prev);
+// Remove our temporary directory
+await fs.rm(tmp, { recursive: true, force: true });
+
 // Crop it down to only include the stuff under the worker header
 const SEARCH = "\n## worker\n";
 const i = output.stdout.indexOf(SEARCH);
 if (i < 0) {
   throw new Error("Worker heading not found!");
 }
-const optionsMd = output.stdout.slice(i + SEARCH.length).trim();
+const optionsMd = output.stdout
+  .slice(i + SEARCH.length)
+  .trim()
+  .replace(/\(https:\/\/worker\.graphile\.org\//g, "(/");
 
 // Load the config.md doc file and replace the part between the comment tags
 const configMd = await fs.readFile("website/docs/config.md", "utf8");

src/index.ts

@@ -58,13 +58,19 @@ declare global {
   namespace GraphileConfig {
     interface WorkerOptions {
       /**
-       * Database connection string.
+       * Database [connection string](https://worker.graphile.org/docs/connection-string).
        *
        * @defaultValue `process.env.DATABASE_URL`
        */
       connectionString?: string;
       /**
-       * Maximum number of concurrent connections to Postgres
+       * Maximum number of concurrent connections to Postgres; must be at least
+       * `2`. This number can be lower than `concurrentJobs`, however a low
+       * pool size may cause issues - if all your pool clients are busy then no
+       * jobs can be started or released. If in doubt, we recommend setting it
+       * to `10` or `concurrentJobs + 2`, whichever is larger. (Note: if your
+       * task executors use this pool, then an even larger value may be needed
+       * for optimum performance, depending on the shape of your logic.)
        *
        * @defaultValue `10`
        */
@@ -153,6 +159,11 @@ declare global {
        */
       logger?: Logger;
 
+      /**
+       * A Node.js `EventEmitter` that exposes certain events within the runner
+       * (see
+       * [`WorkerEvents`](https://worker.graphile.org/docs/worker-events)).
+       */
       events?: WorkerEvents;
     }
     interface Preset {

website/docs/config.md

@@ -80,6 +80,7 @@ Here are the options under the `worker` key as defined by
   crontabFile?: string;
   events?: WorkerEvents;
   fileExtensions?: string[];
+  getQueueNameBatchDelay?: number;
   gracefulShutdownAbortTimeout?: number;
   logger?: Logger<{}>;
   maxPoolSize?: number;
@@ -103,7 +104,7 @@ Number of jobs to run concurrently.
 
 Type: `string | undefined`
 
-Database [connection string](./connection-string.md).
+Database [connection string](/docs/connection-string).
 
 ### worker.crontabFile
 
@@ -126,6 +127,16 @@ A list of file extensions (in priority order) that Graphile Worker should
 attempt to import directly when loading tasks. Defaults to
 `[".js", ".cjs", ".mjs"]`.
 
+### worker.getQueueNameBatchDelay
+
+Type: `number | undefined`
+
+**Experimental**
+
+When getting a queue name in a job, we batch calls for efficiency. By default we
+do this over a 50ms window; increase this for greater efficiency, reduce this to
+reduce the latency for getting an individual queue name.
+
 ### worker.gracefulShutdownAbortTimeout
 
 Type: `number | undefined`