@arkstack/jobs 0.13.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Toneflix Technologies Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,71 @@
+# @arkstack/jobs
+
+[![@arkstack/jobs](https://img.shields.io/npm/dt/@arkstack/jobs?style=flat-square&label=@arkstack/jobs&link=https%3A%2F%2Fwww.npmjs.com%2Fpackage%2F@arkstack/jobs)](https://www.npmjs.com/package/@arkstack/jobs)
+
+Jobs module for Arkstack, providing dispatchable job classes and a dispatcher on top of [`@arkstack/queue`](../queue).
+
+`@arkstack/jobs` is the **authoring** layer; `@arkstack/queue` is the transport. This package gives you the `Job` base class, the `dispatch()` helper, and a registry so workers can reconstruct your job classes from a stored payload.
+
+## Writing a job
+
+```bash
+ark make:job SendWelcomeEmail
+```
+
+```ts
+// src/app/jobs/SendWelcomeEmail.ts
+import { Job } from '@arkstack/jobs'
+
+export class SendWelcomeEmail extends Job {
+  constructor(public userId: number) {
+    super()
+  }
+
+  async handle () {
+    // ... send the email
+  }
+}
+```
+
+## Dispatching
+
+```ts
+import { dispatch } from '@arkstack/jobs'
+import { SendWelcomeEmail } from '@app/jobs/SendWelcomeEmail'
+
+// static helper
+await SendWelcomeEmail.dispatch(user.id)
+await SendWelcomeEmail.dispatch(user.id).onQueue('mail').withDelay(60)
+await SendWelcomeEmail.dispatchSync(user.id)   // run inline now
+
+// functional helper
+await dispatch(new SendWelcomeEmail(user.id))
+await dispatch(new SendWelcomeEmail(user.id), { queue: 'mail', delay: 60 })
+```
+
+With the default `sync` queue connection the job runs immediately. Configure a
+`database` or `redis` connection (see `@arkstack/queue`) and run a worker to
+process jobs in the background:
+
+```bash
+ark queue:work
+```
+
+## Setup
+
+Importing `@arkstack/jobs` anywhere wires the queue (de)serialization
+automatically. For an explicit bootstrap hook (next to `@arkstack/database/setup`):
+
+```ts
+import '@arkstack/jobs/setup'
+```
+
+## How reconstruction works
+
+Each `Job` registers itself with the `JobRegistry` when constructed. When a
+worker pops a payload, the registry rebuilds the instance (bypassing the
+constructor) and assigns the serialized `data` back onto it. For dedicated worker
+**processes**, make sure your job modules are imported — or call
+`JobRegistry.register(MyJob)` — so the names are known before processing.
+
+Override `serialize()` on a job for custom payloads.

package/dist/bridge-CQ0DHM02.js

@@ -0,0 +1,198 @@
+import { Queue } from "@arkstack/queue";
+import { randomUUID } from "node:crypto";
+//#region src/JobRegistry.ts
+/**
+* A registry mapping job names to their classes so a worker can reconstruct job
+* instances from a stored payload.
+*
+* Job classes register themselves when instantiated, which covers same-process
+* dispatch + work. For dedicated worker processes, ensure the job modules are
+* imported (or call {@link JobRegistry.register} explicitly) so the names are
+* known before jobs are processed.
+*/
+var JobRegistry = class {
+	static classes = /* @__PURE__ */ new Map();
+	/**
+	* Register a job class under an explicit name (defaults to the class name).
+	*/
+	static register(jobClass, name) {
+		this.classes.set(name ?? jobClass.name, jobClass);
+		return this;
+	}
+	/**
+	* The registered name for a job instance, if any.
+	*/
+	static nameOf(job) {
+		const ctor = job.constructor;
+		for (const [name, jobClass] of this.classes) if (jobClass === ctor) return name;
+	}
+	/**
+	* Whether a job name is registered.
+	*/
+	static has(name) {
+		return this.classes.has(name);
+	}
+	/**
+	* Reconstruct a job instance from a payload.
+	*
+	* The constructor is bypassed (via `Object.create`) and the serialized data
+	* is assigned onto a fresh instance, so reconstruction never re-runs
+	* constructor side effects.
+	*/
+	static resolve(payload) {
+		const jobClass = this.classes.get(payload.displayName);
+		if (!jobClass) throw new Error(`Job "${payload.displayName}" is not registered. Import the job class or call JobRegistry.register().`);
+		const instance = Object.create(jobClass.prototype);
+		Object.assign(instance, payload.data);
+		return instance;
+	}
+	/**
+	* Remove all registrations. Intended for tests.
+	*/
+	static clear() {
+		this.classes.clear();
+	}
+};
+//#endregion
+//#region src/PendingDispatch.ts
+/**
+* A fluent, awaitable handle returned by `dispatch()` and `Job.dispatch()`.
+*
+* It collects routing overrides and, when awaited, pushes the job onto the
+* appropriate connection. Being thenable means `await dispatch(job)` works
+* directly, and the chained setters return `this` so they can precede the await:
+*
+* ```ts
+* await dispatch(new SendReport(id)).onQueue('reports').withDelay(30)
+* ```
+*/
+var PendingDispatch = class {
+	job;
+	constructor(job) {
+		this.job = job;
+	}
+	/** Set the connection this job is dispatched to. */
+	onConnection(connection) {
+		this.job.connection = connection;
+		return this;
+	}
+	/** Set the queue this job is dispatched to. */
+	onQueue(queue) {
+		this.job.queue = queue;
+		return this;
+	}
+	/** Delay the dispatch by a number of seconds (or until a Date). */
+	withDelay(delay) {
+		this.job.delay = delay instanceof Date ? Math.max(0, Math.round((delay.getTime() - Date.now()) / 1e3)) : delay;
+		return this;
+	}
+	/** The underlying job instance. */
+	getJob() {
+		return this.job;
+	}
+	/**
+	* Perform the dispatch, returning the resulting job id.
+	*/
+	send() {
+		if (this.job.delay && this.job.delay > 0) return Queue.later(this.job.delay, this.job, this.job.queue);
+		return Queue.push(this.job, this.job.queue);
+	}
+	then(onfulfilled, onrejected) {
+		return this.send().then(onfulfilled, onrejected);
+	}
+};
+//#endregion
+//#region src/Job.ts
+/**
+* The base class for dispatchable jobs.
+*
+* Extend it and implement {@link handle}. Instances are {@link Queueable}, so
+* they can be pushed straight onto a queue, but the fluent dispatch API is the
+* idiomatic entry point:
+*
+* ```ts
+* class SendWelcomeEmail extends Job {
+*   constructor(public userId: number) { super() }
+*   async handle() { ...  }
+* }
+*
+* await SendWelcomeEmail.dispatch(1)                 // default connection/queue
+* await SendWelcomeEmail.dispatch(1).onQueue('mail') // fluent overrides
+* await SendWelcomeEmail.dispatch(1).withDelay(60)
+* ```
+*/
+var Job = class {
+	/** The connection this job should be sent to. */
+	connection;
+	/** The queue this job should be sent to. */
+	queue;
+	/** Seconds to delay before the job becomes available. */
+	delay;
+	/** Maximum number of attempts before the job is marked failed. */
+	tries;
+	/** Seconds to wait before a released job becomes available again. */
+	backoff;
+	constructor() {
+		JobRegistry.register(this.constructor);
+	}
+	/**
+	* Serialize the job's state for storage. Defaults to a shallow copy of the
+	* instance's own properties. Override for custom serialization.
+	*/
+	serialize() {
+		return { ...this };
+	}
+	/** Send this job to the given connection. */
+	onConnection(connection) {
+		this.connection = connection;
+		return this;
+	}
+	/** Send this job to the given queue. */
+	onQueue(queue) {
+		this.queue = queue;
+		return this;
+	}
+	/** Delay the job by a number of seconds. */
+	withDelay(seconds) {
+		this.delay = seconds;
+		return this;
+	}
+	/**
+	* Create a pending dispatch for this job class with the given constructor
+	* arguments. Await it (or chain `onQueue`/`onConnection`/`withDelay`) to send.
+	*/
+	static dispatch(...args) {
+		return new PendingDispatch(new this(...args));
+	}
+	/**
+	* Dispatch immediately on the synchronous connection, running the job inline.
+	*/
+	static dispatchSync(...args) {
+		return new PendingDispatch(new this(...args)).onConnection("sync");
+	}
+};
+//#endregion
+//#region src/bridge.ts
+let registered = false;
+/**
+* Wire `@arkstack/jobs` into `@arkstack/queue` by registering how jobs are
+* serialized to and resolved from payloads.
+*
+* Importing `@arkstack/jobs` (or `@arkstack/jobs/setup`) runs this once. It is
+* idempotent, so calling it again is a no-op.
+*/
+const registerJobsWithQueue = () => {
+	if (registered) return;
+	registered = true;
+	Queue.serializeUsing((job) => ({
+		id: randomUUID(),
+		displayName: (job instanceof Job ? JobRegistry.nameOf(job) : void 0) ?? job.constructor?.name ?? "Closure",
+		attempts: 0,
+		maxTries: job.tries ?? null,
+		backoff: job.backoff ?? 0,
+		data: typeof job.serialize === "function" ? job.serialize() : { ...job }
+	}));
+	Queue.resolveJobsUsing((payload) => JobRegistry.resolve(payload));
+};
+//#endregion
+export { JobRegistry as i, Job as n, PendingDispatch as r, registerJobsWithQueue as t };

package/dist/commands/MakeJobCommand.d.ts

@@ -0,0 +1,14 @@
+import { Command } from "@h3ravel/musket";
+
+//#region src/commands/MakeJobCommand.d.ts
+/**
+ * Generate a new dispatchable job class.
+ */
+declare class MakeJobCommand extends Command {
+  protected signature: string;
+  protected description: string;
+  handle(): Promise<undefined>;
+  stub(name: string): string;
+}
+//#endregion
+export { MakeJobCommand };

package/dist/commands/MakeJobCommand.js

@@ -0,0 +1,47 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { Arkstack } from "@arkstack/contract";
+import { Command } from "@h3ravel/musket";
+import { dirname, resolve } from "node:path";
+//#region src/commands/MakeJobCommand.ts
+/**
+* Generate a new dispatchable job class.
+*/
+var MakeJobCommand = class extends Command {
+	signature = `make:job
+        {name : The name of the job class to create.}
+    `;
+	description = "Create a new queued job class.";
+	async handle() {
+		const name = String(this.argument("name")).replace(/\s+/g, "").replace(/\.ts$/, "").trim();
+		if (!name) {
+			this.error("Job name is required");
+			return;
+		}
+		const className = name.split("/").pop();
+		const filePath = resolve(Arkstack.rootDir(), "src", `app/jobs/${name}.ts`);
+		await mkdir(dirname(filePath), { recursive: true });
+		await writeFile(filePath, this.stub(className), { flag: "wx" });
+		this.success(`Job ${className} created successfully at ${filePath}`);
+	}
+	stub(name) {
+		return [
+			"import { Job } from '@arkstack/jobs'",
+			"",
+			`export class ${name} extends Job {`,
+			"    constructor() {",
+			"        super()",
+			"    }",
+			"",
+			"    /**",
+			"     * Execute the job.",
+			"     */",
+			"    async handle () {",
+			"        // Job logic goes here",
+			"    }",
+			"}",
+			""
+		].join("\n");
+	}
+};
+//#endregion
+export { MakeJobCommand };

package/dist/index.d.ts

@@ -0,0 +1,167 @@
+import { JobPayload, Queueable } from "@arkstack/queue";
+
+//#region src/PendingDispatch.d.ts
+/**
+ * A fluent, awaitable handle returned by `dispatch()` and `Job.dispatch()`.
+ *
+ * It collects routing overrides and, when awaited, pushes the job onto the
+ * appropriate connection. Being thenable means `await dispatch(job)` works
+ * directly, and the chained setters return `this` so they can precede the await:
+ *
+ * ```ts
+ * await dispatch(new SendReport(id)).onQueue('reports').withDelay(30)
+ * ```
+ */
+declare class PendingDispatch<T extends Job = Job> implements PromiseLike<string> {
+  private readonly job;
+  constructor(job: T);
+  /** Set the connection this job is dispatched to. */
+  onConnection(connection: string): this;
+  /** Set the queue this job is dispatched to. */
+  onQueue(queue: string): this;
+  /** Delay the dispatch by a number of seconds (or until a Date). */
+  withDelay(delay: number | Date): this;
+  /** The underlying job instance. */
+  getJob(): T;
+  /**
+   * Perform the dispatch, returning the resulting job id.
+   */
+  private send;
+  then<TResult1 = string, TResult2 = never>(onfulfilled?: ((value: string) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): PromiseLike<TResult1 | TResult2>;
+}
+//#endregion
+//#region src/Job.d.ts
+/**
+ * The base class for dispatchable jobs.
+ *
+ * Extend it and implement {@link handle}. Instances are {@link Queueable}, so
+ * they can be pushed straight onto a queue, but the fluent dispatch API is the
+ * idiomatic entry point:
+ *
+ * ```ts
+ * class SendWelcomeEmail extends Job {
+ *   constructor(public userId: number) { super() }
+ *   async handle() { ...  }
+ * }
+ *
+ * await SendWelcomeEmail.dispatch(1)                 // default connection/queue
+ * await SendWelcomeEmail.dispatch(1).onQueue('mail') // fluent overrides
+ * await SendWelcomeEmail.dispatch(1).withDelay(60)
+ * ```
+ */
+declare abstract class Job implements Queueable {
+  /** The connection this job should be sent to. */
+  connection?: string;
+  /** The queue this job should be sent to. */
+  queue?: string;
+  /** Seconds to delay before the job becomes available. */
+  delay?: number;
+  /** Maximum number of attempts before the job is marked failed. */
+  tries?: number;
+  /** Seconds to wait before a released job becomes available again. */
+  backoff?: number;
+  constructor();
+  /**
+   * Perform the work for this job. Implemented by subclasses.
+   */
+  abstract handle(): unknown | Promise<unknown>;
+  /**
+   * Serialize the job's state for storage. Defaults to a shallow copy of the
+   * instance's own properties. Override for custom serialization.
+   */
+  serialize(): Record<string, unknown>;
+  /** Send this job to the given connection. */
+  onConnection(connection: string): this;
+  /** Send this job to the given queue. */
+  onQueue(queue: string): this;
+  /** Delay the job by a number of seconds. */
+  withDelay(seconds: number): this;
+  /**
+   * Create a pending dispatch for this job class with the given constructor
+   * arguments. Await it (or chain `onQueue`/`onConnection`/`withDelay`) to send.
+   */
+  static dispatch<T extends Job>(this: new (...args: any[]) => T, ...args: any[]): PendingDispatch<T>;
+  /**
+   * Dispatch immediately on the synchronous connection, running the job inline.
+   */
+  static dispatchSync<T extends Job>(this: new (...args: any[]) => T, ...args: any[]): PendingDispatch<T>;
+}
+//#endregion
+//#region src/types.d.ts
+/**
+ * Constructor type for a dispatchable {@link Job} subclass.
+ */
+type JobConstructor<T extends Job = Job> = new (...args: any[]) => T;
+/**
+ * Options that can be passed to a dispatch call to override routing/retry.
+ */
+interface DispatchOptions {
+  connection?: string;
+  queue?: string;
+  delay?: number | Date;
+}
+//#endregion
+//#region src/JobRegistry.d.ts
+/**
+ * A registry mapping job names to their classes so a worker can reconstruct job
+ * instances from a stored payload.
+ *
+ * Job classes register themselves when instantiated, which covers same-process
+ * dispatch + work. For dedicated worker processes, ensure the job modules are
+ * imported (or call {@link JobRegistry.register} explicitly) so the names are
+ * known before jobs are processed.
+ */
+declare class JobRegistry {
+  private static classes;
+  /**
+   * Register a job class under an explicit name (defaults to the class name).
+   */
+  static register(jobClass: JobConstructor, name?: string): typeof JobRegistry;
+  /**
+   * The registered name for a job instance, if any.
+   */
+  static nameOf(job: Job): string | undefined;
+  /**
+   * Whether a job name is registered.
+   */
+  static has(name: string): boolean;
+  /**
+   * Reconstruct a job instance from a payload.
+   *
+   * The constructor is bypassed (via `Object.create`) and the serialized data
+   * is assigned onto a fresh instance, so reconstruction never re-runs
+   * constructor side effects.
+   */
+  static resolve(payload: JobPayload): Job;
+  /**
+   * Remove all registrations. Intended for tests.
+   */
+  static clear(): void;
+}
+//#endregion
+//#region src/dispatch.d.ts
+/**
+ * Dispatch a job instance onto a queue.
+ *
+ * Returns a {@link PendingDispatch} that can be awaited directly, chained with
+ * routing overrides, or passed `options` up front:
+ *
+ * ```ts
+ * await dispatch(new SendReport(id))
+ * await dispatch(new SendReport(id)).onQueue('reports')
+ * await dispatch(new SendReport(id), { queue: 'reports', delay: 30 })
+ * ```
+ */
+declare const dispatch: <T extends Job>(job: T, options?: DispatchOptions) => PendingDispatch<T>;
+//#endregion
+//#region src/bridge.d.ts
+/**
+ * Wire `@arkstack/jobs` into `@arkstack/queue` by registering how jobs are
+ * serialized to and resolved from payloads.
+ *
+ * Importing `@arkstack/jobs` (or `@arkstack/jobs/setup`) runs this once. It is
+ * idempotent, so calling it again is a no-op.
+ */
+declare const registerJobsWithQueue: () => void;
+//#endregion
+export { DispatchOptions, Job, JobConstructor, JobRegistry, PendingDispatch, dispatch, registerJobsWithQueue };

package/dist/index.js

@@ -0,0 +1,26 @@
+import { i as JobRegistry, n as Job, r as PendingDispatch, t as registerJobsWithQueue } from "./bridge-CQ0DHM02.js";
+//#region src/dispatch.ts
+/**
+* Dispatch a job instance onto a queue.
+*
+* Returns a {@link PendingDispatch} that can be awaited directly, chained with
+* routing overrides, or passed `options` up front:
+*
+* ```ts
+* await dispatch(new SendReport(id))
+* await dispatch(new SendReport(id)).onQueue('reports')
+* await dispatch(new SendReport(id), { queue: 'reports', delay: 30 })
+* ```
+*/
+const dispatch = (job, options = {}) => {
+	const pending = new PendingDispatch(job);
+	if (options.connection) pending.onConnection(options.connection);
+	if (options.queue) pending.onQueue(options.queue);
+	if (options.delay !== void 0) pending.withDelay(options.delay);
+	return pending;
+};
+//#endregion
+//#region src/index.ts
+registerJobsWithQueue();
+//#endregion
+export { Job, JobRegistry, PendingDispatch, dispatch, registerJobsWithQueue };

package/dist/setup.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/setup.js

@@ -0,0 +1,12 @@
+import { t as registerJobsWithQueue } from "./bridge-CQ0DHM02.js";
+//#region src/setup.ts
+/**
+* Boot the jobs/queue integration. Import this from your application bootstrap:
+*
+* ```ts
+* import '@arkstack/jobs/setup'
+* ```
+*/
+registerJobsWithQueue();
+//#endregion
+export {};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@arkstack/jobs",
+  "version": "0.13.0",
+  "type": "module",
+  "description": "Jobs module for Arkstack, providing dispatchable job classes and a dispatcher on top of @arkstack/queue.",
+  "homepage": "https://arkstack.toneflix.net/guide/jobs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/arkstack-hq/arkstack.git",
+    "directory": "packages/jobs"
+  },
+  "keywords": [
+    "jobs",
+    "queue",
+    "dispatch",
+    "background",
+    "dispatchable",
+    "worker",
+    "arkstack"
+  ],
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./commands/MakeJobCommand": "./dist/commands/MakeJobCommand.js",
+    "./setup": "./dist/setup.js",
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@arkstack/common": "^0.13.0",
+    "@arkstack/queue": "^0.13.0"
+  },
+  "peerDependencies": {
+    "@h3ravel/musket": "^2.2.0",
+    "@arkstack/contract": "^0.13.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest",
+    "version:patch": "pnpm version patch"
+  }
+}