@nest-boot/queue-api 0.0.0-stage → 8.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 nest-boot
+
+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

@@ -1,3 +1,116 @@
-# Temporary Holding Version
+# @nest-boot/queue-api
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Optional Job history and authenticated GraphQL queries for
+[`@nest-boot/queue`](../queue/README.md). Redis remains responsible for queue state
+and processing; the database stores asynchronous history snapshots.
+
+## Setup and visibility
+
+Configure the application's global DatabaseModule, GraphQLModule and AuthModule,
+then import QueueApiModule. It reuses those configured modules, imports QueueModule
+and does not depend on `@nest-boot/schedule`. Register JobEntity in both runtime
+and MikroORM CLI entity lists and create its table through application migrations.
+The database generates UUID IDs; `(queue, jobId)` identifies the source Redis job.
+
+Register queue providers in the API application and mark each visible queue:
+
+```ts
+import { BaseQueue, Queue } from "@nest-boot/queue";
+import { QueueApiModule, QueueVisible } from "@nest-boot/queue-api";
+import { Module } from "@nestjs/common";
+
+@QueueVisible()
+@Queue()
+export class EmailQueue extends BaseQueue {}
+
+@Module({
+  imports: [QueueApiModule],
+  providers: [EmailQueue],
+})
+export class EmailModule {}
+```
+
+`@QueueVisible()` takes no arguments. Each concrete class needs its own marker;
+subclasses do not inherit visibility. Unmarked or unregistered queues are excluded
+from single-record reads, page nodes and counts, including explicit client
+filters. An empty visible set returns no records. Visibility does not change
+synchronization, retention or authorization.
+
+## Queries and authorization
+
+Every query uses AuthGuard. JobService reads trusted request identity and applies
+the same visibility and ownership constraints to single records, pages and counts:
+
+| Query                            | Access scope                                                                              |
+| -------------------------------- | ----------------------------------------------------------------------------------------- |
+| `userJob` / `userJobs`           | `data.userId` matches the current user                                                    |
+| `workspaceJob` / `workspaceJobs` | `data.workspaceId` matches the selected workspace after membership and read authorization |
+| `systemJob` / `systemJobs`       | Both owner fields are absent or JSON null, with administrator authorization               |
+
+System reads use AuthModule's configured `user.adminRoles`. API keys do not inherit
+their owner's administrator access. Empty strings count as present owner values.
+User and workspace scopes can overlap when a task carries both IDs. Missing
+identity or unauthorized workspace access is rejected.
+
+JobService exposes `getUserJob`, `getWorkspaceJob`, `getSystemJob` and their
+`get*JobConnection` variants. It injects EntityManager directly and exposes no
+generic CRUD or unscoped query. Job history has no database RLS; direct ORM access
+is a trusted internal operation, so request handlers use the scoped methods.
+
+GraphQL exposes `id`, `queue`, `name`, `status`, finite numeric `progress`,
+`createdAt`, `startedAt` and `finishedAt`. Other progress values return null.
+Payloads, results, errors, native job IDs and event versions remain private.
+Connections support queue, name, status and creation-time filters. CREATED_AT is
+the only selectable sort key and defaults to descending; UUID breaks timestamp
+ties internally. User/workspace expression indexes and a partial system index
+support these scoped cursor reads.
+
+## Synchronization and retention
+
+JobService subscribes to registered queues before their event readers start,
+including producer-only instances. It forwards snapshots to the built-in `job`
+queue, deduplicating qualified source names and Redis Stream IDs for 24 hours.
+The Job worker compares bigint `(lastEventMs, lastEventSeq)` pairs atomically and
+only applies newer events. Events from its own queue are excluded to prevent
+recursion. Database write failures retry up to 20 times with exponential backoff.
+
+Readers use BullMQ's default starting position without startup replay. Connection
+readiness does not guarantee that the first stream read has started. Retain source
+jobs long enough to capture full snapshots; when a source job is already removed,
+only metadata carried by the event remains available.
+
+Start all registered consumers with `nb queue:start`, or use
+`nb queue:start --queue job` for synchronization and cleanup alone. When filtering,
+select `job` explicitly in the process intended to persist history. Shutdown drains
+source Workers, then event readers and pending submissions, then the Job Worker.
+
+The built-in JobQueue handles `sync` and `cleanup`. One shared BullMQ scheduler on
+the `job` queue runs cleanup daily at 00:00 UTC. Cleanup deletes records inactive
+for more than 30 days in guarded batches of 1000, regardless of status. Records
+without an applied event use `createdAt`. Redis jobs remain intact; later events
+recreate deleted records with a new UUID. Cleanup requires the Job Worker.
+
+## Tests
+
+Unit tests sit beside their source files. End-to-end suites live in `test/`:
+
+- `job.resolver`: visibility, ownership, authorization, filters and cursors through HTTP.
+- `job-queries`: synchronized Redis history through the GraphQL API.
+- `job.processor`: atomic event ordering and retention against PostgreSQL.
+- `job.service`: producer-only event forwarding without historical replay.
+- `job.entity`: schema, UUID defaults, bigint columns and query indexes.
+- `queue-api`: multiple application instances, deduplication, retries and shutdown.
+
+Build before running end-to-end tests because they import the package output:
+
+```bash
+pnpm --filter @nest-boot/queue-api build
+pnpm --filter @nest-boot/queue-api test
+REDIS_URL=redis://localhost:6379 \
+QUEUE_TEST_DATABASE_URL=postgresql://postgres:postgres@localhost:5432/postgres \
+pnpm --filter @nest-boot/queue-api test:e2e
+```
+
+Each database suite creates and removes its own database; the PostgreSQL test user
+needs permission to create databases and the shared `authenticated` test role.
+Redis suites use isolated prefixes and remove their own keys.

