@spfn/core 0.3.0-beta.5 → 0.3.0-beta.7

package/dist/server/index.js

@@ -2275,6 +2275,20 @@ function shouldSweepOrphanSchedules() {
   return getBossConfig()?.sweepOrphanSchedules ?? false;
 }
 
+// src/job/queue-policy.ts
+function resolveQueuePolicy(job2) {
+  if (job2.options?.policy) {
+    return job2.options.policy;
+  }
+  if (job2.runOnce || job2.options?.singletonKey) {
+    return "exclusive";
+  }
+  return "standard";
+}
+
+// src/job/job-builder.ts
+logger.child("@spfn/core:job");
+
 // src/job/job-router.ts
 function isJobDef(value) {
   return value !== null && typeof value === "object" && "name" in value && "handler" in value && "send" in value && "run" in value;
@@ -2282,19 +2296,38 @@ function isJobDef(value) {
 function isJobRouter(value) {
   return value !== null && typeof value === "object" && "jobs" in value && "_jobs" in value;
 }
-function collectJobs(router, prefix = "") {
-  const jobs = [];
+function defineJobRouter(jobs) {
+  return {
+    jobs,
+    _jobs: jobs
+  };
+}
+function mergeJobRouters(base, extra) {
+  for (const key of Object.keys(extra.jobs)) {
+    if (key in base.jobs) {
+      throw new Error(
+        `jobs(): key "${key}" is already registered by an earlier .jobs() call; rename it or nest it under a domain router`
+      );
+    }
+  }
+  return defineJobRouter({ ...base.jobs, ...extra.jobs });
+}
+function collectJobEntries(router, prefix = "") {
+  const entries = [];
   for (const [key, value] of Object.entries(router.jobs)) {
-    const name = prefix ? `${prefix}.${key}` : key;
+    const path = prefix ? `${prefix}.${key}` : key;
     if (isJobRouter(value)) {
-      jobs.push(...collectJobs(value, name));
+      entries.push(...collectJobEntries(value, path));
     } else if (isJobDef(value)) {
-      jobs.push(value);
+      entries.push({ key: path, job: value });
     }
   }
-  return jobs;
+  return entries;
 }
-var jobLogger2 = logger.child("@spfn/core:job");
+function collectJobs(router, prefix = "") {
+  return collectJobEntries(router, prefix).map((entry) => entry.job);
+}
+var jobLogger3 = logger.child("@spfn/core:job");
 function getEventQueueName(eventName) {
   return `event:${eventName}`;
 }
@@ -2315,11 +2348,12 @@ async function registerJobs(router) {
       "pg-boss not initialized. Call initBoss() before registerJobs()"
     );
   }
+  assertUniqueJobNames(router);
   const jobs = collectJobs(router);
   const clearOnStart = shouldClearOnStart();
-  jobLogger2.info(`Registering ${jobs.length} job(s)...`);
+  jobLogger3.info(`Registering ${jobs.length} job(s)...`);
   if (clearOnStart) {
-    jobLogger2.info("Clearing existing jobs before registration...");
+    jobLogger3.info("Clearing existing jobs before registration...");
     for (const job2 of jobs) {
       await boss.deleteAllJobs(job2.name);
       if (job2.subscribedEvent) {
@@ -2327,7 +2361,7 @@ async function registerJobs(router) {
         await boss.deleteAllJobs(eventQueue);
       }
     }
-    jobLogger2.info("Existing jobs cleared");
+    jobLogger3.info("Existing jobs cleared");
   }
   await Promise.all(jobs.map((job2) => registerJob(job2)));
   for (const job2 of jobs) {
@@ -2338,42 +2372,77 @@ async function registerJobs(router) {
   if (shouldSweepOrphanSchedules()) {
     await sweepOrphanSchedules(boss);
   }
-  jobLogger2.info("All jobs registered successfully");
+  jobLogger3.info("All jobs registered successfully");
+}
+function assertUniqueJobNames(router) {
+  const keysByName = /* @__PURE__ */ new Map();
+  for (const { key, job: job2 } of collectJobEntries(router)) {
+    const existingKey = keysByName.get(job2.name);
+    if (existingKey) {
+      throw new Error(
+        `registerJobs(): job name "${job2.name}" is defined twice (keys "${existingKey}" and "${key}"); job names are pg-boss queue names and must be unique`
+      );
+    }
+    keysByName.set(job2.name, key);
+  }
 }
 var registeredCronNames = /* @__PURE__ */ new Set();
 async function sweepOrphanSchedules(boss) {
   if (registeredCronNames.size === 0) {
-    jobLogger2.debug("No cron jobs declared; skipping orphan schedule sweep");
+    jobLogger3.debug("No cron jobs declared; skipping orphan schedule sweep");
     return;
   }
   try {
     const schedules = await boss.getSchedules();
     const orphans = schedules.filter((schedule) => !registeredCronNames.has(schedule.name));
     if (orphans.length === 0) {
-      jobLogger2.debug("No orphan schedules found");
+      jobLogger3.debug("No orphan schedules found");
       return;
     }
     await Promise.all(orphans.map(async (orphan) => {
       try {
         await boss.unschedule(orphan.name, orphan.key);
-        jobLogger2.info(`Removed orphan schedule: ${orphan.name}`);
+        jobLogger3.info(`Removed orphan schedule: ${orphan.name}`);
       } catch (error) {
-        jobLogger2.error(`Failed to remove orphan schedule: ${orphan.name}`, {
+        jobLogger3.error(`Failed to remove orphan schedule: ${orphan.name}`, {
           error: error instanceof Error ? error.message : String(error)
         });
       }
     }));
   } catch (error) {
-    jobLogger2.error("Orphan schedule sweep failed", {
+    jobLogger3.error("Orphan schedule sweep failed", {
       error: error instanceof Error ? error.message : String(error)
     });
   }
 }
-async function ensureQueue(boss, queueName) {
-  await boss.createQueue(queueName);
+async function ensureQueue(boss, queueName, policy) {
+  await boss.createQueue(queueName, { policy });
+  const existing = await boss.getQueue(queueName);
+  if (!existing || existing.policy === policy) {
+    return;
+  }
+  if (shouldClearOnStart()) {
+    await boss.deleteQueue(queueName);
+    await boss.createQueue(queueName, { policy });
+    jobLogger3.info(`[Queue:${queueName}] policy ${existing.policy} \u2192 ${policy} (recreated: clearOnStart)`);
+    return;
+  }
+  jobLogger3.error(
+    `[Queue:${queueName}] policy mismatch: the queue exists as "${existing.policy}" but its jobs require "${policy}". Delete the queue in a quiet window (getBoss().deleteQueue('${queueName}') drops its job rows) or set clearOnStart in development; until then singletonKey/runOnce on this queue do not deduplicate`
+  );
+}
+function createQueueEnsurer(boss, policy) {
+  const ensured = /* @__PURE__ */ new Set();
+  return async (queueName) => {
+    if (ensured.has(queueName)) {
+      return;
+    }
+    ensured.add(queueName);
+    await ensureQueue(boss, queueName, policy);
+  };
 }
 async function executeJobHandler(job2, pgBossJob) {
-  jobLogger2.debug(`[Job:${job2.name}] Executing...`, { jobId: pgBossJob.id });
+  jobLogger3.debug(`[Job:${job2.name}] Executing...`, { jobId: pgBossJob.id });
   const startTime = Date.now();
   try {
     if (job2.inputSchema) {
@@ -2382,13 +2451,13 @@ async function executeJobHandler(job2, pgBossJob) {
       await job2.handler();
     }
     const duration = Date.now() - startTime;
-    jobLogger2.info(`[Job:${job2.name}] Completed in ${duration}ms`, {
+    jobLogger3.info(`[Job:${job2.name}] Completed in ${duration}ms`, {
       jobId: pgBossJob.id,
       duration
     });
   } catch (error) {
     const duration = Date.now() - startTime;
-    jobLogger2.error(`[Job:${job2.name}] Failed after ${duration}ms`, {
+    jobLogger3.error(`[Job:${job2.name}] Failed after ${duration}ms`, {
       jobId: pgBossJob.id,
       duration,
       error: error instanceof Error ? error.message : String(error)
@@ -2396,8 +2465,8 @@ async function executeJobHandler(job2, pgBossJob) {
     throw error;
   }
 }
-async function registerWorker(boss, job2, queueName) {
-  await ensureQueue(boss, queueName);
+async function registerWorker(boss, job2, queueName, ensureQueueOnce) {
+  await ensureQueueOnce(queueName);
   const batchSize = job2.options?.batchSize ?? 1;
   const pollingIntervalSeconds = job2.options?.pollingIntervalSeconds ?? env.JOB_POLLING_INTERVAL_SECONDS;
   await boss.work(
@@ -2431,28 +2500,28 @@ function connectEventToQueue(boss, job2, queueName) {
   eventDef._registerJobQueue(queueName, async (queue, payload) => {
     await boss.send(queue, payload, getDefaultJobOptions(job2.options));
   });
-  jobLogger2.debug(`[Job:${job2.name}] Connected to event: ${job2.subscribedEvent}`);
+  jobLogger3.debug(`[Job:${job2.name}] Connected to event: ${job2.subscribedEvent}`);
 }
-async function registerCronSchedule(boss, job2) {
+async function registerCronSchedule(boss, job2, ensureQueueOnce) {
   if (!job2.cronExpression) {
     return;
   }
-  jobLogger2.debug(`[Job:${job2.name}] Scheduling cron: ${job2.cronExpression}`);
-  await ensureQueue(boss, job2.name);
+  jobLogger3.debug(`[Job:${job2.name}] Scheduling cron: ${job2.cronExpression}`);
+  await ensureQueueOnce(job2.name);
   await boss.schedule(
     job2.name,
     job2.cronExpression,
     {},
     getDefaultJobOptions(job2.options)
   );
-  jobLogger2.info(`[Job:${job2.name}] Cron scheduled: ${job2.cronExpression}`);
+  jobLogger3.info(`[Job:${job2.name}] Cron scheduled: ${job2.cronExpression}`);
 }
-async function queueRunOnceJob(boss, job2) {
+async function queueRunOnceJob(boss, job2, ensureQueueOnce) {
   if (!job2.runOnce) {
     return;
   }
-  jobLogger2.debug(`[Job:${job2.name}] Queuing runOnce job`);
-  await ensureQueue(boss, job2.name);
+  jobLogger3.debug(`[Job:${job2.name}] Queuing runOnce job`);
+  await ensureQueueOnce(job2.name);
   await boss.send(
     job2.name,
     {},
@@ -2461,7 +2530,7 @@ async function queueRunOnceJob(boss, job2) {
       singletonKey: `runOnce:${job2.name}`
     }
   );
-  jobLogger2.info(`[Job:${job2.name}] runOnce job queued`);
+  jobLogger3.info(`[Job:${job2.name}] runOnce job queued`);
 }
 async function registerJob(job2) {
   const boss = getBoss();
@@ -2469,15 +2538,16 @@ async function registerJob(job2) {
     throw new Error("pg-boss not initialized");
   }
   const queueName = job2.subscribedEvent ? getEventQueueName(job2.subscribedEvent) : job2.name;
-  jobLogger2.debug(`Registering job: ${job2.name}`, {
+  jobLogger3.debug(`Registering job: ${job2.name}`, {
     queueName,
     subscribedEvent: job2.subscribedEvent
   });
-  await registerWorker(boss, job2, queueName);
+  const ensureQueueOnce = createQueueEnsurer(boss, resolveQueuePolicy(job2));
+  await registerWorker(boss, job2, queueName, ensureQueueOnce);
   connectEventToQueue(boss, job2, queueName);
-  await registerCronSchedule(boss, job2);
-  await queueRunOnceJob(boss, job2);
-  jobLogger2.debug(`Job registered: ${job2.name}`);
+  await registerCronSchedule(boss, job2, ensureQueueOnce);
+  await queueRunOnceJob(boss, job2, ensureQueueOnce);
+  jobLogger3.debug(`Job registered: ${job2.name}`);
 }
 var wsLogger = logger.child("@spfn/core:ws");
 function isOriginAllowed(origin, allowList) {
@@ -3506,6 +3576,20 @@ var ServerConfigBuilder = class {
   /**
    * Register background jobs router
    *
+   * May be called once per domain router: repeated calls **merge** into one
+   * router, the way `.routes()` composes. Calling it several times used to
+   * keep only the last router and register nothing else, without warning.
+   *
+   * The pg-boss `config` is per server, so pass it on one call only.
+   *
+   * Two names can collide, and both fail loudly:
+   * - a router **key** present in two calls throws here, at config time;
+   * - two jobs sharing a **`job.name`** (the pg-boss queue name) throw in
+   *   `registerJobs()` at boot, before any queue or worker is created.
+   *
+   * @throws if a router key was already registered by an earlier call
+   * @throws if `config` is given when an earlier call already gave one
+   *
    * @example
    * ```typescript
    * import { job, defineJobRouter } from '@spfn/core/job';
@@ -3518,12 +3602,18 @@ var ServerConfigBuilder = class {
    *
    * export default defineServerConfig()
    *   .routes(appRouter)
-   *   .jobs(jobRouter)
+   *   .jobs(jobRouter, { clearOnStart: isDev })   // config on one call only
+   *   .jobs(billingJobRouter)                     // merged, not replaced
    *   .build();
    * ```
    */
   jobs(router, config) {
-    this.config.jobs = router;
+    if (config && this.config.jobsConfig) {
+      throw new Error(
+        "jobs(): pg-boss config was already given by an earlier .jobs() call; pass it once"
+      );
+    }
+    this.config.jobs = this.config.jobs ? mergeJobRouters(this.config.jobs, router) : router;
     if (config) {
       this.config.jobsConfig = config;
     }