@zerotal/queue 1.12.0 → 1.13.1

package/CHANGELOG.md

@@ -8,6 +8,26 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.13.1] — 2026-08-31
+
+### Added
+
+- **`Job.jobName`** — a declared name for the queue payload, so renaming a job class is free.
+
+  A queued job is a persisted reference to a class: the payload carries a string and the
+  worker resolves the class by it, so a job enqueued yesterday is looked up by today's
+  process. The class name was therefore a compatibility surface that nothing said was one —
+  renaming a job class silently invalidated every job already enqueued under the old name,
+  and the failure landed on the deploy rather than on the change. A test never sees it,
+  because a test enqueues and runs in the same process.
+
+  `static jobName` decouples the stored identity from the class, exactly as `Migration.id`
+  does for a migration's filename, and for the same reason. It defaults to the class name, so
+  a job that declares nothing behaves as before.
+
+  Found while sizing a suite-wide rename of `@internal` exports: three `Job` classes were on
+  that list, and renaming them would have been a data migration wearing a refactor's clothes.
+
 ## [1.9.0] — 2026-08-29
 
 ### Documented

package/api-surface.md

@@ -31,6 +31,7 @@ class Bus = {
 
 class Job = {
   new (): Job
+  static jobName?: string
   _chain: SerializedJob[] | undefined
   batchId: string | undefined
   className: string

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/queue",
-  "version": "1.12.0",
+  "version": "1.13.1",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -31,8 +31,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.12.0",
-    "@zerotal/orm": "1.12.0"
+    "@zerotal/core": "1.13.1",
+    "@zerotal/orm": "1.13.1"
   },
   "devDependencies": {
     "typescript": "^5.8.0"

package/src/Job.ts

@@ -81,10 +81,39 @@ export abstract class Job {
   }
 
   /**
-   * The class name used as the serialization key.
-   * Must match what JobRegistry.register() stores.
+   * The name this job is stored and resolved under, when it should not be the
+   * class name.
+   *
+   * A queued job is a *persisted* reference to a class: the payload in the
+   * database or in Redis carries a string, and the worker looks the class up by
+   * it. So the class name is a wire identifier, not just a source symbol — and
+   * renaming the class silently invalidates every job already enqueued under the
+   * old name. The failure lands on the deploy rather than on the change, and a
+   * test never sees it, because a test enqueues and runs in the same process.
+   *
+   * Declaring the name decouples the two, exactly as
+   * {@link @zerotal/orm!Migration.id} does for a migration's filename:
+   *
+   * ```ts
+   * export class SendWelcomeEmail extends Job {
+   *   static override jobName = "SendWelcomeEmail"; // survives a class rename
+   * }
+   * ```
+   *
+   * It also survives a build that mangles names. `zt compile` does not minify
+   * today, so this is not a live hazard — but nothing about the registry said it
+   * depended on that, which is the kind of assumption worth writing down before
+   * it is discovered.
+   *
+   * Defaults to the class name, so nothing changes for a job that does not set it.
+   */
+  static jobName?: string;
+
+  /**
+   * The name used as the serialization key. Matches what `JobRegistry.register()`
+   * stores: {@link Job.jobName} when declared, the class name otherwise.
    */
   get className(): string {
-    return this.constructor.name;
+    return (this.constructor as typeof Job).jobName ?? this.constructor.name;
   }
 }

package/src/JobRegistry.ts

@@ -1,17 +1,22 @@
 import type { Job } from "./Job.ts";
 
-type JobClass = new (...args: never[]) => Job;
+type JobClass = (new (...args: never[]) => Job) & { jobName?: string };
 
 /**
- * Global registry mapping job class names to their constructors.
+ * Global registry mapping a job's stored name to its constructor.
  * Required for deserialization — when a job is popped from the queue,
  * the worker looks up the class here to instantiate it.
+ *
+ * The key is {@link Job.jobName} when a job declares one, and the class name
+ * otherwise. That distinction exists because the key is written into a persisted
+ * payload: a job enqueued yesterday is resolved by today's process, so the name
+ * is a compatibility surface and renaming the class is a migration.
  */
 export const JobRegistry = {
   _map: new Map<string, JobClass>(),
 
   register(JobClass: JobClass): void {
-    JobRegistry._map.set(JobClass.name, JobClass);
+    JobRegistry._map.set(JobClass.jobName ?? JobClass.name, JobClass);
   },
 
   resolve(className: string): JobClass | undefined {