Switch to ESM and add native TypeScript task loading (Node 22.18+), update tests and docs

RELEASE_NOTES.md

@@ -21,6 +21,23 @@ Read more:
 
 ## v0.18.0
 
+### Breaking changes
+
+- Graphile Worker is now published as an ESM package (`"type": "module"`). Use
+  `import` syntax from ESM consumers. Since Graphile Worker requires Node
+  22.18+, CommonJS consumers can continue to load Worker with `require()` via
+  Node's `require(esm)` support.
+- Example `.js` task and configuration files now use ESM syntax. In projects
+  with `"type": "module"`, `.js` task files must use `export default`; rename
+  CommonJS tasks/configuration to `.cjs` if you need to keep using
+  `module.exports`.
+- TypeScript task files with `.ts` and `.mts` extensions are now recognized by
+  default and loaded through Node's native type stripping. Only erasable,
+  verbatim TypeScript syntax is supported without a custom loader or
+  precompilation.
+
+### Changes
+
 - Since Node 20 is EOL, Node 22 is now the minimum supported version, per our
   [requirements documentation](https://worker.graphile.org/docs/requirements).
 - `Runner` gains `[Symbol.asyncDispose]()` method, so you can

__tests__/batchJobs.test.ts

@@ -1,6 +1,6 @@
 import { jest } from "@jest/globals";
 
-import { Task, TaskList, WorkerSharedOptions } from "../src/interfaces.ts";
+import type { Task, TaskList, WorkerSharedOptions } from "../src/interfaces.ts";
 import { runTaskListOnce } from "../src/main.ts";
 import {
   ESCAPED_GRAPHILE_WORKER_SCHEMA,

__tests__/crontab.test.ts

@@ -1,5 +1,5 @@
 import { parseCronItem, parseCrontab } from "../src/crontab.ts";
-import { CronItemOptions, ParsedCronMatch } from "../src/index.ts";
+import type { CronItemOptions, ParsedCronMatch } from "../src/index.ts";
 
 // 0...59
 const ALL_MINUTES = Array.from(Array(60).keys());

__tests__/events.test.ts

@@ -2,9 +2,11 @@ import { jest } from "@jest/globals";
 import { EventEmitter } from "events";
 import type { Pool } from "pg";
 
-import deferred, { Deferred } from "../src/deferred.ts";
-import { run, Runner } from "../src/index.ts";
-import { Task, TaskList, WorkerSharedOptions } from "../src/interfaces.ts";
+import type { Deferred } from "../src/deferred.ts";
+import deferred from "../src/deferred.ts";
+import type { Runner } from "../src/index.ts";
+import { run } from "../src/index.ts";
+import type { Task, TaskList, WorkerSharedOptions } from "../src/interfaces.ts";
 import {
   ESCAPED_GRAPHILE_WORKER_SCHEMA,
   expectJobCount,

__tests__/fixtures-esm/tasks/module-typescript.mts

@@ -0,0 +1,3 @@
+export default function moduleTypescriptTask() {
+  return "some module typescript";
+}

__tests__/fixtures-esm/tasks/typescript.ts

@@ -0,0 +1,6 @@
+import type { JobHelpers } from "../../../src/interfaces.ts";
+
+export default function typescriptTask(_payload: unknown, helpers: JobHelpers) {
+  helpers.logger.debug("typescript task");
+  return "some typescript";
+}

__tests__/forbiddenFlags.test.ts

@@ -1,12 +1,7 @@
 import { jest } from "@jest/globals";
 
-import {
-  makeWorkerUtils,
-  runTaskListOnce,
-  Task,
-  TaskList,
-  WorkerSharedOptions,
-} from "../src/index.ts";
+import type { Task, TaskList, WorkerSharedOptions } from "../src/index.ts";
+import { makeWorkerUtils, runTaskListOnce } from "../src/index.ts";
 import { getJobs, reset, withPgClient, withPgPool } from "./helpers.ts";
 
 const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));

__tests__/getTasks.test.ts

@@ -1,6 +1,6 @@
 import { getTasks } from "../src/getTasks.ts";
 import { makeJobHelpers, makeWithPgClientFromClient } from "../src/helpers.ts";
-import {
+import type {
   CompiledSharedOptions,
   WatchedTaskList,
   WorkerSharedOptions,
@@ -48,6 +48,12 @@ describe("commonjs", () => {
       expect(
         await tasks.wouldyoulike_default!(helpers.job.payload, helpers),
       ).toEqual("some more sausages");
+      expect(await tasks.typescript!(helpers.job.payload, helpers)).toEqual(
+        "some typescript",
+      );
+      expect(
+        await tasks["module-typescript"]!(helpers.job.payload, helpers),
+      ).toEqual("some module typescript");
       expect(
         await tasks.wouldyoulike_ts!(helpers.job.payload, helpers),
       ).toEqual("some TS sausages");
@@ -191,6 +197,8 @@ describe("esm", () => {
       expect(tasks).toBeTruthy();
       expect(Object.keys(tasks).sort()).toMatchInlineSnapshot(`
         [
+          "module-typescript",
+          "typescript",
           "wouldyoulike",
           "wouldyoulike_default",
         ]
@@ -212,6 +220,12 @@ describe("esm", () => {
       expect(
         await tasks.wouldyoulike_default!(helpers.job.payload, helpers),
       ).toEqual("some more sausages");
+      expect(await tasks.typescript!(helpers.job.payload, helpers)).toEqual(
+        "some typescript",
+      );
+      expect(
+        await tasks["module-typescript"]!(helpers.job.payload, helpers),
+      ).toEqual("some module typescript");
       await release();
     }));
 

__tests__/helpers.ts

@@ -8,7 +8,7 @@ import {
 import pg from "pg";
 
 import defer from "../src/deferred.ts";
-import {
+import type {
   DbJob,
   Job,
   KnownCrontab,

__tests__/jobsView.test.ts

@@ -1,4 +1,5 @@
-import { Job, makeWorkerUtils, WorkerSharedOptions } from "../src/index.ts";
+import type { Job, WorkerSharedOptions } from "../src/index.ts";
+import { makeWorkerUtils } from "../src/index.ts";
 import {
   ESCAPED_GRAPHILE_WORKER_SCHEMA,
   makeSelectionOfJobs,

__tests__/main.runTaskList.test.ts

@@ -2,8 +2,14 @@
 import { jest } from "@jest/globals";
 import type { Pool } from "pg";
 
-import deferred, { Deferred } from "../src/deferred.ts";
-import { Job, Task, TaskList, WorkerSharedOptions } from "../src/interfaces.ts";
+import type { Deferred } from "../src/deferred.ts";
+import deferred from "../src/deferred.ts";
+import type {
+  Job,
+  Task,
+  TaskList,
+  WorkerSharedOptions,
+} from "../src/interfaces.ts";
 import { runTaskList } from "../src/main.ts";
 import {
   ESCAPED_GRAPHILE_WORKER_SCHEMA,

__tests__/main.runTaskListOnce.test.ts

@@ -1,7 +1,8 @@
 import { jest } from "@jest/globals";
 
-import defer, { Deferred } from "../src/deferred.ts";
-import {
+import type { Deferred } from "../src/deferred.ts";
+import defer from "../src/deferred.ts";
+import type {
   DbJob,
   Task,
   TaskList,

__tests__/migrate.test.ts

@@ -1,7 +1,7 @@
 import type { PoolClient } from "pg";
 
 import { migrations } from "../src/generated/sql.ts";
-import { WorkerSharedOptions } from "../src/index.ts";
+import type { WorkerSharedOptions } from "../src/index.ts";
 import { processSharedOptions } from "../src/lib.ts";
 import { installSchema, migrate, runMigration } from "../src/migrate.ts";
 import {

__tests__/nodeTime.test.ts

@@ -1,7 +1,7 @@
 import { jest } from "@jest/globals";
 
 import { run, runTaskListOnce } from "../src/index.ts";
-import { WorkerSharedOptions } from "../src/interfaces.ts";
+import type { WorkerSharedOptions } from "../src/interfaces.ts";
 import {
   ESCAPED_GRAPHILE_WORKER_SCHEMA,
   EventMonitor,

__tests__/resetLockedAt.test.ts

@@ -1,7 +1,7 @@
 import { jest } from "@jest/globals";
 import { EventEmitter } from "events";
 
-import {
+import type {
   Task,
   TaskList,
   WorkerEvents,

__tests__/runner.helpers.getTaskName.test.ts

@@ -1,7 +1,7 @@
 import type { Pool, PoolClient } from "pg";
 import pg from "pg";
 
-import { DbJobSpec, RunnerOptions } from "../src/interfaces.ts";
+import type { DbJobSpec, RunnerOptions } from "../src/interfaces.ts";
 import { run } from "../src/runner.ts";
 import {
   databaseDetails,

__tests__/runner.runOnce.test.ts

@@ -1,7 +1,7 @@
 import pg from "pg";
 
 import { makeWorkerPresetWorkerOptions } from "../src/config.ts";
-import { Job, RunnerOptions, WorkerUtils } from "../src/interfaces.ts";
+import type { Job, RunnerOptions, WorkerUtils } from "../src/interfaces.ts";
 import { coerceError } from "../src/lib.ts";
 import { _allWorkerPools } from "../src/main.ts";
 import { WorkerPreset } from "../src/preset.ts";

__tests__/workerUtils.addJob.test.ts

@@ -1,13 +1,7 @@
 import { jest } from "@jest/globals";
 
-import {
-  addJobAdhoc,
-  makeWorkerUtils,
-  runTaskListOnce,
-  Task,
-  WorkerSharedOptions,
-  WorkerUtils,
-} from "../src/index.ts";
+import type { Task, WorkerSharedOptions, WorkerUtils } from "../src/index.ts";
+import { addJobAdhoc, makeWorkerUtils, runTaskListOnce } from "../src/index.ts";
 import {
   getJobs,
   HOUR,

__tests__/workerUtils.addJobs.test.ts

@@ -1,14 +1,12 @@
 import { jest } from "@jest/globals";
 
-import type { Job } from "../src/index.ts";
-import {
-  addJobAdhoc,
-  makeWorkerUtils,
-  runTaskListOnce,
+import type {
+  Job,
   Task,
   WorkerSharedOptions,
   WorkerUtils,
 } from "../src/index.ts";
+import { addJobAdhoc, makeWorkerUtils, runTaskListOnce } from "../src/index.ts";
 import {
   getJobs,
   HOUR,

__tests__/workerUtils.cleanup.test.ts

@@ -1,10 +1,10 @@
-import {
+import type {
   DbJob,
   Job,
-  makeWorkerUtils,
   WorkerSharedOptions,
   WorkerUtils,
 } from "../src/index.ts";
+import { makeWorkerUtils } from "../src/index.ts";
 import {
   ESCAPED_GRAPHILE_WORKER_SCHEMA,
   makeSelectionOfJobs,

__tests__/workerUtils.completeJobs.test.ts

@@ -1,8 +1,5 @@
-import {
-  makeWorkerUtils,
-  WorkerSharedOptions,
-  WorkerUtils,
-} from "../src/index.ts";
+import type { WorkerSharedOptions, WorkerUtils } from "../src/index.ts";
+import { makeWorkerUtils } from "../src/index.ts";
 import {
   getJobs,
   makeSelectionOfJobs,

__tests__/workerUtils.forceUnlockWorkers.test.ts

@@ -1,9 +1,5 @@
-import {
-  Job,
-  makeWorkerUtils,
-  WorkerSharedOptions,
-  WorkerUtils,
-} from "../src/index.ts";
+import type { Job, WorkerSharedOptions, WorkerUtils } from "../src/index.ts";
+import { makeWorkerUtils } from "../src/index.ts";
 import {
   ESCAPED_GRAPHILE_WORKER_SCHEMA,
   getJobs,

__tests__/workerUtils.permanentlyFailJobs.test.ts

@@ -1,8 +1,5 @@
-import {
-  makeWorkerUtils,
-  WorkerSharedOptions,
-  WorkerUtils,
-} from "../src/index.ts";
+import type { WorkerSharedOptions, WorkerUtils } from "../src/index.ts";
+import { makeWorkerUtils } from "../src/index.ts";
 import {
   getJobs,
   makeSelectionOfJobs,

__tests__/workerUtils.rescheduleJobs.test.ts

@@ -1,8 +1,5 @@
-import {
-  makeWorkerUtils,
-  WorkerSharedOptions,
-  WorkerUtils,
-} from "../src/index.ts";
+import type { WorkerSharedOptions, WorkerUtils } from "../src/index.ts";
+import { makeWorkerUtils } from "../src/index.ts";
 import {
   getJobs,
   makeSelectionOfJobs,

examples/readme/events.js

@@ -1,6 +1,5 @@
-const { run, addJobAdhoc } = require(
-  /* "graphile-worker" */ "../../dist/index.js",
-);
+/* eslint-disable import-x/no-unresolved */
+import { addJobAdhoc, run } from /* "graphile-worker" */ "../../dist/index.js";
 
 async function main() {
   // Run a worker to execute jobs:

examples/readme/tasks/task_2.js

@@ -1,4 +1,4 @@
-module.exports = async (payload, helpers) => {
+export default async function task2(payload, helpers) {
   // async is optional, but best practice
   helpers.logger.debug(`Received ${JSON.stringify(payload)}`);
-};
+}

examples/worker-bullmq-exporter/tasks/bullmq-exporter.js

@@ -1,4 +1,5 @@
-const { Queue } = require("bullmq");
+/* eslint-disable import-x/no-unresolved */
+import { Queue } from "bullmq";
 
 const defaultQueueName = "database-events";
 const queueName = process.env.QUEUE_NAME || defaultQueueName;

examples/worker-cloud-tasks-exporter/README.md

@@ -47,7 +47,7 @@ To create tasks in Cloud Tasks
 
 ```js
 // tasks/cloud-tasks-exporter.js
-const { CloudTasksClient } = require("@google-cloud/tasks");
+import { CloudTasksClient } from "@google-cloud/tasks";
 
 const client = new CloudTasksClient();
 
@@ -110,7 +110,7 @@ To run Graphile Worker task
 
 ```js
 // tasks/cloud-tasks-exporter.js
-module.exports = async (payload, { logger }) => {
+export default async function task(payload, { logger }) {
   logger.info(
     `Delegating task to Cloud Tasks with payload ${JSON.stringify(payload)}`,
   );
@@ -122,7 +122,7 @@ module.exports = async (payload, { logger }) => {
   });
 
   logger.info("Done!");
-};
+}
 ```
 
 ## Run the worker and add a job

examples/worker-cloud-tasks-exporter/tasks/cloud-tasks-exporter.js

@@ -1,4 +1,5 @@
-const { CloudTasksClient } = require("@google-cloud/tasks");
+/* eslint-disable import-x/no-unresolved */
+import { CloudTasksClient } from "@google-cloud/tasks";
 
 const client = new CloudTasksClient();
 
@@ -56,7 +57,7 @@ async function createTask({
 }
 
 // Graphile Worker Task
-module.exports = async (payload, { logger }) => {
+export default async function cloudTasksExporter(payload, { logger }) {
   logger.info(
     `Delegating task to Cloud Tasks with payload ${JSON.stringify(payload)}`,
   );
@@ -68,4 +69,4 @@ module.exports = async (payload, { logger }) => {
   });
 
   logger.info("Done!");
-};
+}

examples/worker-faktory-exporter/README.md

@@ -22,9 +22,9 @@ job from a queue.
 
 ```JS
 // tasks/faktory-export.js
-const faktory = require("faktory-worker");
+import faktory from "faktory-worker";
 
-module.exports = async (payload, helpers) => {
+export default async function task(payload, helpers) {
   const { param } = payload;
   const { logger } = helpers;