@terreno/jobs 57.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Flourish Health, Inc.
+
+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,56 @@
+# @terreno/jobs
+
+Durable background jobs for Terreno backends — Mongo-backed queues with pluggable
+runners, retries, schedules, dead letters, and admin operations.
+
+## Install
+
+```bash
+bun add @terreno/jobs
+```
+
+Peer dependency: `mongoose ^8.0.0 || ^9.0.0`. Optional peers for cloud runners:
+`@google-cloud/tasks`, `@vercel/queue`.
+
+## Quick start
+
+```typescript
+import {JobsApp, MongoJobRunner, getJobsService} from "@terreno/jobs";
+import {TerrenoApp} from "@terreno/api";
+import {User} from "./models/user";
+
+const jobsApp = new JobsApp({runner: new MongoJobRunner()});
+
+jobsApp.define("my/task", {
+  handler: async (_payload, ctx) => {
+    ctx.log.info("running");
+  },
+});
+
+new TerrenoApp({userModel: User}).register(jobsApp).start();
+
+await jobsApp.startWorker();
+await getJobsService().enqueue({name: "my/task", payload: {}});
+```
+
+`JobsApp.register()` does not start a worker. Call `startWorker()` from the API
+process or a dedicated worker entrypoint.
+
+## What's included
+
+- `JobsApp` — TerrenoPlugin for definitions, admin routes, and optional execute HTTP
+- `MongoJobRunner` — default in-process poll loop over MongoDB
+- `GcpCloudTasksRunner` — `@terreno/jobs/runners/gcpCloudTasks`
+- `VercelQueuesRunner` — `@terreno/jobs/runners/vercelQueues`
+- Admin list/detail, retry, requeue, cancel, stats, and schedules
+- Retries with backoff, delayed enqueue, cron schedules, and dead-letter rows
+
+## Documentation
+
+Full API reference: [docs/reference/jobs.md](https://github.com/flourishhealth/terreno/blob/master/docs/reference/jobs.md)
+
+Operator guide: [docs/how-to/background-jobs.md](https://github.com/flourishhealth/terreno/blob/master/docs/how-to/background-jobs.md)
+
+## License and Contributing
+
+Licensed under the [MIT License](https://github.com/FlourishHealth/terreno/blob/master/LICENSE). See [CONTRIBUTING.md](https://github.com/FlourishHealth/terreno/blob/master/CONTRIBUTING.md) for contribution guidelines.

package/biome.jsonc

@@ -0,0 +1,20 @@
+{
+  "$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
+  "extends": ["../biome.jsonc"],
+  "files": {
+    "includes": [
+      "package.json",
+      "src/**/*.ts",
+      "src/**/*.tsx",
+      "!!**/node_modules",
+      "!!node_modules",
+      "!!**/dist",
+      "!!dist",
+      "!!**/build",
+      "!!build",
+      "!!**/coverage",
+      "!!coverage"
+    ]
+  },
+  "root": true
+}

package/bunfig.toml

@@ -0,0 +1,5 @@
+[test]
+preload = ["./src/tests/bunSetup.ts"]
+root = "./src"
+coveragePathIgnorePatterns = ["**/dist/**", "**/*.test.ts", "**/tests/**", "**/node_modules/**", "../**"]
+coverageThreshold = { line = 95, function = 95 }

package/dist/activeJobExecution.d.ts

@@ -0,0 +1,3 @@
+export declare const beginActiveJobExecution: (jobId: string, parentSignal: AbortSignal) => AbortSignal;
+export declare const endActiveJobExecution: (jobId: string) => void;
+export declare const abortActiveJobExecution: (jobId: string) => boolean;

package/dist/activeJobExecution.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.abortActiveJobExecution = exports.endActiveJobExecution = exports.beginActiveJobExecution = void 0;
+var activeExecutions = new Map();
+var beginActiveJobExecution = function (jobId, parentSignal) {
+    var controller = new AbortController();
+    activeExecutions.set(jobId, controller);
+    if (parentSignal.aborted) {
+        controller.abort();
+    }
+    else {
+        parentSignal.addEventListener("abort", function () { return controller.abort(); }, { once: true });
+    }
+    return controller.signal;
+};
+exports.beginActiveJobExecution = beginActiveJobExecution;
+var endActiveJobExecution = function (jobId) {
+    activeExecutions.delete(jobId);
+};
+exports.endActiveJobExecution = endActiveJobExecution;
+var abortActiveJobExecution = function (jobId) {
+    var controller = activeExecutions.get(jobId);
+    if (!controller) {
+        return false;
+    }
+    controller.abort();
+    return true;
+};
+exports.abortActiveJobExecution = abortActiveJobExecution;

package/dist/claimLock.d.ts

@@ -0,0 +1,16 @@
+import type { JobDocument } from "./modelTypes";
+/** @internal */
+export declare const getWorkerId: () => string;
+export interface JobClaimLock {
+    lockedAt: Date;
+    lockedBy: string;
+}
+export declare const createClaimLock: (lockedAt: Date) => JobClaimLock;
+export declare const buildClaimOwnershipFilter: (jobId: JobDocument["_id"], claim: JobClaimLock) => {
+    _id: JobDocument["_id"];
+    lockedAt: Date;
+    lockedBy: string;
+};
+/** @internal */
+export declare const hasWorkerIdPrefix: (lockedBy: string | undefined) => boolean;
+export declare const isAbortError: (error: unknown) => boolean;

package/dist/claimLock.js

@@ -0,0 +1,34 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isAbortError = exports.hasWorkerIdPrefix = exports.buildClaimOwnershipFilter = exports.createClaimLock = exports.getWorkerId = void 0;
+var node_crypto_1 = require("node:crypto");
+var node_os_1 = __importDefault(require("node:os"));
+/** @internal */
+var getWorkerId = function () { return "".concat(node_os_1.default.hostname(), ":").concat(process.pid); };
+exports.getWorkerId = getWorkerId;
+var createClaimLock = function (lockedAt) { return ({
+    lockedAt: lockedAt,
+    lockedBy: "".concat((0, exports.getWorkerId)(), ":").concat((0, node_crypto_1.randomUUID)()),
+}); };
+exports.createClaimLock = createClaimLock;
+var buildClaimOwnershipFilter = function (jobId, claim) { return ({
+    _id: jobId,
+    lockedAt: claim.lockedAt,
+    lockedBy: claim.lockedBy,
+}); };
+exports.buildClaimOwnershipFilter = buildClaimOwnershipFilter;
+/** @internal */
+var hasWorkerIdPrefix = function (lockedBy) {
+    if (!lockedBy) {
+        return false;
+    }
+    return lockedBy.startsWith("".concat((0, exports.getWorkerId)(), ":"));
+};
+exports.hasWorkerIdPrefix = hasWorkerIdPrefix;
+var isAbortError = function (error) {
+    return error instanceof Error && error.name === "AbortError";
+};
+exports.isAbortError = isAbortError;

package/dist/dispatchCompensation.d.ts

@@ -0,0 +1,3 @@
+import type { JobDocument } from "./modelTypes";
+import type { JobRunner } from "./types";
+export declare const dispatchJobToRunner: (runner: JobRunner, job: JobDocument) => Promise<void>;

package/dist/dispatchCompensation.js

@@ -0,0 +1,89 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dispatchJobToRunner = void 0;
+var api_1 = require("@terreno/api");
+var dispatchError_1 = require("./dispatchError");
+var job_1 = require("./models/job");
+var removeUntouchedPendingJob = function (jobId) { return __awaiter(void 0, void 0, void 0, function () {
+    var removed;
+    return __generator(this, function (_a) {
+        switch (_a.label) {
+            case 0: return [4 /*yield*/, job_1.Job.findOneAndDelete({
+                    _id: jobId,
+                    $and: [
+                        { $or: [{ lockedAt: { $exists: false } }, { lockedAt: null }] },
+                        { $or: [{ lockedBy: { $exists: false } }, { lockedBy: null }] },
+                    ],
+                    attemptCount: 0,
+                    status: "pending",
+                })];
+            case 1:
+                removed = _a.sent();
+                return [2 /*return*/, removed !== null];
+        }
+    });
+}); };
+var dispatchJobToRunner = function (runner, job) { return __awaiter(void 0, void 0, void 0, function () {
+    var error_1, compensationSucceeded;
+    return __generator(this, function (_a) {
+        switch (_a.label) {
+            case 0:
+                _a.trys.push([0, 2, , 4]);
+                return [4 /*yield*/, runner.enqueue(job)];
+            case 1:
+                _a.sent();
+                return [3 /*break*/, 4];
+            case 2:
+                error_1 = _a.sent();
+                return [4 /*yield*/, removeUntouchedPendingJob(job._id)];
+            case 3:
+                compensationSucceeded = _a.sent();
+                if (!compensationSucceeded) {
+                    api_1.logger.error("[jobs] Dispatch failed for job ".concat(job._id.toString(), " and compensation lost race \u2014 row was already claimed or mutated"));
+                }
+                throw new dispatchError_1.JobDispatchError({
+                    cause: error_1,
+                    compensationSucceeded: compensationSucceeded,
+                    jobId: job._id.toString(),
+                });
+            case 4: return [2 /*return*/];
+        }
+    });
+}); };
+exports.dispatchJobToRunner = dispatchJobToRunner;

package/dist/dispatchError.d.ts

@@ -0,0 +1,10 @@
+export declare class JobDispatchError extends Error {
+    readonly cause: unknown;
+    readonly compensationSucceeded: boolean;
+    readonly jobId: string;
+    constructor(options: {
+        cause: unknown;
+        compensationSucceeded: boolean;
+        jobId: string;
+    });
+}

package/dist/dispatchError.js

@@ -0,0 +1,33 @@
+"use strict";
+var __extends = (this && this.__extends) || (function () {
+    var extendStatics = function (d, b) {
+        extendStatics = Object.setPrototypeOf ||
+            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
+            function (d, b) { for (var p in b) if (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };
+        return extendStatics(d, b);
+    };
+    return function (d, b) {
+        if (typeof b !== "function" && b !== null)
+            throw new TypeError("Class extends value " + String(b) + " is not a constructor or null");
+        extendStatics(d, b);
+        function __() { this.constructor = d; }
+        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JobDispatchError = void 0;
+var JobDispatchError = /** @class */ (function (_super) {
+    __extends(JobDispatchError, _super);
+    function JobDispatchError(options) {
+        var _this = this;
+        var detail = options.cause instanceof Error ? options.cause.message : String(options.cause);
+        _this = _super.call(this, "Job dispatch failed for ".concat(options.jobId, ": ").concat(detail)) || this;
+        _this.name = "JobDispatchError";
+        _this.cause = options.cause;
+        _this.compensationSucceeded = options.compensationSucceeded;
+        _this.jobId = options.jobId;
+        return _this;
+    }
+    return JobDispatchError;
+}(Error));
+exports.JobDispatchError = JobDispatchError;

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export type { JobsAppOptions } from "./jobsApp";
+export { JobsApp } from "./jobsApp";
+export { getJobsService, tryGetJobsService, unregisterJobsService } from "./jobsService";
+export { Job } from "./models/job";
+export { JobSchedule } from "./models/jobSchedule";
+export type { JobAttempt, JobDocument, JobModel, JobScheduleDocument, JobScheduleModel, JobStatus, } from "./modelTypes";
+export type { ExecuteAuthVerifier } from "./routes/jobsExecute";
+export { MongoJobRunner } from "./runners/mongoRunner";
+export type { EnqueueJobParams, JobDefinition, JobHandlerContext, JobRunner, JobRunnerStartOptions, JobScheduleDefinition, JobsRunnerHost, } from "./types";

package/dist/index.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MongoJobRunner = exports.JobSchedule = exports.Job = exports.unregisterJobsService = exports.tryGetJobsService = exports.getJobsService = exports.JobsApp = void 0;
+var jobsApp_1 = require("./jobsApp");
+Object.defineProperty(exports, "JobsApp", { enumerable: true, get: function () { return jobsApp_1.JobsApp; } });
+var jobsService_1 = require("./jobsService");
+Object.defineProperty(exports, "getJobsService", { enumerable: true, get: function () { return jobsService_1.getJobsService; } });
+Object.defineProperty(exports, "tryGetJobsService", { enumerable: true, get: function () { return jobsService_1.tryGetJobsService; } });
+Object.defineProperty(exports, "unregisterJobsService", { enumerable: true, get: function () { return jobsService_1.unregisterJobsService; } });
+var job_1 = require("./models/job");
+Object.defineProperty(exports, "Job", { enumerable: true, get: function () { return job_1.Job; } });
+var jobSchedule_1 = require("./models/jobSchedule");
+Object.defineProperty(exports, "JobSchedule", { enumerable: true, get: function () { return jobSchedule_1.JobSchedule; } });
+var mongoRunner_1 = require("./runners/mongoRunner");
+Object.defineProperty(exports, "MongoJobRunner", { enumerable: true, get: function () { return mongoRunner_1.MongoJobRunner; } });

package/dist/jobExecutor.d.ts

@@ -0,0 +1,34 @@
+import { type JobClaimLock } from "./claimLock";
+import type { JobDocument } from "./modelTypes";
+import type { JobDefinition } from "./types";
+export interface JobExecutionHost {
+    getDefinition(name: string): JobDefinition | undefined;
+    getLockTtlMs(): number;
+}
+export type ExecuteJobOutcome = {
+    job: JobDocument;
+    kind: "executed";
+} | {
+    job: JobDocument;
+    kind: "noop";
+} | {
+    kind: "conflict";
+    reason: "locked";
+} | {
+    kind: "conflict";
+    reason: "not_due";
+    runAt: Date;
+} | {
+    kind: "not_found";
+};
+export declare const runClaimedJob: ({ claim, host, job, signal, }: {
+    claim: JobClaimLock;
+    host: JobExecutionHost;
+    job: JobDocument;
+    signal: AbortSignal;
+}) => Promise<JobDocument>;
+export declare const executeJobById: ({ host, jobId, signal, }: {
+    host: JobExecutionHost;
+    jobId: string;
+    signal: AbortSignal;
+}) => Promise<ExecuteJobOutcome>;