package/dist/connections/job.connection-definition.d.ts

@@ -0,0 +1,9 @@
+import { Job as JobEntity } from "../entities/job.entity.js";
+declare const Connection: import("@nestjs/common").Type<import("@nest-boot/graphql-connection").ConnectionInterface<JobEntity>>, ConnectionArgs: import("@nestjs/common").Type<import("@nest-boot/graphql-connection").ConnectionArgsInterface<JobEntity>>;
+/** Cursor pagination, filters and creation-time ordering for visible jobs. */
+export declare class JobConnectionArgs extends ConnectionArgs {
+}
+/** Cross-queue Job records within the current authorized scope. */
+export declare class JobConnection extends Connection {
+}
+export {};

package/dist/connections/job.connection-definition.js

@@ -0,0 +1,50 @@
+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;
+};
+import { ArgsType, ObjectType } from "@nest-boot/graphql";
+import { ConnectionBuilder } from "@nest-boot/graphql-connection";
+import { Job as JobEntity } from "../entities/job.entity.js";
+const { Connection, ConnectionArgs } = new ConnectionBuilder(JobEntity)
+    .addField({ field: "id", type: "string", sortable: false })
+    .addField({
+    field: "queue",
+    type: "string",
+    filterable: true,
+})
+    .addField({
+    field: "name",
+    type: "string",
+    filterable: true,
+    searchable: true,
+})
+    .addField({
+    field: "status",
+    type: "string",
+    filterable: true,
+})
+    .addField({
+    field: "created_at",
+    replacement: "createdAt",
+    type: "date",
+    filterable: true,
+    sortable: true,
+})
+    .build();
+/** Cursor pagination, filters and creation-time ordering for visible jobs. */
+let JobConnectionArgs = class JobConnectionArgs extends ConnectionArgs {
+};
+JobConnectionArgs = __decorate([
+    ArgsType()
+], JobConnectionArgs);
+export { JobConnectionArgs };
+/** Cross-queue Job records within the current authorized scope. */
+let JobConnection = class JobConnection extends Connection {
+};
+JobConnection = __decorate([
+    ObjectType()
+], JobConnection);
+export { JobConnection };
+//# sourceMappingURL=job.connection-definition.js.map

