@nest-native/jobs 0.1.0

package/dist/jobs.service.js

@@ -0,0 +1,55 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JobsService = void 0;
+const common_1 = require("@nestjs/common");
+const transactional_1 = require("@nestjs-cls/transactional");
+const tokens_1 = require("./tokens");
+/**
+ * Enqueues jobs **inside the caller's business transaction** — the job row
+ * commits atomically with your writes. Inject it into a `@Transactional()`
+ * service and call `enqueue` alongside your business writes; if the
+ * transaction rolls back, the job was never enqueued.
+ *
+ * `enqueue` returns the store's native shape: the **sqlite** store returns a
+ * synchronous `JobRow` (call it without `await` inside a synchronous
+ * `@Transactional` body); the **postgres** and **mysql** stores return a
+ * `Promise` (await it). Type the service as `JobsService<typeof yourStore>` to get the
+ * exact shape. On a `(name, uniqueKey)` collision with an ACTIVE job it
+ * returns that existing row — a dedup no-op.
+ *
+ * Requires the host app to configure `@nestjs-cls/transactional` with the
+ * Drizzle adapter (`enableTransactionProxy: true`) — `@InjectTransaction()`
+ * resolves the transaction-scoped Drizzle instance from it (and falls back to
+ * the base instance outside any transaction).
+ */
+let JobsService = class JobsService {
+    constructor(db, store) {
+        this.db = db;
+        this.store = store;
+    }
+    // TPayload keeps the input structural: a payload typed as a plain interface
+    // compiles without casting (see EnqueueJobInput). The store widens it internally.
+    enqueue(input) {
+        return this.store.enqueue(this.db, input);
+    }
+};
+exports.JobsService = JobsService;
+exports.JobsService = JobsService = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, transactional_1.InjectTransaction)()),
+    __param(1, (0, common_1.Inject)(tokens_1.JOBS_STORE)),
+    __metadata("design:paramtypes", [Object, Object])
+], JobsService);
+//# sourceMappingURL=jobs.service.js.map

package/dist/jobs.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jobs.service.js","sourceRoot":"","sources":["../jobs.service.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,2CAAoD;AACpD,6DAA8D;AAE9D,qCAAsC;AAEtC;;;;;;;;;;;;;;;;;GAiBG;AAEI,IAAM,WAAW,GAAjB,MAAM,WAAW;IACtB,YACwC,EAAW,EACZ,KAAa;QADZ,OAAE,GAAF,EAAE,CAAS;QACZ,UAAK,GAAL,KAAK,CAAQ;IACjD,CAAC;IAEJ,4EAA4E;IAC5E,kFAAkF;IAClF,OAAO,CACL,KAAgC;QAEhC,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,KAAK,CAAkC,CAAC;IAC7E,CAAC;CACF,CAAA;AAbY,kCAAW;sBAAX,WAAW;IADvB,IAAA,mBAAU,GAAE;IAGR,WAAA,IAAA,iCAAiB,GAAE,CAAA;IACnB,WAAA,IAAA,eAAM,EAAC,mBAAU,CAAC,CAAA;;GAHV,WAAW,CAavB"}

package/dist/testing/harness.d.ts

