@10x-media/jobs 0.1.0-beta.2 → 0.1.0-beta.3

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @10x-media/jobs
 
+## 0.1.0-beta.3
+
+### Minor Changes
+
+- Add a typed `translations` option to every plugin factory and make translation keys a stable public API. Each plugin's `./i18n` subpath now exports the `keys` object, the `TranslationKey` union, and the `TranslationsOption` shape. Overrides are flat and per-locale: values win over the built-in locales key-by-key, locales a plugin does not ship are added whole, and app-level `i18n.translations` still wins over everything.
+
+  ```ts
+  import { analytics } from "@10x-media/analytics";
+  import { keys } from "@10x-media/analytics/i18n";
+
+  analytics({
+    adapters: [nativeAdapter()],
+    translations: {
+      de: { [keys.pluginName]: "Analytik" },
+    },
+  });
+  ```
+
+  A typo'd key inside `translations` is a compile error.
+
+### Patch Changes
+
+- Restructure README: features, quick start, and links into the documentation site at https://docs.10xmedia.de. Long-form documentation moved out of the package README.
+
+- Update README documentation links: the docs site now serves from the domain root, so `docs.10xmedia.de/docs/<plugin>` links became `docs.10xmedia.de/<plugin>`.
+
+- Ship per-file dist output instead of bundled chunks. Bundling merged client components into shared chunks and dropped their 'use client' directives, so Next.js lost the RSC boundary and the admin panel crashed with "useRef only works in Client Components" when rendering components imported through such a chunk (for analytics: every chart-based dashboard widget). Dist now mirrors src one file at a time, directives stay exactly where they were authored, and file names are stable across releases. A repo-level `check:dist` verification (directive parity, no inlined dependencies, exports resolution, publint) now runs in CI so this class of regression cannot ship again.
+
 ## 0.1.0-beta.2
 
 ### Minor Changes

package/README.md

@@ -1,353 +1,54 @@
 # @10x-media/jobs
 