package/dist/connections/job.connection-definition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"job.connection-definition.js","sourceRoot":"","sources":["../../src/connections/job.connection-definition.ts"],"names":[],"mappings":";;;;;;AAAA,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAElE,OAAO,EAAE,GAAG,IAAI,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAE7D,MAAM,EAAE,UAAU,EAAE,cAAc,EAAE,GAAG,IAAI,iBAAiB,CAAC,SAAS,CAAC;KACpE,QAAQ,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;KAC1D,QAAQ,CAAC;IACR,KAAK,EAAE,OAAO;IACd,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE,IAAI;CACjB,CAAC;KACD,QAAQ,CAAC;IACR,KAAK,EAAE,MAAM;IACb,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE,IAAI;IAChB,UAAU,EAAE,IAAI;CACjB,CAAC;KACD,QAAQ,CAAC;IACR,KAAK,EAAE,QAAQ;IACf,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE,IAAI;CACjB,CAAC;KACD,QAAQ,CAAC;IACR,KAAK,EAAE,YAAY;IACnB,WAAW,EAAE,WAAW;IACxB,IAAI,EAAE,MAAM;IACZ,UAAU,EAAE,IAAI;IAChB,QAAQ,EAAE,IAAI;CACf,CAAC;KACD,KAAK,EAAE,CAAC;AAEX,8EAA8E;AAEvE,IAAM,iBAAiB,GAAvB,MAAM,iBAAkB,SAAQ,cAAc;CAAG,CAAA;AAA3C,iBAAiB;IAD7B,QAAQ,EAAE;GACE,iBAAiB,CAA0B;;AAExD,mEAAmE;AAE5D,IAAM,aAAa,GAAnB,MAAM,aAAc,SAAQ,UAAU;CAAG,CAAA;AAAnC,aAAa;IADzB,UAAU,EAAE;GACA,aAAa,CAAsB"}

package/dist/decorators/queue-visible.decorator.d.ts

@@ -0,0 +1,14 @@
+import type { BaseQueue } from "@nest-boot/queue";
+import type { Type } from "@nestjs/common";
+/**
+ * Allows a registered queue's Job records to appear in scoped API queries.
+ * @returns Queue class decorator. Authorization still applies to every query.
+ */
+export declare function QueueVisible(): (target: Type<BaseQueue>) => void;
+/**
+ * Checks whether a queue class explicitly enables API queries.
+ * @param queue - Registered queue instance.
+ * @returns Whether the concrete queue class has its own visibility marker.
+ * @internal
+ */
+export declare function isQueueVisible(queue: BaseQueue): boolean;

package/dist/decorators/queue-visible.decorator.js

@@ -0,0 +1,20 @@
+const QUEUE_VISIBLE = Symbol("QUEUE_VISIBLE");
+/**
+ * Allows a registered queue's Job records to appear in scoped API queries.
+ * @returns Queue class decorator. Authorization still applies to every query.
+ */
+export function QueueVisible() {
+    return (target) => {
+        Reflect.defineMetadata(QUEUE_VISIBLE, true, target);
+    };
+}
+/**
+ * Checks whether a queue class explicitly enables API queries.
+ * @param queue - Registered queue instance.
+ * @returns Whether the concrete queue class has its own visibility marker.
+ * @internal
+ */
+export function isQueueVisible(queue) {
+    return Reflect.getOwnMetadata(QUEUE_VISIBLE, queue.constructor) === true;
+}
+//# sourceMappingURL=queue-visible.decorator.js.map

package/dist/decorators/queue-visible.decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue-visible.decorator.js","sourceRoot":"","sources":["../../src/decorators/queue-visible.decorator.ts"],"names":[],"mappings":"AAGA,MAAM,aAAa,GAAG,MAAM,CAAC,eAAe,CAAC,CAAC;AAE9C;;;GAGG;AACH,MAAM,UAAU,YAAY;IAC1B,OAAO,CAAC,MAAuB,EAAQ,EAAE;QACvC,OAAO,CAAC,cAAc,CAAC,aAAa,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IACtD,CAAC,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,KAAgB;IAC7C,OAAO,OAAO,CAAC,cAAc,CAAC,aAAa,EAAE,KAAK,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;AAC3E,CAAC"}

