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

package/dist/{boss-D16fO2oG.d.ts → boss-Caj5dGMm.d.ts}

@@ -7,6 +7,23 @@ import PgBoss from 'pg-boss';
  * Type definitions for the pg-boss based job system
  */
 
+/**
+ * pg-boss queue policy
+ *
+ * The policy decides which unique index pg-boss puts on
+ * `(queue name, singletonKey)`, and therefore what `singletonKey` actually
+ * deduplicates. A `standard` queue has no such index: the key is stored and
+ * ignored.
+ *
+ * | policy | one job per `(queue, singletonKey)` among states… |
+ * |---|---|
+ * | `standard` | none — the key is ignored |
+ * | `short` | `created` (queued, not yet picked up) |
+ * | `singleton` | `active` (running) — many may queue, one runs at a time |
+ * | `stately` | one per state among `created`, `retry`, `active` |
+ * | `exclusive` | `created` + `retry` + `active` together |
+ */
+type JobQueuePolicy = 'standard' | 'short' | 'singleton' | 'stately' | 'exclusive';
 /**
  * Job options passed to pg-boss
  */
@@ -39,9 +56,32 @@ interface JobOptions {
      */
     priority?: number;
     /**
-     * Singleton key - only one job with this key can exist
+     * Deduplication key. What it deduplicates depends entirely on `policy`:
+     * on a `standard` queue (the default for a plain job) pg-boss stores the
+     * key and never conflicts on it, so nothing is deduplicated.
+     *
+     * Setting this without an explicit `policy` makes the queue `exclusive`.
      */
     singletonKey?: string;
+    /**
+     * pg-boss queue policy — what `singletonKey` deduplicates on this queue.
+     *
+     * | policy | one job per `(queue, singletonKey)` among states… |
+     * |---|---|
+     * | `standard` | none — the key is ignored |
+     * | `short` | `created` |
+     * | `singleton` | `active` |
+     * | `stately` | one per state among `created`, `retry`, `active` |
+     * | `exclusive` | `created` + `retry` + `active` together |
+     *
+     * Deduplication is scoped by queue name: different queues never
+     * deduplicate against each other. `exclusive` with no `singletonKey`
+     * collapses the whole queue to one pending job, which is why plain jobs
+     * stay `standard`.
+     *
+     * @default 'exclusive' when the job is `.runOnce()` or sets `singletonKey`, otherwise 'standard'
+     */
+    policy?: JobQueuePolicy;
     /**
      * Keep completed jobs for this many seconds
      * @default 604800 (7 days)
@@ -71,7 +111,11 @@ interface JobSendOptions {
      */
     startAfter?: number | Date;
     /**
-     * Singleton key for this specific job instance
+     * Deduplication key for this specific job instance.
+     *
+     * Only takes effect when the job's queue has a non-standard `policy`: see
+     * {@link JobOptions.policy}. On a `standard` queue pg-boss stores the key
+     * and never conflicts on it, and the first such send logs a warning.
      */
     singletonKey?: string;
     /**
@@ -281,4 +325,4 @@ declare function isBossRunning(): boolean;
  */
 declare function shouldClearOnStart(): boolean;
 
-export { type BossConfig as B, type CompensateHandler as C, type InferJobInput as I, type JobOptions as J, type JobHandler as a, type JobDef as b, type JobRouter as c, type JobRouterEntry as d, type BossOptions as e, type InferJobOutput as f, type JobSendOptions as g, getBoss as h, initBoss as i, isBossRunning as j, stopBoss as k, shouldClearOnStart as s };
+export { type BossConfig as B, type CompensateHandler as C, type InferJobInput as I, type JobOptions as J, type JobHandler as a, type JobDef as b, type JobRouter as c, type JobRouterEntry as d, type JobQueuePolicy as e, type BossOptions as f, type InferJobOutput as g, type JobSendOptions as h, getBoss as i, initBoss as j, isBossRunning as k, stopBoss as l, shouldClearOnStart as s };

package/dist/job/index.d.ts

@@ -1,5 +1,5 @@
-import { J as JobOptions, C as CompensateHandler, a as JobHandler, b as JobDef, c as JobRouter, d as JobRouterEntry } from '../boss-D16fO2oG.js';
-export { B as BossConfig, e as BossOptions, I as InferJobInput, f as InferJobOutput, g as JobSendOptions, h as getBoss, i as initBoss, j as isBossRunning, s as shouldClearOnStart, k as stopBoss } from '../boss-D16fO2oG.js';
+import { J as JobOptions, C as CompensateHandler, a as JobHandler, b as JobDef, c as JobRouter, d as JobRouterEntry, e as JobQueuePolicy } from '../boss-Caj5dGMm.js';
+export { B as BossConfig, f as BossOptions, I as InferJobInput, g as InferJobOutput, h as JobSendOptions, i as getBoss, j as initBoss, k as isBossRunning, s as shouldClearOnStart, l as stopBoss } from '../boss-Caj5dGMm.js';
 import * as _sinclair_typebox from '@sinclair/typebox';
 import { Static } from '@sinclair/typebox';
 import { EventDef, InferEventPayload } from '@spfn/core/event';
@@ -168,11 +168,56 @@ declare function isJobRouter(value: unknown): value is JobRouter<any>;
  * ```
  */
 declare function defineJobRouter<TJobs extends Record<string, JobRouterEntry>>(jobs: TJobs): JobRouter<TJobs>;
+/**
+ * Merge two job routers into a new one
+ *
+ * `defineServerConfig().jobs()` may be called once per domain router, the way
+ * `.routes()` is; each call merges into what is already registered instead of
+ * replacing it. Keys are the router's own namespace, so a key present in both
+ * routers is a mistake the app cannot recover from silently — one of the two
+ * would disappear.
+ *
+ * Neither input is mutated: a fresh router is returned.
+ *
+ * @throws if a top-level key exists in both routers
+ */
+declare function mergeJobRouters(base: JobRouter<any>, extra: JobRouter<any>): JobRouter<any>;
 /**
  * Collect all JobDefs from a JobRouter (including nested)
  */
 declare function collectJobs(router: JobRouter<any>, prefix?: string): JobDef<any>[];
 
+/**
+ * Queue Policy Resolution
+ *
+ * Lives apart from register-jobs.ts and job-builder.ts so both can read the
+ * policy of a job definition without importing each other.
+ */
+
+/**
+ * The part of a job definition that decides its queue policy
+ *
+ * `JobDef` satisfies this; the builder can also pass its own fields before the
+ * definition object exists.
+ */
+interface QueuePolicySource {
+    readonly runOnce?: boolean;
+    readonly options?: JobOptions;
+}
+/**
+ * Resolve the pg-boss queue policy for a job definition
+ *
+ * An explicit `.options({ policy })` always wins. Otherwise a job that asks
+ * for deduplication — `.runOnce()` or an `options.singletonKey` — gets
+ * `exclusive`, the only policy under which a second enqueue is dropped while
+ * the first is still pending or running.
+ *
+ * Everything else stays `standard`: `exclusive` without a `singletonKey`
+ * deduplicates on `COALESCE(singleton_key, '')` and would collapse a plain
+ * queue to a single pending job.
+ */
+declare function resolveQueuePolicy(job: QueuePolicySource): JobQueuePolicy;
+
 /**
  * Job Registration
  *
@@ -215,4 +260,4 @@ declare function collectJobs(router: JobRouter<any>, prefix?: string): JobDef<an
  */
 declare function registerJobs(router: JobRouter<any>): Promise<void>;
 
-export { CompensateHandler, JobDef, JobHandler, JobOptions, JobRouter, JobRouterEntry, collectJobs, defineJobRouter, isJobDef, isJobRouter, job, registerJobs };
+export { CompensateHandler, JobDef, JobHandler, JobOptions, JobQueuePolicy, JobRouter, JobRouterEntry, collectJobs, defineJobRouter, isJobDef, isJobRouter, job, mergeJobRouters, registerJobs, resolveQueuePolicy };

package/dist/job/index.js

@@ -1,8 +1,8 @@
-import PgBoss from 'pg-boss';
 import { logger } from '@spfn/core/logger';
+import PgBoss from 'pg-boss';
 import { env } from '@spfn/core/config';
 
-// src/job/boss.ts
+// src/job/job-builder.ts
 var jobLogger = logger.child("@spfn/core:job");
 function requiresSSLWithoutVerification(connectionString) {
   try {
@@ -94,7 +94,29 @@ 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
+var jobLogger2 = logger.child("@spfn/core:job");
+var warnedIgnoredSingletonKeys = /* @__PURE__ */ new Set();
+function warnIfSingletonKeyIgnored(name, source) {
+  if (resolveQueuePolicy(source) !== "standard" || warnedIgnoredSingletonKeys.has(name)) {
+    return;
+  }
+  warnedIgnoredSingletonKeys.add(name);
+  jobLogger2.warn(
+    `[Job:${name}] singletonKey ignored: queue policy is "standard"; set .options({ policy: 'exclusive' }) (or another non-standard policy) to deduplicate`
+  );
+}
 function buildPgBossOptions(defaults, sendOptions) {
   const options = {};
   if (sendOptions?.startAfter) {
@@ -255,6 +277,9 @@ var JobBuilder = class _JobBuilder {
         );
       }
       const [input, sendOptions] = inputSchema ? [inputOrOptions, maybeOptions] : [void 0, inputOrOptions];
+      if (sendOptions?.singletonKey) {
+        warnIfSingletonKeyIgnored(name, { runOnce, options });
+      }
       return await boss.send(
         name,
         input ?? {},
@@ -276,6 +301,9 @@ var JobBuilder = class _JobBuilder {
         );
       }
       const [inputs, sendOptions] = inputSchema ? [inputsOrOptions, maybeOptions] : [void 0, inputsOrOptions];
+      if (sendOptions?.singletonKey) {
+        warnIfSingletonKeyIgnored(name, { runOnce, options });
+      }
       const pgBossOptions = buildPgBossOptions(options, sendOptions);
       const jobs = (inputs ?? [{}]).map((data) => ({
         name,
@@ -320,19 +348,32 @@ function defineJobRouter(jobs) {
     _jobs: jobs
   };
 }
-function collectJobs(router, prefix = "") {
-  const 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}`;
 }
@@ -353,11 +394,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) {
@@ -365,7 +407,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) {
@@ -376,42 +418,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) {
@@ -420,13 +497,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)
@@ -434,8 +511,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(
@@ -469,28 +546,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,
     {},
@@ -499,7 +576,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();
@@ -507,17 +584,18 @@ 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}`);
 }
 
-export { collectJobs, defineJobRouter, getBoss, initBoss, isBossRunning, isJobDef, isJobRouter, job, registerJobs, shouldClearOnStart, stopBoss };
+export { collectJobs, defineJobRouter, getBoss, initBoss, isBossRunning, isJobDef, isJobRouter, job, mergeJobRouters, registerJobs, resolveQueuePolicy, shouldClearOnStart, stopBoss };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map