-A jobs ops dashboard and a production-grade reliability, execution, and queue-control layer for Payload's built-in `payload-jobs`.
+An ops dashboard plus reliability, worker, and queue-control layers for Payload v3's built-in jobs queue. See what the queue is doing, recover jobs that die mid-run, run a proper worker process with graceful drain, and pause or drive the queue from the outside. Every layer is opt-in.
 
 [![npm](https://img.shields.io/npm/v/@10x-media/jobs?style=flat-square)](https://www.npmjs.com/package/@10x-media/jobs)
 
 Part of the [@10x-media Payload plugins](https://github.com/10x-media/payload-plugins) collection. In beta: published under the `beta` dist-tag until a stable 1.0.
 
-## Requirements
+## Features
 
-- Payload v3 (peer: `payload@^3.82.0`)
-- React 19 (peer)
+- **Dashboard**: a derived Status column, a queue-health bar, and error/log panels on the `payload-jobs` collection. On by default.
+- **Reliability**: job leases, an orphan sweeper with dead-lettering, leader election with fence tokens, serverless staleness.
+- **Workers**: `createWorker` runs jobs as a standalone process and drains gracefully on SIGTERM.
+- **Queue control**: cluster-wide pause/resume plus hardened `queue-run`, `queue-sweep`, and `queue-status` endpoints with access guards.
+- **Topology presets** for serverless (Vercel Cron), single-node, and multi-node deployments.
+- **Typed translations** with per-key overrides via `@10x-media/jobs/i18n`.
 
-## Installation
+## Quick start
 
 ```bash
 pnpm add @10x-media/jobs
 ```
 
-## Usage
-
-```ts
-import { buildConfig } from 'payload'
-import { jobs } from '@10x-media/jobs'
-
-export default buildConfig({
-  // ...
-  plugins: [
-    jobs({
-      // options
-    }),
-  ],
-})
-```
-
-## Options
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `disabled` | `boolean` | `false` | When `true`, returns the incoming config unchanged. Useful for toggling the plugin per environment. |
-| `reliability` | `ReliabilityOptions \| boolean` | off | Job leases, the orphan sweeper, leader election, and serverless staleness. Opt in with `true` (defaults) or a tuned object. |
-| `queueControl` | `QueueControlOptions \| boolean` | off | Cluster-wide pause/resume, hardened run/sweep/status endpoints, and access guards. Opt in with `true` (defaults) or a tuned object. |
-
-<!-- Add new options to this table as you build them. -->
-
-## Deployment topologies
-
-The plugin ships four opt-in layers. You add only the ones your deployment needs, and you pick a topology preset to wire reliability and queue-control consistently.
-
-### Overview
-
-| Layer | What it adds | How to enable |
-|---|---|---|
-| Observability | The jobs ops dashboard (status, queue health, error and log panels) and i18n. | Always on (just adding `jobs()`). |
-| Reliability | Job leases, an orphan sweeper, leader election, serverless staleness. | `reliability: true` (or a tuned `ReliabilityOptions`). |
-| Execution | A standalone worker (`createWorker`) that runs jobs everywhere and schedules/sweeps only while holding the leader lease, with a graceful SIGTERM drain. | Run the worker entrypoint as its own process. |
-| Queue control | Cluster-wide pause/resume plus hardened `/api/payload-jobs/queue-run`, `/queue-sweep`, and `/queue-status` endpoints with access guards. | `queueControl: true` (or a tuned `QueueControlOptions`). |
-
-Every layer is opt-in. The observability dashboard is always present once the plugin is installed. The other three you turn on as your topology demands.
-
-Three facts shape every topology below.
-
-1. **Reliability and queue-control require at least one configured task.** The `payload-jobs` collection only materializes once you configure at least one task. With zero tasks, `createWorker` throws a clear error telling you to add one, and the lease store has no table to read. Configure your tasks on `jobs.tasks` in `buildConfig` before enabling reliability or running a worker.
-
-2. **The worker is a separate process, not your web server.** The execution layer (`createWorker`) is meant to run as its own long-lived process (a worker container, a separate Vercel-incompatible service). Your Next.js / Payload web server handles HTTP. The worker boots its own Payload instance against the same database and owns the run/schedule/sweep loops. The only topology that does not run a worker process is serverless, which drives everything from cron-hit endpoints instead.
-
-3. **Completed jobs are deleted, not kept.** Payload's `jobs.deleteJobOnComplete` defaults to `true` in v3.85, so a job that finishes successfully is removed from the queue. With the default, the dashboard and `/queue-status` counts reflect the live states (`queued`, `scheduled`, `retrying`, `processing`, `failed`, `cancelled`), since succeeded jobs are gone. Set `jobs.deleteJobOnComplete: false` in `buildConfig` to keep completed jobs for auditing; the `succeeded` count then reflects them.
-
-Pick a preset:
-
-```ts
-import { jobs, serverlessPreset, singleNodePreset, multiNodePreset } from '@10x-media/jobs'
-
-// Serverless (Vercel): cron-driven endpoints, no long-running worker.
-jobs({ ...serverlessPreset({ maxDurationMs: 800_000 }) })
-
-// Single-node Docker: one worker container, claim races moot.
-jobs({ ...singleNodePreset() })
-
-// Multi-node Docker: many worker replicas, one elected scheduler and sweeper.
-jobs({ ...multiNodePreset({ leaderId: process.env.HOSTNAME }) })
-```
-
-Each preset returns `{ reliability, queueControl }`, so spreading it into `jobs({ ... })` configures both layers at once. An override after the spread replaces the whole group (it does not deep-merge), so to tweak one field spread the group too: `jobs({ ...multiNodePreset(), reliability: { ...multiNodePreset().reliability, leaderId: 'node-7' } })`.
-
-### Serverless (Vercel)
-
-Serverless functions are killed at their `maxDuration` with no SIGTERM, so there is no long-running worker and heartbeats are meaningless. `serverlessPreset` instead derives job staleness from the platform hard-kill duration and guards the control endpoints with a shared cron secret. You drive the run and sweep from Vercel Cron.
-
-```ts
-// payload.config.ts
-import { buildConfig } from 'payload'
-import { jobs, serverlessPreset } from '@10x-media/jobs'
-
-export default buildConfig({
-  // ...
-  jobs: {
-    tasks: [
-      // ...your tasks; at least one is required.
-    ],
-  },
-  plugins: [jobs({ ...serverlessPreset({ maxDurationMs: 800_000 }) })],
-})
-```
-
-`serverlessPreset` sets `reliability.jobLeaseTtlMs` and `reliability.serverless.maxDurationMs` to your `maxDurationMs`, and sets `queueControl.access` to `cronSecretAccess()`. Pass `cronSecretEnvVar` if your secret lives somewhere other than `CRON_SECRET`.
-
-Generate the `vercel.json` crons with `vercelCrons()`:
-
-```ts
-// scripts/vercel-crons.ts (or hand-write the array below into vercel.json)
-import { vercelCrons } from '@10x-media/jobs'
-
-console.log(JSON.stringify({ crons: vercelCrons() }, null, 2))
-```
-
-```json
-{
-  "crons": [
-    { "path": "/api/payload-jobs/queue-run?allQueues=true", "schedule": "* * * * *" },
-    { "path": "/api/payload-jobs/queue-sweep", "schedule": "* * * * *" }
-  ]
-}
-```
-
-`vercelCrons()` defaults to every minute (Vercel Pro). Override any path or schedule, for example `vercelCrons({ sweepSchedule: '*/5 * * * *' })`.
-
-**The cron secret.** Set `CRON_SECRET` in your Vercel project. Vercel sends it as `Authorization: Bearer ${CRON_SECRET}` on every cron invocation, and `cronSecretAccess` checks exactly that header (a logged-in admin user also passes, so you can hit the endpoints manually from the panel). Without the secret set, unauthenticated cron requests are rejected.
-
-**The endpoints.** Both are plugin-registered GET endpoints on the `payload-jobs` collection:
-
-- `/api/payload-jobs/queue-run` runs due jobs (pause-aware, mirrors the native run params). `?allQueues=true` runs every queue, `?queue=<name>` runs one, `?limit=<n>` caps jobs per invocation, `?disableScheduling=true` skips schedule handling.
-- `/api/payload-jobs/queue-sweep` runs one orphan sweep (a single cron invocation, so no leader election). Requires reliability to be enabled.
-
-**CSRF note.** Both `queue-run` and `queue-sweep` are state-mutating operations served over GET. A crafted `<img>` or link in a document opened by a logged-in admin can trigger them silently (CSRF). The serverless preset uses Vercel Cron, which sends GET requests only, so switching to POST is not feasible without breaking the Vercel cron flow. For deployments where browser sessions are involved, override `access` to require an `Authorization: Bearer` token (`cronSecretAccess`) rather than relying on the session cookie (`loggedInAccess`).
-
-**Vercel limits.** Match your plan to a cron cadence and a function duration:
-
-- **Hobby**: crons run at most **once per day** and functions cap at **300s**. That is unusable for real job processing. Use Hobby only for a toy or a demo.
-- **Pro**: crons run **per minute** and functions extend to **800s**. That per-minute, 800s window is the practical floor for serverless job processing, which is why `serverlessPreset({ maxDurationMs: 800_000 })` and `vercelCrons()` default to it.
-
-**`limit` guidance.** A serverless run must finish inside `maxDuration`. Set `?limit=<n>` on the run cron (or `vercelCrons({ runPath: '/api/payload-jobs/queue-run?allQueues=true&limit=20' })`) so one batch of jobs comfortably fits the window. Size the limit to `maxDuration / (slowest expected job duration)` with headroom. If a batch risks overrunning, lower the limit and let the next minute's cron pick up the rest.
-
-### Single-node Docker
-
-One worker container claims and runs every job serially, so claim races are moot and leader election is a no-op (the single node always wins). `singleNodePreset()` turns on reliability and queue-control with defaults; the in-process worker runs the scheduler and sweeper directly.
-
 ```ts
 // payload.config.ts
 import { buildConfig } from 'payload'
 import { jobs, singleNodePreset } from '@10x-media/jobs'
 
 export default buildConfig({
-  // ...
   jobs: {
-    tasks: [
-      // ...your tasks; at least one is required.
-    ],
+    tasks: [/* at least one task; payload-jobs does not exist without one */],
   },
   plugins: [jobs({ ...singleNodePreset() })],
 })
 ```
 
-Run the worker as its own service in `docker-compose.yml`, alongside your web service and database:
-
-```yaml
-services:
-  web:
-    build: .
-    command: ['node', 'server.js']
-    environment:
-      DATABASE_URI: postgres://postgres:postgres@db:5432/app
-      PAYLOAD_SECRET: ${PAYLOAD_SECRET}
-    depends_on: [db]
-
-  worker:
-    build: .
-    # Exec-form CMD so Node is PID 1 and receives SIGTERM directly.
-    command: ['node', 'dist/worker.js']
-    environment:
-      DATABASE_URI: postgres://postgres:postgres@db:5432/app
-      PAYLOAD_SECRET: ${PAYLOAD_SECRET}
-    depends_on: [db]
-
-  db:
-    image: postgres:16
-    environment:
-      POSTGRES_DB: app
-      POSTGRES_PASSWORD: postgres
-```
+`jobs({})` alone enables the dashboard; the preset also turns on reliability and queue control. Run a worker process for production execution.
 
-`dist/worker.js` is your compiled worker entrypoint (see below). In development you can run the TypeScript source directly with `node --import tsx worker.ts`. With one claimer, you do not need to tune leader leases; defaults are fine.
+## Documentation
 
-### Multi-node Docker
-
-Many worker replicas share one database. Every replica runs jobs, but only the replica holding the `scheduler` lease handles schedules and only the one holding the `sweeper` lease runs the orphan sweep. `multiNodePreset()` is the default: leader-elected scheduling and sweeping with no extra infrastructure (the leases live in the plugin-owned `payload-jobs-locks` collection).
-
-```ts
-// payload.config.ts
-import { buildConfig } from 'payload'
-import { jobs, multiNodePreset } from '@10x-media/jobs'
-
-export default buildConfig({
-  // ...
-  jobs: {
-    tasks: [
-      // ...your tasks; at least one is required.
-    ],
-  },
-  // process.env.HOSTNAME is each container's id, a natural stable leader id.
-  plugins: [jobs({ ...multiNodePreset({ leaderId: process.env.HOSTNAME }) })],
-})
-```
-
-`leaderId` is the stable identity this node uses when it acquires a lease. Pass `process.env.HOSTNAME` (or any per-replica stable value); omit it to let the worker generate a `hostname:pid` identity at runtime. Leadership fails over automatically: if the current leader dies, another replica acquires the lease once it expires (`leaderLeaseTtlMs`, default 30s) and a monotonic fence token prevents a revived zombie from acting.
-
-**Env-designated-leader fallback (zero infra).** If you do not want leader election at all, you can designate one replica as the scheduler by environment. Run native auto-scheduling on a single replica and disable scheduling on the rest:
-
-```ts
-import { autoRunConfig } from '@10x-media/jobs'
-
-const isScheduler = process.env.JOBS_SCHEDULER === '1'
-
-export default buildConfig({
-  // ...
-  jobs: {
-    tasks: [/* ... */],
-    // Only the designated replica handles schedules; the others just run jobs.
-    autoRun: autoRunConfig({ disableScheduling: !isScheduler }),
-  },
-  plugins: [jobs({ ...multiNodePreset() })],
-})
-```
-
-Set `JOBS_SCHEDULER=1` on exactly one replica (or run a single dedicated scheduler replica). This trades automatic failover for zero coordination state. Leader election (the default) is preferred when you want a replica loss to recover on its own.
-
-**Graceful shutdown is a hard requirement under multi-node.** When an orchestrator rolls or scales down a replica, it sends SIGTERM, then SIGKILLs after a grace period. The worker's drain requeues its in-flight job (so another replica picks it up) and releases its leases, but only if it is given time to finish.
-
-- The orchestrator grace period must be set to `drainTimeoutMs + pollIntervalMs + 5s` to be safe. In Docker Compose set `stop_grace_period`; in Kubernetes set `terminationGracePeriodSeconds`. The actual shutdown time is `drainTimeoutMs` plus up to one `pollIntervalMs` (drain loop overrun) plus the `releaseLeadership` DB roundtrip plus `payload.destroy()` latency, which can be significant if the DB connection pool is busy. If the grace period is shorter, the orchestrator SIGKILLs a still-draining worker and you lose the clean requeue.
-- The container `CMD` must be **exec form** (`CMD ["node", "dist/worker.js"]`, not `CMD node dist/worker.js`). Shell form runs Node as a child of `/bin/sh`, which does not forward SIGTERM, so the worker never drains and is hard-killed every time.
-
-```yaml
-services:
-  worker:
-    build: .
-    command: ['node', 'dist/worker.js'] # exec form: Node receives SIGTERM
-    # drainTimeoutMs (30s) + pollIntervalMs (0.5s) + 5s buffer = 36s; round up to 40s.
-    stop_grace_period: 40s
-    deploy:
-      replicas: 3
-    environment:
-      DATABASE_URI: postgres://postgres:postgres@db:5432/app
-      PAYLOAD_SECRET: ${PAYLOAD_SECRET}
-    depends_on: [db]
-```
-
-The Kubernetes equivalent: an exec-form `command` in the pod spec and `terminationGracePeriodSeconds: 40` (`drainTimeoutMs + pollIntervalMs + 5s` buffer).
-
-### The worker entrypoint
-
-The worker is a thin bootstrap: boot Payload, resolve reliability options, and start the worker. `createWorker` installs SIGTERM/SIGINT drain handlers by default, so the process drains and exits 0 on a real signal. This is the canonical pattern (mirrors `packages/jobs/dev/worker.ts`):
-
-```ts
-// worker.ts
-import { getPayload } from 'payload'
-import { createWorker, resolveReliabilityOptions } from '@10x-media/jobs'
-
-import config from './payload.config'
-
-const RELIABILITY_OPTIONS = {
-  jobLeaseTtlMs: 300_000,
-  leaderLeaseTtlMs: 30_000,
-  sweepIntervalMs: 60_000,
-}
-
-const main = async (): Promise<void> => {
-  const payload = await getPayload({ config })
-  const reliability = resolveReliabilityOptions(RELIABILITY_OPTIONS)
-  if (!reliability) {
-    throw new Error('@10x-media/jobs worker: reliability resolved to null')
-  }
-  createWorker({
-    payload,
-    reliability,
-    drainTimeoutMs: 30_000,
-    runIntervalMs: 2_000,
-  }).start()
-  payload.logger.info('@10x-media/jobs worker started; awaiting jobs and signals')
-}
-
-main().catch((err) => {
-  console.error('@10x-media/jobs worker failed to start', err)
-  process.exit(1)
-})
-```
-
-Notes:
-
-- `resolveReliabilityOptions` fully defaults your `ReliabilityOptions`. It returns `null` when reliability is off (passed `false` or `undefined`), which the worker cannot run with, hence the guard.
-- Pass the same reliability tuning you give the plugin (share a constant between `payload.config.ts` and `worker.ts`) so the lease TTLs match across the cluster.
-- `createWorker` registers SIGTERM and SIGINT handlers automatically (`installSignals` defaults to `true`). On signal it drains in-flight jobs (within `drainTimeoutMs`), requeues any straggler, releases leases, destroys the Payload instance, and exits **0** on clean drain or **1** if the drain timed out (jobs were requeued). Keep your orchestrator grace period at `drainTimeoutMs + pollIntervalMs + 5s` (see Multi-node above).
-- Only one worker with `installSignals: true` may exist per process. Creating a second one throws. Use `installSignals: false` for additional workers in the same process (e.g. test helpers).
-- Run it with `node --import tsx worker.ts` in development, or compile it and run `node dist/worker.js` in production.
-
-### CI-optional e2e recipes
-
-Two real-process scenarios are proven in-process by the test suite, so they are not automated in CI. Both are useful to run by hand against a real database when validating a deployment. Mark them manual / CI-optional.
-
-**Recipe 1: two workers, one elected scheduler.** Run two worker processes against the same database and confirm exactly one holds the `scheduler` lease.
-
-```bash
-# Terminal 1 and Terminal 2 (same DATABASE_URI), distinct leader ids:
-JOBS_LEADER_ID=node-a node --import tsx worker.ts
-JOBS_LEADER_ID=node-b node --import tsx worker.ts
-```
-
-Then inspect the leases collection (one row per role, `owner` names the current holder):
-
-```ts
-const locks = await payload.find({
-  collection: 'payload-jobs-locks',
-  where: { role: { equals: 'scheduler' } },
-})
-// Expect exactly one row whose `owner` is node-a OR node-b, never both.
-console.log(locks.docs.map((d) => ({ role: d.role, owner: d.owner, fenceToken: d.fenceToken })))
-```
-
-Only the owning worker logs schedule handling; the other runs jobs but never schedules. (Wire `leaderId` into your worker from `process.env.JOBS_LEADER_ID` for this recipe.)
-
-**Recipe 2: kill a worker mid-job, watch the sweeper recover the orphan.** Confirm that a hard-killed worker's in-flight job is reclaimed by another worker's sweeper after the lease expires.
-
-```bash
-# Start two workers against the same DB (as above), then queue a long job:
-#   await payload.jobs.queue({ task: 'your-slow-task', input: { ... } })
-# Find the PID of the worker that claimed it and hard-kill it (no drain):
-kill -9 <worker-pid>
-```
-
-A `kill -9` skips the graceful drain entirely, so the job stays marked processing with a stale lease. After `jobLeaseTtlMs` elapses, the surviving worker's sweeper detects the orphan and requeues it (up to `maxRecoveries` times, then dead-letters). Watch the job flip back to queued and then get re-claimed:
-
-```ts
-const orphans = await payload.find({
-  collection: 'payload-jobs',
-  where: { and: [{ processing: { equals: false } }, { recoveryAttempts: { greater_than: 0 } }] },
-})
-// After the lease TTL, the killed worker's job appears here with recoveryAttempts >= 1.
-console.log(orphans.totalDocs)
-```
+Full documentation at [docs.10xmedia.de](https://docs.10xmedia.de/jobs):
 
-Give it at least `jobLeaseTtlMs + sweepIntervalMs` before asserting recovery.
+- [Overview](https://docs.10xmedia.de/jobs)
+- [Quick start](https://docs.10xmedia.de/jobs/quick-start)
+- [Dashboard](https://docs.10xmedia.de/jobs/dashboard)
+- [Reliability](https://docs.10xmedia.de/jobs/reliability)
+- [Workers](https://docs.10xmedia.de/jobs/workers)
+- [Topologies](https://docs.10xmedia.de/jobs/topologies)
+- [Queue control](https://docs.10xmedia.de/jobs/queue-control)
+- [Testing and local dev](https://docs.10xmedia.de/jobs/testing)
+- [i18n](https://docs.10xmedia.de/jobs/i18n)
 
 ## License
 

package/dist/execution/autoRunConfig.d.ts

@@ -0,0 +1,36 @@
+import { JobsConfig } from "payload";
+
+//#region src/execution/autoRunConfig.d.ts
+/**
+ * Payload's per-cron autoRun config. Payload 3.85.0 does not re-export the
+ * `AutorunCronConfig` type from its package root, so derive it from the array branch of
+ * the publicly exported `JobsConfig['autoRun']` (which Payload types as that element).
+ */
+type AutorunCronConfig = Extract<NonNullable<JobsConfig['autoRun']>, unknown[]>[number];
+/** One logical queue's autoRun cadence. */
+type AutoRunQueueConfig = {
+  queue: string; /** Cron cadence for this queue. Default every minute. */
+  cron?: string; /** Max jobs claimed per tick. Default 10. */
+  limit?: number;
+};
+type AutoRunConfigOptions = {
+  /** One entry per logical queue. Default a single `default` queue. */queues?: AutoRunQueueConfig[]; /** Suppress per-run info logging. Default true. */
+  silent?: boolean;
+  /**
+   * Disable native auto-scheduling on these crons. Default false. Set true when a
+   * `createWorker` owns scheduling (multi-node), so the cron only runs jobs.
+   */
+  disableScheduling?: boolean;
+};
+/**
+ * Build a production `jobs.autoRun` array: one Croner config per queue, silent by
+ * default, with Payload's own `protect: true` preventing overlap. This is the simple
+ * single-node and serverless-adjacent path where native autoRun safely handles both
+ * scheduling and running in one process. Multi-node deployments use `createWorker`
+ * instead, because native autoRun cannot gate scheduling to one elected leader (its
+ * only dynamic lever, `shouldAutoRun`, permanently stops the cron rather than pausing).
+ */
+declare const autoRunConfig: (options?: AutoRunConfigOptions) => AutorunCronConfig[];
+//#endregion
+export { AutoRunConfigOptions, AutoRunQueueConfig, autoRunConfig };
+//# sourceMappingURL=autoRunConfig.d.ts.map

package/dist/execution/autoRunConfig.js

@@ -0,0 +1,25 @@
+//#region src/execution/autoRunConfig.ts
+const DEFAULT_CRON = "* * * * *";
+const DEFAULT_LIMIT = 10;
+/**
+* Build a production `jobs.autoRun` array: one Croner config per queue, silent by
+* default, with Payload's own `protect: true` preventing overlap. This is the simple
+* single-node and serverless-adjacent path where native autoRun safely handles both
+* scheduling and running in one process. Multi-node deployments use `createWorker`
+* instead, because native autoRun cannot gate scheduling to one elected leader (its
+* only dynamic lever, `shouldAutoRun`, permanently stops the cron rather than pausing).
+*/
+const autoRunConfig = (options = {}) => {
+	const { disableScheduling = false, queues = [{ queue: "default" }], silent = true } = options;
+	return queues.map((q) => ({
+		cron: q.cron ?? DEFAULT_CRON,
+		disableScheduling,
+		limit: q.limit ?? DEFAULT_LIMIT,
+		queue: q.queue,
+		silent
+	}));
+};
+//#endregion
+export { autoRunConfig };
+
+//# sourceMappingURL=autoRunConfig.js.map

package/dist/execution/autoRunConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"autoRunConfig.js","names":[],"sources":["../../src/execution/autoRunConfig.ts"],"sourcesContent":["import type { JobsConfig } from 'payload'\n\n/**\n * Payload's per-cron autoRun config. Payload 3.85.0 does not re-export the\n * `AutorunCronConfig` type from its package root, so derive it from the array branch of\n * the publicly exported `JobsConfig['autoRun']` (which Payload types as that element).\n */\nexport type AutorunCronConfig = Extract<NonNullable<JobsConfig['autoRun']>, unknown[]>[number]\n\n/** One logical queue's autoRun cadence. */\nexport type AutoRunQueueConfig = {\n\tqueue: string\n\t/** Cron cadence for this queue. Default every minute. */\n\tcron?: string\n\t/** Max jobs claimed per tick. Default 10. */\n\tlimit?: number\n}\n\nexport type AutoRunConfigOptions = {\n\t/** One entry per logical queue. Default a single `default` queue. */\n\tqueues?: AutoRunQueueConfig[]\n\t/** Suppress per-run info logging. Default true. */\n\tsilent?: boolean\n\t/**\n\t * Disable native auto-scheduling on these crons. Default false. Set true when a\n\t * `createWorker` owns scheduling (multi-node), so the cron only runs jobs.\n\t */\n\tdisableScheduling?: boolean\n}\n\nconst DEFAULT_CRON = '* * * * *'\nconst DEFAULT_LIMIT = 10\n\n/**\n * Build a production `jobs.autoRun` array: one Croner config per queue, silent by\n * default, with Payload's own `protect: true` preventing overlap. This is the simple\n * single-node and serverless-adjacent path where native autoRun safely handles both\n * scheduling and running in one process. Multi-node deployments use `createWorker`\n * instead, because native autoRun cannot gate scheduling to one elected leader (its\n * only dynamic lever, `shouldAutoRun`, permanently stops the cron rather than pausing).\n */\nexport const autoRunConfig = (options: AutoRunConfigOptions = {}): AutorunCronConfig[] => {\n\tconst { disableScheduling = false, queues = [{ queue: 'default' }], silent = true } = options\n\treturn queues.map((q) => ({\n\t\tcron: q.cron ?? DEFAULT_CRON,\n\t\tdisableScheduling,\n\t\tlimit: q.limit ?? DEFAULT_LIMIT,\n\t\tqueue: q.queue,\n\t\tsilent,\n\t}))\n}\n"],"mappings":";AA8BA,MAAM,eAAe;AACrB,MAAM,gBAAgB;;;;;;;;;AAUtB,MAAa,iBAAiB,UAAgC,CAAC,MAA2B;CACzF,MAAM,EAAE,oBAAoB,OAAO,SAAS,CAAC,EAAE,OAAO,UAAU,CAAC,GAAG,SAAS,SAAS;CACtF,OAAO,OAAO,KAAK,OAAO;EACzB,MAAM,EAAE,QAAQ;EAChB;EACA,OAAO,EAAE,SAAS;EAClB,OAAO,EAAE;EACT;CACD,EAAE;AACH"}

package/dist/execution/drain.d.ts

@@ -0,0 +1,33 @@
+//#region src/execution/drain.d.ts
+type DrainDeps = {
+  /** Stop the worker's interval loops (stop claiming new jobs). */stopLoops: () => void; /** Count this node's in-flight jobs (processing and claimed by it). */
+  countInFlight: () => Promise<number>; /** Requeue this node's remaining in-flight jobs. Returns how many were released. */
+  requeueStragglers: () => Promise<number>; /** Release the held scheduler and sweeper leadership leases. */
+  releaseLeadership: () => Promise<void>; /** Destroy the Payload instance (stops crons, closes the DB). */
+  destroy: () => Promise<void>; /** Wall-clock milliseconds (real in production, virtual in tests). */
+  now: () => number; /** Wait `ms` (real in production, virtual in tests). */
+  sleep: (ms: number) => Promise<void>;
+  logger?: {
+    info?: (m: string) => void;
+  };
+};
+type DrainOptions = {
+  /** Max wall-clock time to await in-flight jobs before requeuing stragglers. */drainTimeoutMs: number; /** How often to re-count in-flight jobs while draining. */
+  pollIntervalMs: number;
+};
+type DrainResult = {
+  inFlightAtStart: number;
+  remaining: number;
+  requeued: number;
+  timedOut: boolean;
+};
+/**
+ * Run the graceful-drain sequence: stop claiming, await this node's in-flight jobs up
+ * to a wall-clock budget, requeue any stragglers, release leadership, and destroy. The
+ * clock (`now`/`sleep`) is injected so tests drive it deterministically without real
+ * waiting. Always releases leadership and destroys, even when nothing was in flight.
+ */
+declare const drainWorker: (deps: DrainDeps, options: DrainOptions) => Promise<DrainResult>;
+//#endregion
+export { DrainDeps, DrainOptions, DrainResult, drainWorker };
+//# sourceMappingURL=drain.d.ts.map

package/dist/execution/drain.js

@@ -0,0 +1,33 @@
+//#region src/execution/drain.ts
+/**
+* Run the graceful-drain sequence: stop claiming, await this node's in-flight jobs up
+* to a wall-clock budget, requeue any stragglers, release leadership, and destroy. The
+* clock (`now`/`sleep`) is injected so tests drive it deterministically without real
+* waiting. Always releases leadership and destroys, even when nothing was in flight.
+*/
+const drainWorker = async (deps, options) => {
+	deps.stopLoops();
+	await deps.releaseLeadership();
+	const start = deps.now();
+	const inFlightAtStart = await deps.countInFlight();
+	let remaining = inFlightAtStart;
+	while (remaining > 0 && deps.now() - start < options.drainTimeoutMs) {
+		await deps.sleep(options.pollIntervalMs);
+		if (deps.now() - start >= options.drainTimeoutMs) break;
+		remaining = await deps.countInFlight();
+	}
+	const timedOut = remaining > 0;
+	const requeued = timedOut ? await deps.requeueStragglers() : 0;
+	await deps.destroy();
+	deps.logger?.info?.(`@10x-media/jobs: drain complete (started ${inFlightAtStart}, requeued ${requeued}, timedOut ${timedOut})`);
+	return {
+		inFlightAtStart,
+		remaining,
+		requeued,
+		timedOut
+	};
+};
+//#endregion
+export { drainWorker };
+
+//# sourceMappingURL=drain.js.map

package/dist/execution/drain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"drain.js","names":[],"sources":["../../src/execution/drain.ts"],"sourcesContent":["export type DrainDeps = {\n\t/** Stop the worker's interval loops (stop claiming new jobs). */\n\tstopLoops: () => void\n\t/** Count this node's in-flight jobs (processing and claimed by it). */\n\tcountInFlight: () => Promise<number>\n\t/** Requeue this node's remaining in-flight jobs. Returns how many were released. */\n\trequeueStragglers: () => Promise<number>\n\t/** Release the held scheduler and sweeper leadership leases. */\n\treleaseLeadership: () => Promise<void>\n\t/** Destroy the Payload instance (stops crons, closes the DB). */\n\tdestroy: () => Promise<void>\n\t/** Wall-clock milliseconds (real in production, virtual in tests). */\n\tnow: () => number\n\t/** Wait `ms` (real in production, virtual in tests). */\n\tsleep: (ms: number) => Promise<void>\n\tlogger?: { info?: (m: string) => void }\n}\n\nexport type DrainOptions = {\n\t/** Max wall-clock time to await in-flight jobs before requeuing stragglers. */\n\tdrainTimeoutMs: number\n\t/** How often to re-count in-flight jobs while draining. */\n\tpollIntervalMs: number\n}\n\nexport type DrainResult = {\n\tinFlightAtStart: number\n\tremaining: number\n\trequeued: number\n\ttimedOut: boolean\n}\n\n/**\n * Run the graceful-drain sequence: stop claiming, await this node's in-flight jobs up\n * to a wall-clock budget, requeue any stragglers, release leadership, and destroy. The\n * clock (`now`/`sleep`) is injected so tests drive it deterministically without real\n * waiting. Always releases leadership and destroys, even when nothing was in flight.\n */\nexport const drainWorker = async (deps: DrainDeps, options: DrainOptions): Promise<DrainResult> => {\n\tdeps.stopLoops()\n\t// Release leadership before the polling loop so other nodes can elect a new\n\t// leader during the drain window rather than waiting for the full timeout.\n\tawait deps.releaseLeadership()\n\tconst start = deps.now()\n\tconst inFlightAtStart = await deps.countInFlight()\n\tlet remaining = inFlightAtStart\n\twhile (remaining > 0 && deps.now() - start < options.drainTimeoutMs) {\n\t\tawait deps.sleep(options.pollIntervalMs)\n\t\tif (deps.now() - start >= options.drainTimeoutMs) {\n\t\t\tbreak\n\t\t}\n\t\tremaining = await deps.countInFlight()\n\t}\n\tconst timedOut = remaining > 0\n\t// Only on timeout, to abandon still-running handlers. On a clean drain a just-finished\n\t// job can still read processing:true before its completion write lands; requeuing it\n\t// would bump recoveryAttempts and re-run it. The sweeper recovers genuine orphans.\n\tconst requeued = timedOut ? await deps.requeueStragglers() : 0\n\tawait deps.destroy()\n\tdeps.logger?.info?.(\n\t\t`@10x-media/jobs: drain complete (started ${inFlightAtStart}, requeued ${requeued}, timedOut ${timedOut})`\n\t)\n\treturn { inFlightAtStart, remaining, requeued, timedOut }\n}\n"],"mappings":";;;;;;;AAsCA,MAAa,cAAc,OAAO,MAAiB,YAAgD;CAClG,KAAK,UAAU;CAGf,MAAM,KAAK,kBAAkB;CAC7B,MAAM,QAAQ,KAAK,IAAI;CACvB,MAAM,kBAAkB,MAAM,KAAK,cAAc;CACjD,IAAI,YAAY;CAChB,OAAO,YAAY,KAAK,KAAK,IAAI,IAAI,QAAQ,QAAQ,gBAAgB;EACpE,MAAM,KAAK,MAAM,QAAQ,cAAc;EACvC,IAAI,KAAK,IAAI,IAAI,SAAS,QAAQ,gBACjC;EAED,YAAY,MAAM,KAAK,cAAc;CACtC;CACA,MAAM,WAAW,YAAY;CAI7B,MAAM,WAAW,WAAW,MAAM,KAAK,kBAAkB,IAAI;CAC7D,MAAM,KAAK,QAAQ;CACnB,KAAK,QAAQ,OACZ,4CAA4C,gBAAgB,aAAa,SAAS,aAAa,SAAS,EACzG;CACA,OAAO;EAAE;EAAiB;EAAW;EAAU;CAAS;AACzD"}

package/dist/execution/inFlight.js

@@ -0,0 +1,36 @@
+//#region src/execution/inFlight.ts
+/**
+* Create a process-local in-flight counter. One counter is created per worker
+* instance and shared across all heartbeat wrappers running in that worker.
+* Uses a simple closure rather than a DB query, which is cheaper and immune to
+* TOCTOU races on the `claimedBy` field between heartbeat renewals.
+*/
+const createInFlightCounter = () => {
+	let n = 0;
+	return {
+		count: () => n,
+		decrement: () => {
+			n--;
+		},
+		increment: () => {
+			n++;
+		}
+	};
+};
+const registry = /* @__PURE__ */ new Map();
+/** Register or retrieve the counter for `ownerId`. Creates one on first call. */
+const getOrCreateCounter = (ownerId) => {
+	const hit = registry.get(ownerId);
+	if (hit) return hit;
+	const c = createInFlightCounter();
+	registry.set(ownerId, c);
+	return c;
+};
+/** Remove the counter for `ownerId` (call on worker teardown to avoid leaks in tests). */
+const releaseCounter = (ownerId) => {
+	registry.delete(ownerId);
+};
+//#endregion
+export { getOrCreateCounter, releaseCounter };
+
+//# sourceMappingURL=inFlight.js.map

package/dist/execution/inFlight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inFlight.js","names":[],"sources":["../../src/execution/inFlight.ts"],"sourcesContent":["/** A process-local counter for jobs currently executing on this node. */\nexport type InFlightCounter = {\n\tincrement: () => void\n\tdecrement: () => void\n\tcount: () => number\n}\n\n/**\n * Create a process-local in-flight counter. One counter is created per worker\n * instance and shared across all heartbeat wrappers running in that worker.\n * Uses a simple closure rather than a DB query, which is cheaper and immune to\n * TOCTOU races on the `claimedBy` field between heartbeat renewals.\n */\nexport const createInFlightCounter = (): InFlightCounter => {\n\tlet n = 0\n\treturn {\n\t\tcount: () => n,\n\t\tdecrement: () => {\n\t\t\tn--\n\t\t},\n\t\tincrement: () => {\n\t\t\tn++\n\t\t},\n\t}\n}\n\n// Registry so the heartbeat wrappers (registered at plugin config time) and the\n// worker (created at runtime) can share the same counter without explicit wiring.\nconst registry = new Map<string, InFlightCounter>()\n\n/** Register or retrieve the counter for `ownerId`. Creates one on first call. */\nexport const getOrCreateCounter = (ownerId: string): InFlightCounter => {\n\tconst hit = registry.get(ownerId)\n\tif (hit) {\n\t\treturn hit\n\t}\n\tconst c = createInFlightCounter()\n\tregistry.set(ownerId, c)\n\treturn c\n}\n\n/** Remove the counter for `ownerId` (call on worker teardown to avoid leaks in tests). */\nexport const releaseCounter = (ownerId: string): void => {\n\tregistry.delete(ownerId)\n}\n"],"mappings":";;;;;;;AAaA,MAAa,8BAA+C;CAC3D,IAAI,IAAI;CACR,OAAO;EACN,aAAa;EACb,iBAAiB;GAChB;EACD;EACA,iBAAiB;GAChB;EACD;CACD;AACD;AAIA,MAAM,2BAAW,IAAI,IAA6B;;AAGlD,MAAa,sBAAsB,YAAqC;CACvE,MAAM,MAAM,SAAS,IAAI,OAAO;CAChC,IAAI,KACH,OAAO;CAER,MAAM,IAAI,sBAAsB;CAChC,SAAS,IAAI,SAAS,CAAC;CACvB,OAAO;AACR;;AAGA,MAAa,kBAAkB,YAA0B;CACxD,SAAS,OAAO,OAAO;AACxB"}

package/dist/execution/signals.js

@@ -0,0 +1,31 @@
+//#region src/execution/signals.ts
+let handlersInstalled = false;
+/** Whether signal handlers have been installed in this process (module-level flag). */
+const areHandlersInstalled = () => handlersInstalled;
+/**
+* Register `handler` for each signal and return a cleanup that removes them. The
+* handler fires at most once across all signals (a second signal during drain is
+* ignored). Payload installs no signal handlers of its own, so these never conflict.
+* `target` defaults to `process`; tests pass an EventEmitter.
+*/
+const installSignalHandlers = (signals, handler, target = process) => {
+	handlersInstalled = true;
+	let fired = false;
+	const registered = signals.map((signal) => {
+		const listener = () => {
+			if (fired) return;
+			fired = true;
+			handler(signal);
+		};
+		target.on(signal, listener);
+		return [signal, listener];
+	});
+	return () => {
+		handlersInstalled = false;
+		for (const [signal, listener] of registered) target.removeListener(signal, listener);
+	};
+};
+//#endregion
+export { areHandlersInstalled, installSignalHandlers };
+
+//# sourceMappingURL=signals.js.map

package/dist/execution/signals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signals.js","names":[],"sources":["../../src/execution/signals.ts"],"sourcesContent":["let handlersInstalled = false\n\n/** Whether signal handlers have been installed in this process (module-level flag). */\nexport const areHandlersInstalled = (): boolean => handlersInstalled\n\n/** Reset the installed-handlers flag. Only for use in tests between worker instantiations. */\nexport const resetHandlersInstalled = (): void => {\n\thandlersInstalled = false\n}\n\n/** The subset of `process` the signal installer needs (injectable for tests). */\nexport type SignalTarget = {\n\ton: (signal: NodeJS.Signals, listener: () => void) => unknown\n\tremoveListener: (signal: NodeJS.Signals, listener: () => void) => unknown\n}\n\nexport type SignalCleanup = () => void\n\n/**\n * Register `handler` for each signal and return a cleanup that removes them. The\n * handler fires at most once across all signals (a second signal during drain is\n * ignored). Payload installs no signal handlers of its own, so these never conflict.\n * `target` defaults to `process`; tests pass an EventEmitter.\n */\nexport const installSignalHandlers = (\n\tsignals: NodeJS.Signals[],\n\thandler: (signal: NodeJS.Signals) => void,\n\ttarget: SignalTarget = process\n): SignalCleanup => {\n\thandlersInstalled = true\n\tlet fired = false\n\tconst registered = signals.map((signal) => {\n\t\tconst listener = () => {\n\t\t\tif (fired) {\n\t\t\t\treturn\n\t\t\t}\n\t\t\tfired = true\n\t\t\thandler(signal)\n\t\t}\n\t\ttarget.on(signal, listener)\n\t\treturn [signal, listener] as const\n\t})\n\treturn () => {\n\t\thandlersInstalled = false\n\t\tfor (const [signal, listener] of registered) {\n\t\t\ttarget.removeListener(signal, listener)\n\t\t}\n\t}\n}\n"],"mappings":";AAAA,IAAI,oBAAoB;;AAGxB,MAAa,6BAAsC;;;;;;;AAqBnD,MAAa,yBACZ,SACA,SACA,SAAuB,YACJ;CACnB,oBAAoB;CACpB,IAAI,QAAQ;CACZ,MAAM,aAAa,QAAQ,KAAK,WAAW;EAC1C,MAAM,iBAAiB;GACtB,IAAI,OACH;GAED,QAAQ;GACR,QAAQ,MAAM;EACf;EACA,OAAO,GAAG,QAAQ,QAAQ;EAC1B,OAAO,CAAC,QAAQ,QAAQ;CACzB,CAAC;CACD,aAAa;EACZ,oBAAoB;EACpB,KAAK,MAAM,CAAC,QAAQ,aAAa,YAChC,OAAO,eAAe,QAAQ,QAAQ;CAExC;AACD"}