package/dist/entities/index.d.ts

@@ -0,0 +1,4 @@
+import { Job as JobEntity } from "./job.entity.js";
+export { Job as JobEntity } from "./job.entity.js";
+/** Job history entities; Redis owns all queue operational state. */
+export declare const entities: (typeof JobEntity)[];

package/dist/entities/index.js

@@ -0,0 +1,5 @@
+import { Job as JobEntity } from "./job.entity.js";
+export { Job as JobEntity } from "./job.entity.js";
+/** Job history entities; Redis owns all queue operational state. */
+export const entities = [JobEntity];
+//# sourceMappingURL=index.js.map

package/dist/entities/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/entities/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,IAAI,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,GAAG,IAAI,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEnD,oEAAoE;AACpE,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,SAAS,CAAC,CAAC"}

package/dist/entities/job.entity.d.ts

@@ -0,0 +1,24 @@
+import type { JobProgress } from "bullmq";
+import { JobStatus } from "../enums/job-status.enum.js";
+/** Database history synchronized from Redis QueueEvents by the Job worker. */
+export declare class Job {
+    /** Database-generated UUID, stable across synchronization events. */
+    id: string;
+    /** Queue name of the source Redis job. */
+    queue: string;
+    /** Original BullMQ identifier, unique within its queue. */
+    jobId: string;
+    name: string;
+    data: Record<string, unknown>;
+    status: JobStatus;
+    progress: JobProgress | null;
+    returnValue: unknown;
+    failedReason: string | null;
+    createdAt: Date;
+    startedAt: Date | null;
+    finishedAt: Date | null;
+    /** Millisecond component of the latest applied Redis Stream ID. */
+    lastEventMs: bigint;
+    /** Sequence component of the latest applied Redis Stream ID. */
+    lastEventSeq: bigint;
+}

package/dist/entities/job.entity.js