@@ -0,0 +1,61 @@
+import type { JobContext } from '../interfaces';
+import type { JobHandler } from '../job-handler.decorator';
+import type { JobsClaimer, TickReport } from '../jobs-claimer.service';
+import type { RunnerConfig } from '../interfaces';
+export interface DrainJobsOptions {
+    /** Runner overrides applied to every tick. */
+    runner?: RunnerConfig;
+    /**
+     * Safety valve: maximum ticks before giving up (default 100). Prevents a
+     * test from spinning forever when a job keeps retrying with no delay.
+     */
+    maxTicks?: number;
+}
+/**
+ * Ticks the claimer until a tick claims nothing, aggregating the reports —
+ * "run everything that is currently due" in one await:
+ *
+ * ```ts
+ * const report = await drainJobs(app.get(JobsClaimer));
+ * assert.equal(report.completed, 3);
+ * ```
+ *
+ * Note: jobs a tick reschedules into the future (retry backoff, delayMs) are
+ * not due, so a drain settles even while retries are pending — advance time
+ * (or wait) and drain again to run them.
+ */
+export declare function drainJobs(claimer: JobsClaimer, options?: DrainJobsOptions): Promise<TickReport>;
+/** One recorded handler execution. */
+export interface RecordedJobExecution {
+    payload: Record<string, unknown>;
+    ctx: JobContext;
+}
+/**
+ * A {@link JobHandler} implementation that records every execution and can be
+ * armed to fail — once (`failNextWith`, ideal for throw-then-succeed retry
+ * tests) or persistently (`failWith`). Executions are recorded BEFORE the
+ * failure is thrown, so `executions()` reflects every attempt the claimer made.
+ *
+ * Subclass it to attach the decorator:
+ *
+ * ```ts
+ * @JobHandler('email.welcome')
+ * class WelcomeHandler extends RecordingJobHandler {}
+ * ```
+ */
+export declare class RecordingJobHandler implements JobHandler {
+    private readonly records;
+    private readonly oneShotFailures;
+    private failure;
+    handle(payload: Record<string, unknown>, ctx: JobContext): void;
+    /** Queue `error` to be thrown by the NEXT execution only. */
+    failNextWith(error: Error): void;
+    /** Make every subsequent execution throw `error` until cleared. */
+    failWith(error: Error): void;
+    /** Stop failing; subsequent executions succeed again. */
+    clearFailure(): void;
+    /** Every execution so far, in order. */
+    executions(): readonly RecordedJobExecution[];
+    /** Clear recorded executions and any armed failures. */
+    reset(): void;
+}

package/dist/testing/harness.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RecordingJobHandler = void 0;
+exports.drainJobs = drainJobs;
+/**
+ * Ticks the claimer until a tick claims nothing, aggregating the reports —
+ * "run everything that is currently due" in one await:
+ *
+ * ```ts
+ * const report = await drainJobs(app.get(JobsClaimer));
+ * assert.equal(report.completed, 3);
+ * ```
+ *
+ * Note: jobs a tick reschedules into the future (retry backoff, delayMs) are
+ * not due, so a drain settles even while retries are pending — advance time
+ * (or wait) and drain again to run them.
+ */
+async function drainJobs(claimer, options = {}) {
+    const maxTicks = options.maxTicks ?? 100;
+    const total = { claimed: 0, completed: 0, retried: 0, failed: 0 };
+    for (let tick = 0; tick < maxTicks; tick += 1) {
+        const report = await claimer.tick(options.runner);
+        total.claimed += report.claimed;
+        total.completed += report.completed;
+        total.retried += report.retried;
+        total.failed += report.failed;
+        if (report.claimed === 0) {
+            return total;
+        }
+    }
+    throw new Error(`drainJobs did not settle after ${maxTicks} ticks — a job is likely being ` +
+        'retried with no delay. Raise maxTicks or fix the handler.');
+}
+/**
+ * A {@link JobHandler} implementation that records every execution and can be
+ * armed to fail — once (`failNextWith`, ideal for throw-then-succeed retry
+ * tests) or persistently (`failWith`). Executions are recorded BEFORE the
+ * failure is thrown, so `executions()` reflects every attempt the claimer made.
+ *
+ * Subclass it to attach the decorator:
+ *
+ * ```ts
+ * @JobHandler('email.welcome')
+ * class WelcomeHandler extends RecordingJobHandler {}
+ * ```
+ */
+class RecordingJobHandler {
+    constructor() {
+        this.records = [];
+        this.oneShotFailures = [];
+    }
+    handle(payload, ctx) {
+        this.records.push({ payload, ctx });
+        const oneShot = this.oneShotFailures.shift();
+        if (oneShot) {
+            throw oneShot;
+        }
+        if (this.failure) {
+            throw this.failure;
+        }
+    }
+    /** Queue `error` to be thrown by the NEXT execution only. */
+    failNextWith(error) {
+        this.oneShotFailures.push(error);
+    }
+    /** Make every subsequent execution throw `error` until cleared. */
+    failWith(error) {
+        this.failure = error;
+    }
+    /** Stop failing; subsequent executions succeed again. */
+    clearFailure() {
+        this.failure = undefined;
+        this.oneShotFailures.length = 0;
+    }
+    /** Every execution so far, in order. */
+    executions() {
+        return this.records;
+    }
+    /** Clear recorded executions and any armed failures. */
+    reset() {
+        this.records.length = 0;
+        this.clearFailure();
+    }
+}
+exports.RecordingJobHandler = RecordingJobHandler;
+//# sourceMappingURL=harness.js.map

