@bymax-one/nest-queue 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (12) hide show
  1. package/CHANGELOG.md +123 -0
  2. package/LICENSE +21 -0
  3. package/README.md +858 -0
  4. package/dist/server/index.cjs +1518 -0
  5. package/dist/server/index.d.cts +1386 -0
  6. package/dist/server/index.d.ts +1386 -0
  7. package/dist/server/index.mjs +1500 -0
  8. package/dist/shared/index.cjs +32 -0
  9. package/dist/shared/index.d.cts +132 -0
  10. package/dist/shared/index.d.ts +132 -0
  11. package/dist/shared/index.mjs +29 -0
  12. package/package.json +153 -0
package/dist/shared/index.cjs ADDED
@@ -0,0 +1,32 @@
1
+ 'use strict';
2
+
3
+ // src/shared/constants/job-status.ts
4
+ var JOB_STATUS = {
5
+ WAITING: "waiting",
6
+ ACTIVE: "active",
7
+ COMPLETED: "completed",
8
+ FAILED: "failed",
9
+ DELAYED: "delayed",
10
+ PAUSED: "paused"
11
+ };
12
+
13
+ // src/shared/constants/error-codes.ts
14
+ var QUEUE_ERROR_CODES = {
15
+ CONNECTION_INVALID: "queue.connection_invalid",
16
+ CONNECTION_REQUIRES_NULL_RETRIES: "queue.connection_requires_null_retries",
17
+ CONNECTION_TIMEOUT: "queue.connection_timeout",
18
+ QUEUE_NOT_FOUND: "queue.queue_not_found",
19
+ JOB_NOT_FOUND: "queue.job_not_found",
20
+ INVALID_JOB_DATA: "queue.invalid_job_data",
21
+ INVALID_REPEAT_OPTIONS: "queue.invalid_repeat_options",
22
+ DUPLICATE_PROCESSOR: "queue.duplicate_processor",
23
+ FLOW_DISABLED: "queue.flow_disabled",
24
+ METRICS_DISABLED: "queue.metrics_disabled",
25
+ SHUTDOWN_TIMEOUT_EXCEEDED: "queue.shutdown_timeout_exceeded",
26
+ BULK_ENQUEUE_FAILED: "queue.bulk_enqueue_failed",
27
+ WORKER_REGISTRATION_FAILED: "queue.worker_registration_failed",
28
+ INVALID_OPTIONS: "queue.invalid_options"
29
+ };
30
+
31
+ exports.JOB_STATUS = JOB_STATUS;
32
+ exports.QUEUE_ERROR_CODES = QUEUE_ERROR_CODES;
package/dist/shared/index.d.cts ADDED
@@ -0,0 +1,132 @@
1
+ /**
2
+ * @fileoverview Job status union shared across runtimes.
3
+ * @layer shared/types
4
+ */
5
+ /**
6
+ * Snapshot statuses BullMQ exposes via `Queue.getJobCounts()`.
7
+ * Kept in sync with BullMQ's internal status set.
8
+ *
9
+ * @example
10
+ * const status: JobStatus = 'waiting'
11
+ */
12
+ type JobStatus = 'waiting' | 'active' | 'completed' | 'failed' | 'delayed' | 'paused';
13
+
14
+ /**
15
+ * @fileoverview Instantaneous queue metrics snapshot type.
16
+ * @layer shared/types
17
+ */
18
+
19
+ /**
20
+ * Instantaneous snapshot of a queue's job counts grouped by status.
21
+ *
22
+ * @example
23
+ * const metrics: QueueMetrics = {
24
+ * queue: 'email',
25
+ * counts: { waiting: 3, active: 1, completed: 120, failed: 2, delayed: 0, paused: 0 },
26
+ * collectedAt: '2026-06-26T12:00:00.000Z',
27
+ * }
28
+ */
29
+ interface QueueMetrics {
30
+ /** Queue name the snapshot was taken from. */
31
+ queue: string;
32
+ /** Number of jobs in each of the six BullMQ statuses. */
33
+ counts: Record<JobStatus, number>;
34
+ /** ISO 8601 UTC timestamp when the snapshot was collected. */
35
+ collectedAt: string;
36
+ }
37
+
38
+ /**
39
+ * @fileoverview Discriminated union for the BullMQ Job Schedulers (recurring jobs) API.
40
+ * @layer shared/types
41
+ */
42
+ /**
43
+ * Discriminated union for the BullMQ Job Schedulers API — the current
44
+ * recurring-jobs surface (the legacy repeatable API is removed in BullMQ v6).
45
+ * Either `pattern` (cron) OR `every` (ms interval) is provided, never both.
46
+ *
47
+ * A thin, validated projection of BullMQ's `RepeatOptions` minus the internal
48
+ * scheduler `key`.
49
+ *
50
+ * @example Cron schedule
51
+ * const daily: JobSchedulerRepeatOptions = { pattern: '0 3 * * *', tz: 'America/Sao_Paulo' }
52
+ * @example Fixed interval
53
+ * const everyMinute: JobSchedulerRepeatOptions = { every: 60_000 }
54
+ */
55
+ type JobSchedulerRepeatOptions = {
56
+ /** Crontab expression (5-field, or 6-field with seconds). */
57
+ pattern: string;
58
+ /** IANA timezone (e.g. 'America/Sao_Paulo'). Default: UTC. */
59
+ tz?: string;
60
+ /** Optional cap on the number of runs. */
61
+ limit?: number;
62
+ /** Start time (epoch ms or ISO string). */
63
+ startDate?: number | string;
64
+ /** Stop time (epoch ms or ISO string). Must be in the future or BullMQ throws. */
65
+ endDate?: number | string;
66
+ } | {
67
+ /** Interval in milliseconds between runs. */
68
+ every: number;
69
+ /** Optional cap on the number of runs. */
70
+ limit?: number;
71
+ /** Phase offset (ms) applied to interval schedulers. */
72
+ offset?: number;
73
+ /** Start time (epoch ms or ISO string). */
74
+ startDate?: number | string;
75
+ /** Stop time (epoch ms or ISO string). */
76
+ endDate?: number | string;
77
+ };
78
+
79
+ /**
80
+ * @fileoverview Canonical job-status constant object.
81
+ * @layer shared/constants
82
+ */
83
+ /**
84
+ * Canonical job status constants — use these in business logic instead of
85
+ * hardcoded string literals. Declared `as const` so the literal types survive
86
+ * into the emitted declaration files.
87
+ *
88
+ * @example
89
+ * if (status === JOB_STATUS.FAILED) { retry() }
90
+ */
91
+ declare const JOB_STATUS: {
92
+ readonly WAITING: "waiting";
93
+ readonly ACTIVE: "active";
94
+ readonly COMPLETED: "completed";
95
+ readonly FAILED: "failed";
96
+ readonly DELAYED: "delayed";
97
+ readonly PAUSED: "paused";
98
+ };
99
+
100
+ /**
101
+ * @fileoverview Stable error-code catalog emitted by the library, plus the
102
+ * derived code union. Single source of truth, re-exported by the server barrel.
103
+ * @layer shared/constants
104
+ */
105
+ /**
106
+ * Stable, transport-independent error codes emitted through `QueueException`.
107
+ * Declared `as const` so each value keeps its literal type in the emitted
108
+ * declaration files.
109
+ *
110
+ * @example
111
+ * if (error.code === QUEUE_ERROR_CODES.JOB_NOT_FOUND) { return null }
112
+ */
113
+ declare const QUEUE_ERROR_CODES: {
114
+ readonly CONNECTION_INVALID: "queue.connection_invalid";
115
+ readonly CONNECTION_REQUIRES_NULL_RETRIES: "queue.connection_requires_null_retries";
116
+ readonly CONNECTION_TIMEOUT: "queue.connection_timeout";
117
+ readonly QUEUE_NOT_FOUND: "queue.queue_not_found";
118
+ readonly JOB_NOT_FOUND: "queue.job_not_found";
119
+ readonly INVALID_JOB_DATA: "queue.invalid_job_data";
120
+ readonly INVALID_REPEAT_OPTIONS: "queue.invalid_repeat_options";
121
+ readonly DUPLICATE_PROCESSOR: "queue.duplicate_processor";
122
+ readonly FLOW_DISABLED: "queue.flow_disabled";
123
+ readonly METRICS_DISABLED: "queue.metrics_disabled";
124
+ readonly SHUTDOWN_TIMEOUT_EXCEEDED: "queue.shutdown_timeout_exceeded";
125
+ readonly BULK_ENQUEUE_FAILED: "queue.bulk_enqueue_failed";
126
+ readonly WORKER_REGISTRATION_FAILED: "queue.worker_registration_failed";
127
+ readonly INVALID_OPTIONS: "queue.invalid_options";
128
+ };
129
+ /** Union of every value in {@link QUEUE_ERROR_CODES}. */
130
+ type QueueErrorCode = (typeof QUEUE_ERROR_CODES)[keyof typeof QUEUE_ERROR_CODES];
131
+
132
+ export { JOB_STATUS, type JobSchedulerRepeatOptions, type JobStatus, QUEUE_ERROR_CODES, type QueueErrorCode, type QueueMetrics };
package/dist/shared/index.d.ts ADDED
@@ -0,0 +1,132 @@
1
+ /**
2
+ * @fileoverview Job status union shared across runtimes.
3
+ * @layer shared/types
4
+ */
5
+ /**
6
+ * Snapshot statuses BullMQ exposes via `Queue.getJobCounts()`.
7
+ * Kept in sync with BullMQ's internal status set.
8
+ *
9
+ * @example
10
+ * const status: JobStatus = 'waiting'
11
+ */
12
+ type JobStatus = 'waiting' | 'active' | 'completed' | 'failed' | 'delayed' | 'paused';
13
+
14
+ /**
15
+ * @fileoverview Instantaneous queue metrics snapshot type.
16
+ * @layer shared/types
17
+ */
18
+
19
+ /**
20
+ * Instantaneous snapshot of a queue's job counts grouped by status.
21
+ *
22
+ * @example
23
+ * const metrics: QueueMetrics = {
24
+ * queue: 'email',
25
+ * counts: { waiting: 3, active: 1, completed: 120, failed: 2, delayed: 0, paused: 0 },
26
+ * collectedAt: '2026-06-26T12:00:00.000Z',
27
+ * }
28
+ */
29
+ interface QueueMetrics {
30
+ /** Queue name the snapshot was taken from. */
31
+ queue: string;
32
+ /** Number of jobs in each of the six BullMQ statuses. */
33
+ counts: Record<JobStatus, number>;
34
+ /** ISO 8601 UTC timestamp when the snapshot was collected. */
35
+ collectedAt: string;
36
+ }
37
+
38
+ /**
39
+ * @fileoverview Discriminated union for the BullMQ Job Schedulers (recurring jobs) API.
40
+ * @layer shared/types
41
+ */
42
+ /**
43
+ * Discriminated union for the BullMQ Job Schedulers API — the current
44
+ * recurring-jobs surface (the legacy repeatable API is removed in BullMQ v6).
45
+ * Either `pattern` (cron) OR `every` (ms interval) is provided, never both.
46
+ *
47
+ * A thin, validated projection of BullMQ's `RepeatOptions` minus the internal
48
+ * scheduler `key`.
49
+ *
50
+ * @example Cron schedule
51
+ * const daily: JobSchedulerRepeatOptions = { pattern: '0 3 * * *', tz: 'America/Sao_Paulo' }
52
+ * @example Fixed interval
53
+ * const everyMinute: JobSchedulerRepeatOptions = { every: 60_000 }
54
+ */
55
+ type JobSchedulerRepeatOptions = {
56
+ /** Crontab expression (5-field, or 6-field with seconds). */
57
+ pattern: string;
58
+ /** IANA timezone (e.g. 'America/Sao_Paulo'). Default: UTC. */
59
+ tz?: string;
60
+ /** Optional cap on the number of runs. */
61
+ limit?: number;
62
+ /** Start time (epoch ms or ISO string). */
63
+ startDate?: number | string;
64
+ /** Stop time (epoch ms or ISO string). Must be in the future or BullMQ throws. */
65
+ endDate?: number | string;
66
+ } | {
67
+ /** Interval in milliseconds between runs. */
68
+ every: number;
69
+ /** Optional cap on the number of runs. */
70
+ limit?: number;
71
+ /** Phase offset (ms) applied to interval schedulers. */
72
+ offset?: number;
73
+ /** Start time (epoch ms or ISO string). */
74
+ startDate?: number | string;
75
+ /** Stop time (epoch ms or ISO string). */
76
+ endDate?: number | string;
77
+ };
78
+
79
+ /**
80
+ * @fileoverview Canonical job-status constant object.
81
+ * @layer shared/constants
82
+ */
83
+ /**
84
+ * Canonical job status constants — use these in business logic instead of
85
+ * hardcoded string literals. Declared `as const` so the literal types survive
86
+ * into the emitted declaration files.
87
+ *
88
+ * @example
89
+ * if (status === JOB_STATUS.FAILED) { retry() }
90
+ */
91
+ declare const JOB_STATUS: {
92
+ readonly WAITING: "waiting";
93
+ readonly ACTIVE: "active";
94
+ readonly COMPLETED: "completed";
95
+ readonly FAILED: "failed";
96
+ readonly DELAYED: "delayed";
97
+ readonly PAUSED: "paused";
98
+ };
99
+
100
+ /**
101
+ * @fileoverview Stable error-code catalog emitted by the library, plus the
102
+ * derived code union. Single source of truth, re-exported by the server barrel.
103
+ * @layer shared/constants
104
+ */
105
+ /**
106
+ * Stable, transport-independent error codes emitted through `QueueException`.
107
+ * Declared `as const` so each value keeps its literal type in the emitted
108
+ * declaration files.
109
+ *
110
+ * @example
111
+ * if (error.code === QUEUE_ERROR_CODES.JOB_NOT_FOUND) { return null }
112
+ */
113
+ declare const QUEUE_ERROR_CODES: {
114
+ readonly CONNECTION_INVALID: "queue.connection_invalid";
115
+ readonly CONNECTION_REQUIRES_NULL_RETRIES: "queue.connection_requires_null_retries";
116
+ readonly CONNECTION_TIMEOUT: "queue.connection_timeout";
117
+ readonly QUEUE_NOT_FOUND: "queue.queue_not_found";
118
+ readonly JOB_NOT_FOUND: "queue.job_not_found";
119
+ readonly INVALID_JOB_DATA: "queue.invalid_job_data";
120
+ readonly INVALID_REPEAT_OPTIONS: "queue.invalid_repeat_options";
121
+ readonly DUPLICATE_PROCESSOR: "queue.duplicate_processor";
122
+ readonly FLOW_DISABLED: "queue.flow_disabled";
123
+ readonly METRICS_DISABLED: "queue.metrics_disabled";
124
+ readonly SHUTDOWN_TIMEOUT_EXCEEDED: "queue.shutdown_timeout_exceeded";
125
+ readonly BULK_ENQUEUE_FAILED: "queue.bulk_enqueue_failed";
126
+ readonly WORKER_REGISTRATION_FAILED: "queue.worker_registration_failed";
127
+ readonly INVALID_OPTIONS: "queue.invalid_options";
128
+ };
129
+ /** Union of every value in {@link QUEUE_ERROR_CODES}. */
130
+ type QueueErrorCode = (typeof QUEUE_ERROR_CODES)[keyof typeof QUEUE_ERROR_CODES];
131
+
132
+ export { JOB_STATUS, type JobSchedulerRepeatOptions, type JobStatus, QUEUE_ERROR_CODES, type QueueErrorCode, type QueueMetrics };
package/dist/shared/index.mjs ADDED
@@ -0,0 +1,29 @@
1
+ // src/shared/constants/job-status.ts
2
+ var JOB_STATUS = {
3
+ WAITING: "waiting",
4
+ ACTIVE: "active",
5
+ COMPLETED: "completed",
6
+ FAILED: "failed",
7
+ DELAYED: "delayed",
8
+ PAUSED: "paused"
9
+ };
10
+
11
+ // src/shared/constants/error-codes.ts
12
+ var QUEUE_ERROR_CODES = {
13
+ CONNECTION_INVALID: "queue.connection_invalid",
14
+ CONNECTION_REQUIRES_NULL_RETRIES: "queue.connection_requires_null_retries",
15
+ CONNECTION_TIMEOUT: "queue.connection_timeout",
16
+ QUEUE_NOT_FOUND: "queue.queue_not_found",
17
+ JOB_NOT_FOUND: "queue.job_not_found",
18
+ INVALID_JOB_DATA: "queue.invalid_job_data",
19
+ INVALID_REPEAT_OPTIONS: "queue.invalid_repeat_options",
20
+ DUPLICATE_PROCESSOR: "queue.duplicate_processor",
21
+ FLOW_DISABLED: "queue.flow_disabled",
22
+ METRICS_DISABLED: "queue.metrics_disabled",
23
+ SHUTDOWN_TIMEOUT_EXCEEDED: "queue.shutdown_timeout_exceeded",
24
+ BULK_ENQUEUE_FAILED: "queue.bulk_enqueue_failed",
25
+ WORKER_REGISTRATION_FAILED: "queue.worker_registration_failed",
26
+ INVALID_OPTIONS: "queue.invalid_options"
27
+ };
28
+
29
+ export { JOB_STATUS, QUEUE_ERROR_CODES };
package/package.json ADDED
@@ -0,0 +1,153 @@
1
+ {
2
+ "name": "@bymax-one/nest-queue",
3
+ "version": "1.0.0",
4
+ "description": "NestJS dynamic module wrapping BullMQ — typed jobs, flows, job schedulers, deduplication, OpenTelemetry, graceful shutdown",
5
+ "author": "Bymax One <support@bymax.one>",
6
+ "license": "MIT",
7
+ "homepage": "https://github.com/bymaxone/nest-queue#readme",
8
+ "repository": {
9
+ "type": "git",
10
+ "url": "git+https://github.com/bymaxone/nest-queue.git"
11
+ },
12
+ "bugs": {
13
+ "url": "https://github.com/bymaxone/nest-queue/issues"
14
+ },
15
+ "type": "module",
16
+ "sideEffects": false,
17
+ "files": [
18
+ "dist",
19
+ "LICENSE",
20
+ "README.md",
21
+ "CHANGELOG.md"
22
+ ],
23
+ "main": "./dist/server/index.cjs",
24
+ "module": "./dist/server/index.mjs",
25
+ "types": "./dist/server/index.d.cts",
26
+ "exports": {
27
+ ".": {
28
+ "import": {
29
+ "types": "./dist/server/index.d.ts",
30
+ "default": "./dist/server/index.mjs"
31
+ },
32
+ "require": {
33
+ "types": "./dist/server/index.d.cts",
34
+ "default": "./dist/server/index.cjs"
35
+ }
36
+ },
37
+ "./shared": {
38
+ "import": {
39
+ "types": "./dist/shared/index.d.ts",
40
+ "default": "./dist/shared/index.mjs"
41
+ },
42
+ "require": {
43
+ "types": "./dist/shared/index.d.cts",
44
+ "default": "./dist/shared/index.cjs"
45
+ }
46
+ },
47
+ "./package.json": "./package.json"
48
+ },
49
+ "typesVersions": {
50
+ "*": {
51
+ "shared": [
52
+ "./dist/shared/index.d.cts"
53
+ ]
54
+ }
55
+ },
56
+ "dependencies": {},
57
+ "peerDependencies": {
58
+ "@nestjs/common": "^11.0.0",
59
+ "@nestjs/core": "^11.0.0",
60
+ "bullmq": "^5.16.0",
61
+ "bullmq-otel": "^1.0.0",
62
+ "ioredis": "^5.0.0",
63
+ "reflect-metadata": "^0.2.0"
64
+ },
65
+ "peerDependenciesMeta": {
66
+ "bullmq-otel": {
67
+ "optional": true
68
+ }
69
+ },
70
+ "devDependencies": {
71
+ "@arethetypeswrong/cli": "^0.18.5",
72
+ "@commitlint/cli": "^21.2.1",
73
+ "@commitlint/config-conventional": "^21.2.0",
74
+ "@eslint/js": "^9.39.5",
75
+ "@nestjs/common": "^11.1.28",
76
+ "@nestjs/core": "^11.1.28",
77
+ "@nestjs/testing": "^11.1.28",
78
+ "@stryker-mutator/core": "^9.6.1",
79
+ "@stryker-mutator/jest-runner": "^9.6.1",
80
+ "@types/jest": "^30.0.0",
81
+ "@types/node": "^24.13.3",
82
+ "bullmq": "^5.81.2",
83
+ "eslint": "^9.39.5",
84
+ "eslint-config-prettier": "^10.1.8",
85
+ "husky": "^9.1.7",
86
+ "ioredis": "5.11.1",
87
+ "ioredis-mock": "^8.9.0",
88
+ "jest": "^30.0.0",
89
+ "jest-environment-node": "^30.4.1",
90
+ "lint-staged": "^17.2.0",
91
+ "prettier": "^3.9.6",
92
+ "reflect-metadata": "^0.2.2",
93
+ "rxjs": "^7.8.1",
94
+ "testcontainers": "^12.0.4",
95
+ "ts-jest": "^29.4.12",
96
+ "tsup": "^8.3.0",
97
+ "typescript": "^5.6.0",
98
+ "typescript-eslint": "^8.65.0"
99
+ },
100
+ "keywords": [
101
+ "nestjs",
102
+ "bullmq",
103
+ "queue",
104
+ "redis",
105
+ "worker",
106
+ "flow",
107
+ "cron",
108
+ "job-scheduler",
109
+ "scheduler",
110
+ "deduplication",
111
+ "opentelemetry",
112
+ "otel",
113
+ "graceful-shutdown",
114
+ "job"
115
+ ],
116
+ "lint-staged": {
117
+ "*.{ts,tsx,js,mjs,cjs}": [
118
+ "eslint --fix",
119
+ "prettier --write"
120
+ ],
121
+ "*.{json,md,yml,yaml}": [
122
+ "prettier --write"
123
+ ]
124
+ },
125
+ "engines": {
126
+ "node": ">=24.0.0"
127
+ },
128
+ "publishConfig": {
129
+ "access": "public",
130
+ "registry": "https://registry.npmjs.org/"
131
+ },
132
+ "scripts": {
133
+ "build": "pnpm clean && tsup",
134
+ "lint": "eslint src scripts test",
135
+ "lint:fix": "eslint src scripts test --fix",
136
+ "test": "jest",
137
+ "test:cov": "jest --coverage",
138
+ "test:watch": "jest --watch",
139
+ "test:e2e": "jest --config jest.e2e.config.ts",
140
+ "test:all": "pnpm test && pnpm test:e2e",
141
+ "test:cov:all": "jest --config jest.coverage.config.ts --coverage",
142
+ "test:types": "tsc --noEmit -p tsconfig.typetest.json",
143
+ "mutation": "stryker run",
144
+ "mutation:incremental": "stryker run --incremental",
145
+ "mutation:dry-run": "stryker run --dryRunOnly",
146
+ "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.server.json",
147
+ "size": "node scripts/check-size.mjs",
148
+ "smoke": "node scripts/dogfood-smoke-test.mjs",
149
+ "check:exports": "attw --pack .",
150
+ "clean": "rm -rf dist coverage",
151
+ "release": "pnpm publish --provenance"
152
+ }
153
+ }