@@ -0,0 +1,128 @@
+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);
+};
+/* eslint-disable @nest-boot/graphql-field-config-from-types -- Persist arbitrary progress but expose only numeric values via the resolver. */
+/* eslint-disable @nest-boot/entity-property-config-from-types -- History uses explicit SQL UUID, JSON and bigint types. */
+import { BigIntType, t } from "@mikro-orm/core";
+import { Entity, Enum, Index, PrimaryKey, Property, Unique, } from "@mikro-orm/decorators/legacy";
+import { Field, Float, HideField, ID, ObjectType } from "@nest-boot/graphql";
+import { JobStatus } from "../enums/job-status.enum.js";
+/** Database history synchronized from Redis QueueEvents by the Job worker. */
+let Job = class Job {
+    /** Database-generated UUID, stable across synchronization events. */
+    id;
+    /** Queue name of the source Redis job. */
+    queue;
+    /** Original BullMQ identifier, unique within its queue. */
+    jobId;
+    name;
+    data;
+    status;
+    progress;
+    returnValue;
+    failedReason;
+    createdAt;
+    startedAt;
+    finishedAt;
+    /** Millisecond component of the latest applied Redis Stream ID. */
+    lastEventMs;
+    /** Sequence component of the latest applied Redis Stream ID. */
+    lastEventSeq;
+};
+__decorate([
+    PrimaryKey({ type: t.uuid, defaultRaw: "gen_random_uuid()" }),
+    Field(() => ID),
+    __metadata("design:type", String)
+], Job.prototype, "id", void 0);
+__decorate([
+    Property({ type: t.text }),
+    Field(() => String),
+    __metadata("design:type", String)
+], Job.prototype, "queue", void 0);
+__decorate([
+    Property({ type: t.text }),
+    HideField(),
+    __metadata("design:type", String)
+], Job.prototype, "jobId", void 0);
+__decorate([
+    Property({ type: t.text }),
+    Field(() => String),
+    __metadata("design:type", String)
+], Job.prototype, "name", void 0);
+__decorate([
+    Property({ type: t.json, defaultRaw: "'{}'::jsonb" }),
+    HideField(),
+    __metadata("design:type", Object)
+], Job.prototype, "data", void 0);
+__decorate([
+    Enum({ items: () => JobStatus }),
+    Field(() => JobStatus),
+    __metadata("design:type", String)
+], Job.prototype, "status", void 0);
+__decorate([
+    Property({ type: t.json, nullable: true }),
+    Field(() => Float, { nullable: true }),
+    __metadata("design:type", Object)
+], Job.prototype, "progress", void 0);
+__decorate([
+    Property({ type: t.json, nullable: true }),
+    HideField(),
+    __metadata("design:type", Object)
+], Job.prototype, "returnValue", void 0);
+__decorate([
+    Property({ type: t.text, nullable: true }),
+    HideField(),
+    __metadata("design:type", Object)
+], Job.prototype, "failedReason", void 0);
+__decorate([
+    Property({ type: t.datetime }),
+    Field(() => Date),
+    __metadata("design:type", Date)
+], Job.prototype, "createdAt", void 0);
+__decorate([
+    Property({ type: t.datetime, nullable: true }),
+    Field(() => Date, { nullable: true }),
+    __metadata("design:type", Object)
+], Job.prototype, "startedAt", void 0);
+__decorate([
+    Property({ type: t.datetime, nullable: true }),
+    Field(() => Date, { nullable: true }),
+    __metadata("design:type", Object)
+], Job.prototype, "finishedAt", void 0);
+__decorate([
+    Property({ type: new BigIntType("bigint"), default: 0 }),
+    HideField(),
+    __metadata("design:type", BigInt)
+], Job.prototype, "lastEventMs", void 0);
+__decorate([
+    Property({ type: new BigIntType("bigint"), default: 0 }),
+    HideField(),
+    __metadata("design:type", BigInt)
+], Job.prototype, "lastEventSeq", void 0);
+Job = __decorate([
+    ObjectType(),
+    Entity(),
+    Unique({ properties: ["queue", "jobId"] }),
+    Index({
+        columns: [{ name: "data.userId" }, { name: "createdAt" }, { name: "id" }],
+    }),
+    Index({
+        columns: [
+            { name: "data.workspaceId" },
+            { name: "createdAt" },
+            { name: "id" },
+        ],
+    }),
+    Index({
+        properties: ["createdAt", "id"],
+        where: `"data"->>'userId' is null and "data"->>'workspaceId' is null`,
+    })
+], Job);
+export { Job };
+//# sourceMappingURL=job.entity.js.map

package/dist/entities/job.entity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"job.entity.js","sourceRoot":"","sources":["../../src/entities/job.entity.ts"],"names":[],"mappings":"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"}

package/dist/enums/job-status.enum.d.ts

@@ -0,0 +1,19 @@
+/** BullMQ job state values, shared by the entity and GraphQL API. */
+export declare enum JobStatus {
+    /** Job is waiting in the Redis prioritized set. */
+    PRIORITIZED = "prioritized",
+    /** No source job state could be recovered from Redis. */
+    UNKNOWN = "unknown",
+    /** Job is waiting to be processed, without a priority. */
+    WAITING = "waiting",
+    /** Job is actively being processed. */
+    ACTIVE = "active",
+    /** Job has completed successfully. */
+    COMPLETED = "completed",
+    /** Job has failed; it may be retried according to its retry policy. */
+    FAILED = "failed",
+    /** Job is delayed and will be processed later. */
+    DELAYED = "delayed",
+    /** Job is waiting for its child jobs to complete. */
+    WAITING_CHILDREN = "waiting-children"
+}

package/dist/enums/job-status.enum.js