package/dist/testing/harness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"harness.js","sourceRoot":"","sources":["../../testing/harness.ts"],"names":[],"mappings":";;;AA+BA,8BAoBC;AAjCD;;;;;;;;;;;;GAYG;AACI,KAAK,UAAU,SAAS,CAC7B,OAAoB,EACpB,UAA4B,EAAE;IAE9B,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,GAAG,CAAC;IACzC,MAAM,KAAK,GAAe,EAAE,OAAO,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;IAC9E,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,QAAQ,EAAE,IAAI,IAAI,CAAC,EAAE,CAAC;QAC9C,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAClD,KAAK,CAAC,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC;QAChC,KAAK,CAAC,SAAS,IAAI,MAAM,CAAC,SAAS,CAAC;QACpC,KAAK,CAAC,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC;QAChC,KAAK,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,CAAC;QAC9B,IAAI,MAAM,CAAC,OAAO,KAAK,CAAC,EAAE,CAAC;YACzB,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IACD,MAAM,IAAI,KAAK,CACb,kCAAkC,QAAQ,iCAAiC;QACzE,2DAA2D,CAC9D,CAAC;AACJ,CAAC;AAQD;;;;;;;;;;;;GAYG;AACH,MAAa,mBAAmB;IAAhC;QACmB,YAAO,GAA2B,EAAE,CAAC;QACrC,oBAAe,GAAY,EAAE,CAAC;IAwCjD,CAAC;IArCC,MAAM,CAAC,OAAgC,EAAE,GAAe;QACtD,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC;QACpC,MAAM,OAAO,GAAG,IAAI,CAAC,eAAe,CAAC,KAAK,EAAE,CAAC;QAC7C,IAAI,OAAO,EAAE,CAAC;YACZ,MAAM,OAAO,CAAC;QAChB,CAAC;QACD,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,MAAM,IAAI,CAAC,OAAO,CAAC;QACrB,CAAC;IACH,CAAC;IAED,6DAA6D;IAC7D,YAAY,CAAC,KAAY;QACvB,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACnC,CAAC;IAED,mEAAmE;IACnE,QAAQ,CAAC,KAAY;QACnB,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;IACvB,CAAC;IAED,yDAAyD;IACzD,YAAY;QACV,IAAI,CAAC,OAAO,GAAG,SAAS,CAAC;QACzB,IAAI,CAAC,eAAe,CAAC,MAAM,GAAG,CAAC,CAAC;IAClC,CAAC;IAED,wCAAwC;IACxC,UAAU;QACR,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,wDAAwD;IACxD,KAAK;QACH,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;QACxB,IAAI,CAAC,YAAY,EAAE,CAAC;IACtB,CAAC;CACF;AA1CD,kDA0CC"}

package/dist/testing/index.d.ts

@@ -0,0 +1 @@
+export * from './harness';

package/dist/testing/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// @nest-native/jobs/testing — hermetic helpers for testing job flows.
+__exportStar(require("./harness"), exports);
+//# sourceMappingURL=index.js.map

package/dist/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../testing/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,sEAAsE;AACtE,4CAA0B"}

package/dist/tokens.d.ts

@@ -0,0 +1,10 @@
+/** The dialect-specific {@link JobStore} provided to `JobsModule`. */
+export declare const JOBS_STORE: unique symbol;
+/**
+ * The base (non-transactional) Drizzle instance the claimer opens its own
+ * transaction on. `JobsModule` aliases this to the user-supplied
+ * `drizzleInstanceToken`.
+ */
+export declare const JOBS_DRIZZLE: unique symbol;
+/** The resolved {@link JobsModuleOptions}. */
+export declare const JOBS_OPTIONS: unique symbol;

