`Invalid job class` with Bun

[lauritzsh]

I saw #72 and it seems Piscina is working now with Bun oven-sh/bun#19924 (comment) so I wanted to give it a shot, but I'm running into another issue which might be related or not.

I copied the Hello, World example

import { Job } from "sidequest";

export class HelloJob extends Job {
	run(name: string) {
		const msg = `hello ${name}`;
		console.log(msg);
		return msg;
	}
}

I have a simple setup for running it

import { Sidequest } from "sidequest";
import { HelloJob } from "@/jobs/HelloJob";

Sidequest.start({
	backend: {
		driver: "@sidequest/postgres-backend",
		config: "postgresql://postgres:postgres@localhost:6432/postgres",
	},
});

Sidequest.build(HelloJob).enqueue("Hello");

but I just get

❯ bun src/scripts/test.ts
[info] [2026-01-11 11:24:44] [Sidequest] [Engine] : Starting Sidequest using backend @sidequest/postgres-backend
[info] [2026-01-11 11:24:44] [Sidequest] [Dashboard] : Server running on http://localhost:8678
[info] [2026-01-11 11:24:44] [Sidequest] [Worker] : Starting worker with provided configuration...
[info] [2026-01-11 11:24:44] [Sidequest] [Core] : Running job #7 - HelloJob
[error] [2026-01-11 11:24:44] [Sidequest] [Runner] : Invalid job class: HelloJob
[error] [2026-01-11 11:24:44] [Sidequest] [Core] : Invalid job class: HelloJob
{
  name: 'Error',
  originalLine: 42,
  originalColumn: 81,
  line: 61,
  column: 43,
  sourceURL: '/Users/lauritz/Developer/fenzhong/node_modules/@sidequest/engine/dist/shared-runner/runner.js',
  Symbol(level): 'error'
}
Error: Invalid job class: HelloJob
    at run (/Users/lauritz/Developer/fenzhong/node_modules/@sidequest/engine/dist/shared-runner/runner.js:61:43)
    at async onMessage (/Users/lauritz/Developer/fenzhong/node_modules/piscina/dist/worker.js:180:28)
    at processTicksAndRejections (native:7:39)

If I run with tsx it's all fine

❯ npx tsx src/scripts/test.ts
[info] [2026-01-11 11:26:05] [Sidequest] [Engine] : Starting Sidequest using backend @sidequest/postgres-backend
[info] [2026-01-11 11:26:05] [Sidequest] [Dashboard] : Server running on http://localhost:8678
[info] [2026-01-11 11:26:06] [Sidequest] [Worker] : Starting worker with provided configuration...
[info] [2026-01-11 11:26:06] [Sidequest] [Core] : Running job #9 - HelloJob
hello Hello
[info] [2026-01-11 11:26:06] [Sidequest] [Core] : Job #9 - HelloJob has completed

I'm creating a new issue as the other was closed, and this time it's a different error message. Feel free to close if it's still an issue related to Piscina.

[erickreutz]

We are also interested in using Sidequest with Bun

[merencia]

Hey!

I'was able to make it work using manual job resolution.

app.js

import { Sidequest } from "sidequest";
import { HelloJob } from "./hello-job";

await Sidequest.start({
  backend: {
    driver: "@sidequest/postgres-backend",
    config: "postgres://postgres:postgres@localhost:5432/test_bun"
  },
  manualJobResolution: true,
  jobsFilePath: "./sidequest.jobs.ts"
});

Sidequest.build(HelloJob).enqueue("Lucas");

hello-job.ts

import { Job } from "sidequest";

export class HelloJob extends Job {
  run(name: string): string {
    const msg = `Hello ${name}`;
    console.log(msg);
    return msg;
  }
}

and the most important part:
sidequest.jobs.ts

export { HelloJob } from "./hello-job"

[merencia]

@lauritzsh since I was able to run sidequest on bun using manual job resolution I'm closing this issue.
feel free to reopen it if needed.

[lauritzsh]

Nice the manual resolution works. I went with another library for now, but I'll definitely reconsider Sidequest in the future. Hopefully the auto resolution works by then too.

Maybe the docs could be updated here https://docs.sidequestjs.com/installation#installation-instructions to say Bun isn't supported, but it works with manual resolution or something. So people who use Bun can try it too.

[erickreutz]

@lauritzsh what lib did you go with?

[lauritzsh]

what lib did you go with?

I ended up with https://github.com/timgit/pg-boss as it also just uses Postgres, but the documentation isn't really kept in sync with the npm package which is annoying, so I'm still interested in other solutions. One instance of this is https://timgit.github.io/pg-boss/#/./api/jobs?id=findjobsname-options which you'd think is available so I tried to use it, but the code wouldn't compile. The functionality seems to be merged a week ago, but the last version is from December 19 still, so that's why I can't use it.

The documentation isn't indexed by Google as well it seems https://www.google.com/search?q=site:https://timgit.github.io/pg-boss which I often prefer over the site's own search feature.

Good documentation that's synchronized with the npm release would make me switch.

I would say the mental model of pg-boss was simpler for me to set up. Specifically I have a web server running, and the worker in its own process. It was easy for me to understand to export a boss singleton, and call work in one process, send in the other process. It took me some time to figure how I would start Sidequest only in one process to do the actual work, allow the other to just send stuff to be processed, but I think I got it with .start vs .configure. I didn't get to experiment much more because of the Bun blocker.