@@ -0,0 +1,23 @@
+import { registerEnumType } from "@nest-boot/graphql";
+/** BullMQ job state values, shared by the entity and GraphQL API. */
+export var JobStatus;
+(function (JobStatus) {
+    /** Job is waiting in the Redis prioritized set. */
+    JobStatus["PRIORITIZED"] = "prioritized";
+    /** No source job state could be recovered from Redis. */
+    JobStatus["UNKNOWN"] = "unknown";
+    /** Job is waiting to be processed, without a priority. */
+    JobStatus["WAITING"] = "waiting";
+    /** Job is actively being processed. */
+    JobStatus["ACTIVE"] = "active";
+    /** Job has completed successfully. */
+    JobStatus["COMPLETED"] = "completed";
+    /** Job has failed; it may be retried according to its retry policy. */
+    JobStatus["FAILED"] = "failed";
+    /** Job is delayed and will be processed later. */
+    JobStatus["DELAYED"] = "delayed";
+    /** Job is waiting for its child jobs to complete. */
+    JobStatus["WAITING_CHILDREN"] = "waiting-children";
+})(JobStatus || (JobStatus = {}));
+registerEnumType(JobStatus, { name: "JobStatus" });
+//# sourceMappingURL=job-status.enum.js.map

package/dist/enums/job-status.enum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-status.enum.js","sourceRoot":"","sources":["../../src/enums/job-status.enum.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEtD,qEAAqE;AACrE,MAAM,CAAN,IAAY,SAiBX;AAjBD,WAAY,SAAS;IACnB,mDAAmD;IACnD,wCAA2B,CAAA;IAC3B,yDAAyD;IACzD,gCAAmB,CAAA;IACnB,0DAA0D;IAC1D,gCAAmB,CAAA;IACnB,uCAAuC;IACvC,8BAAiB,CAAA;IACjB,sCAAsC;IACtC,oCAAuB,CAAA;IACvB,uEAAuE;IACvE,8BAAiB,CAAA;IACjB,kDAAkD;IAClD,gCAAmB,CAAA;IACnB,qDAAqD;IACrD,kDAAqC,CAAA;AACvC,CAAC,EAjBW,SAAS,KAAT,SAAS,QAiBpB;AAED,gBAAgB,CAAC,SAAS,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./connections/job.connection-definition.js";
+export { QueueVisible } from "./decorators/queue-visible.decorator.js";
+export * from "./entities/index.js";
+export { JobStatus } from "./enums/job-status.enum.js";
+export { QueueApiModule } from "./queue-api.module.js";
+export { JobResolver } from "./resolvers/job.resolver.js";
+export { JobService } from "./services/job.service.js";

package/dist/index.js

@@ -0,0 +1,8 @@
+export * from "./connections/job.connection-definition.js";
+export { QueueVisible } from "./decorators/queue-visible.decorator.js";
+export * from "./entities/index.js";
+export { JobStatus } from "./enums/job-status.enum.js";
+export { QueueApiModule } from "./queue-api.module.js";
+export { JobResolver } from "./resolvers/job.resolver.js";
+export { JobService } from "./services/job.service.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,4CAA4C,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,MAAM,yCAAyC,CAAC;AACvE,cAAc,qBAAqB,CAAC;AACpC,OAAO,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/processors/job.processor.d.ts

@@ -0,0 +1,18 @@
+import { EntityManager } from "@mikro-orm/core";
+import { BaseProcessor, type Job } from "@nest-boot/queue";
+import { JobQueue } from "../queues/job.queue.js";
+/** Synchronizes Job records and removes expired records. */
+export declare class JobProcessor extends BaseProcessor {
+    private readonly em;
+    constructor(em: EntityManager);
+    /**
+     * Deletes records inactive for 30 days, falling back to their creation time.
+     * @param _job - Scheduled cleanup task.
+     */
+    processCleanup(_job: Job<JobQueue, "cleanup">): Promise<void>;
+    /**
+     * Inserts new history and applies only strictly newer events.
+     * @param job - Deduplicated synchronization job.
+     */
+    processSync(job: Job<JobQueue, "sync">): Promise<void>;
+}

package/dist/processors/job.processor.js