package/dist/tokens.js

@@ -0,0 +1,15 @@
+"use strict";
+// DI tokens for the jobs engine.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JOBS_OPTIONS = exports.JOBS_DRIZZLE = exports.JOBS_STORE = void 0;
+/** The dialect-specific {@link JobStore} provided to `JobsModule`. */
+exports.JOBS_STORE = Symbol.for('@nest-native/jobs:store');
+/**
+ * The base (non-transactional) Drizzle instance the claimer opens its own
+ * transaction on. `JobsModule` aliases this to the user-supplied
+ * `drizzleInstanceToken`.
+ */
+exports.JOBS_DRIZZLE = Symbol.for('@nest-native/jobs:drizzle');
+/** The resolved {@link JobsModuleOptions}. */
+exports.JOBS_OPTIONS = Symbol.for('@nest-native/jobs:options');
+//# sourceMappingURL=tokens.js.map

package/dist/tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../tokens.ts"],"names":[],"mappings":";AAAA,iCAAiC;;;AAEjC,sEAAsE;AACzD,QAAA,UAAU,GAAG,MAAM,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAAC;AAEhE;;;;GAIG;AACU,QAAA,YAAY,GAAG,MAAM,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC;AAEpE,8CAA8C;AACjC,QAAA,YAAY,GAAG,MAAM,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,107 @@
+{
+  "name": "@nest-native/jobs",
+  "version": "0.1.0",
+  "description": "Background jobs for NestJS without Redis — a Drizzle-backed job queue (SQLite, Postgres + MySQL) with transactional enqueue, retries, delayed and unique jobs",
+  "keywords": [
+    "nestjs",
+    "jobs",
+    "background-jobs",
+    "job-queue",
+    "queue",
+    "worker",
+    "task-queue",
+    "delayed-jobs",
+    "drizzle",
+    "sqlite",
+    "postgres",
+    "mysql",
+    "typescript"
+  ],
+  "author": "Rodrigo Nogueira",
+  "license": "MIT",
+  "homepage": "https://github.com/nest-native/jobs#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nest-native/jobs.git",
+    "directory": "packages/jobs"
+  },
+  "bugs": {
+    "url": "https://github.com/nest-native/jobs/issues"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./sqlite": {
+      "types": "./dist/dialects/sqlite/index.d.ts",
+      "require": "./dist/dialects/sqlite/index.js",
+      "default": "./dist/dialects/sqlite/index.js"
+    },
+    "./postgres": {
+      "types": "./dist/dialects/postgres/index.d.ts",
+      "require": "./dist/dialects/postgres/index.js",
+      "default": "./dist/dialects/postgres/index.js"
+    },
+    "./mysql": {
+      "types": "./dist/dialects/mysql/index.d.ts",
+      "require": "./dist/dialects/mysql/index.js",
+      "default": "./dist/dialects/mysql/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "require": "./dist/testing/index.js",
+      "default": "./dist/testing/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/**/*.d.ts",
+    "dist/**/*.js",
+    "dist/**/*.js.map"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "clean": "rimraf dist tsconfig.tsbuildinfo",
+    "build": "npm run clean && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "@nestjs-cls/transactional": "^3.0.0",
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/core": "^11.0.0",
+    "better-sqlite3": "^11.0.0 || ^12.0.0",
+    "drizzle-orm": "^0.44.0 || ^0.45.0",
+    "mysql2": "^3.0.0",
+    "pg": "^8.0.0",
+    "reflect-metadata": "^0.1.12 || ^0.2.0",
+    "rxjs": "^7.0.0"
+  },
+  "peerDependenciesMeta": {
+    "better-sqlite3": {
+      "optional": true
+    },
+    "mysql2": {
+      "optional": true
+    },
+    "pg": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@nestjs/common": "^11.1.27",
+    "@nestjs/core": "^11.1.27",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.1",
+    "typescript": "^6.0.3"
+  }
+}