@@ -0,0 +1,111 @@
+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);
+};
+import { EntityManager, } from "@mikro-orm/core";
+import { BaseProcessor, Processor } from "@nest-boot/queue";
+import { pick } from "lodash-es";
+import { Job as JobEntity } from "../entities/job.entity.js";
+import { JobStatus } from "../enums/job-status.enum.js";
+import { JobQueue } from "../queues/job.queue.js";
+/** Synchronizes Job records and removes expired records. */
+let JobProcessor = class JobProcessor extends BaseProcessor {
+    em;
+    constructor(em) {
+        super();
+        this.em = em;
+    }
+    /**
+     * Deletes records inactive for 30 days, falling back to their creation time.
+     * @param _job - Scheduled cleanup task.
+     */
+    async processCleanup(_job) {
+        const em = this.em.fork({ disableContextResolution: true });
+        const cutoff = Date.now() - 30 * 24 * 60 * 60 * 1000;
+        const where = {
+            $or: [
+                { lastEventMs: { $gt: 0n, $lt: BigInt(cutoff) } },
+                { lastEventMs: 0n, createdAt: { $lt: new Date(cutoff) } },
+            ],
+        };
+        let lastId;
+        while (true) {
+            const rows = await em.find(JobEntity, { $and: [where, ...(lastId ? [{ id: { $gt: lastId } }] : [])] }, {
+                fields: ["id"],
+                orderBy: { id: "asc" },
+                limit: 1000,
+                disableIdentityMap: true,
+            });
+            if (!rows.length) {
+                return;
+            }
+            lastId = rows[rows.length - 1].id;
+            // Recheck eligibility so a concurrent event cannot delete a refreshed job.
+            await em.nativeDelete(JobEntity, {
+                $and: [where, { id: { $in: rows.map(({ id }) => id) } }],
+            });
+        }
+    }
+    /**
+     * Inserts new history and applies only strictly newer events.
+     * @param job - Deduplicated synchronization job.
+     */
+    async processSync(job) {
+        const { eventId, data: snapshot } = job.data;
+        const [ms, seq] = eventId.split("-");
+        const data = {
+            ...pick(snapshot, [
+                "queue",
+                "jobId",
+                "name",
+                "data",
+                "status",
+                "progress",
+                "returnValue",
+                "failedReason",
+            ]),
+            lastEventMs: BigInt(ms),
+            lastEventSeq: BigInt(seq),
+        };
+        for (const field of ["createdAt", "startedAt", "finishedAt"]) {
+            const timestamp = snapshot[field];
+            if (timestamp !== undefined) {
+                data[field] = timestamp === null ? null : new Date(timestamp);
+            }
+        }
+        const em = this.em.fork({ disableContextResolution: true });
+        // A concurrent insert must never overwrite an already newer version.
+        await em.upsert(JobEntity, {
+            name: "",
+            data: {},
+            status: JobStatus.UNKNOWN,
+            createdAt: new Date(Number(ms)),
+            ...data,
+        }, {
+            onConflictFields: ["queue", "jobId"],
+            onConflictAction: "ignore",
+        });
+        await em.nativeUpdate(JobEntity, {
+            queue: data.queue,
+            jobId: data.jobId,
+            $or: [
+                { lastEventMs: { $lt: data.lastEventMs } },
+                {
+                    lastEventMs: data.lastEventMs,
+                    lastEventSeq: { $lt: data.lastEventSeq },
+                },
+            ],
+        }, data);
+    }
+};
+JobProcessor = __decorate([
+    Processor(JobQueue),
+    __metadata("design:paramtypes", [EntityManager])
+], JobProcessor);
+export { JobProcessor };
+//# sourceMappingURL=job.processor.js.map

package/dist/processors/job.processor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"job.processor.js","sourceRoot":"","sources":["../../src/processors/job.processor.ts"],"names":[],"mappings":"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"}

package/dist/queue-api.module.d.ts

@@ -0,0 +1,3 @@
+/** Authenticated Job APIs using the application's global database and auth configuration. */
+export declare class QueueApiModule {
+}