@monque/core 1.0.0 → 1.1.1

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025 Maurice de Bruyn
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -61,6 +61,10 @@ await monque.enqueue('send-email', { to: 'user@example.com', subject: 'Hello' })
 // Schedule recurring jobs
 await monque.schedule('0 9 * * *', 'daily-report', { type: 'summary' });
 
+// Management
+await monque.cancelJob('job-id');
+const stats = await monque.getQueueStats();
+
 // Graceful shutdown
 await monque.stop();
 ```
@@ -92,6 +96,19 @@ Creates a new Monque instance.
 - `stop()` - Graceful shutdown
 - `isHealthy()` - Check scheduler health
 
+**Management:**
+- `getJob(id)` - Get job details
+- `getJobs(filter)` - List jobs
+- `getJobsWithCursor(options)` - Paginated list
+- `getQueueStats(filter?)` - Queue statistics
+- `cancelJob(id)` - Cancel a job
+- `retryJob(id)` - Retry a job
+- `rescheduleJob(id, date)` - Reschedule a job
+- `deleteJob(id)` - Delete a job
+- `cancelJobs(filter)` - Bulk cancel
+- `retryJobs(filter)` - Bulk retry
+- `deleteJobs(filter)` - Bulk delete
+
 ### Events
 
 ```typescript
@@ -99,6 +116,9 @@ monque.on('job:start', (job) => { /* job started */ });
 monque.on('job:complete', ({ job, duration }) => { /* job completed */ });
 monque.on('job:fail', ({ job, error, willRetry }) => { /* job failed */ });
 monque.on('job:error', ({ error, job? }) => { /* unexpected error */ });
+monque.on('job:cancelled', ({ job }) => { /* job cancelled */ });
+monque.on('job:retried', ({ job, previousStatus }) => { /* job retried */ });
+monque.on('job:deleted', ({ jobId }) => { /* job deleted */ });
 monque.on('stale:recovered', ({ count }) => { /* stale jobs recovered */ });
 ```
 

package/dist/CHANGELOG.md

@@ -0,0 +1,83 @@
+# @monque/core
+
+## 1.1.1
+
+### Patch Changes
+
+- [#90](https://github.com/ueberBrot/monque/pull/90) [`0364f4b`](https://github.com/ueberBrot/monque/commit/0364f4b9452bc6b81961fce896ebcaeecbaafa58) Thanks [@ueberBrot](https://github.com/ueberBrot)! - Add missing LICENSE and optimize build configuration (source maps, quality gates) for better developer experience and reliability.
+
+## 1.1.0
+
+### Minor Changes
+
+- [#75](https://github.com/ueberBrot/monque/pull/75) [`ebb3a23`](https://github.com/ueberBrot/monque/commit/ebb3a230ec1cd59f381cd22dca19d71b0e568829) Thanks [@ueberBrot](https://github.com/ueberBrot)! - **Management APIs**: Introduced a comprehensive suite of management APIs for monitoring and controlling job queues:
+
+  - **Single Job Management**: `cancelJob`, `retryJob`, `rescheduleJob`, `deleteJob`
+  - **Bulk Operations**: `cancelJobs`, `retryJobs`, `deleteJobs` with rich filtering
+  - **Cursor Pagination**: `getJobsWithCursor` for stable, efficient iteration over large datasets
+  - **Statistics**: `getQueueStats` for monitoring queue health and performance
+
+  **Events**: New events for observability include `job:cancelled`, `job:retried`, and `job:deleted`.
+
+## 1.0.0
+
+### Major Changes
+
+- [#72](https://github.com/ueberBrot/monque/pull/72) [`448bc3e`](https://github.com/ueberBrot/monque/commit/448bc3ee2fddc1e7f5911331fec19e8995ac44ff) Thanks [@ueberBrot](https://github.com/ueberBrot)! - v1.0.0 Stable Release
+
+## 0.3.0
+
+### Minor Changes
+
+- [#67](https://github.com/ueberBrot/monque/pull/67) [`75fafcd`](https://github.com/ueberBrot/monque/commit/75fafcd474277de581d127bc6b60e73f04dff9dc) Thanks [@renovate](https://github.com/apps/renovate)! - chore(deps): update dependencies
+
+  - @monque/core: cron-parser (^5.4.0 → ^5.5.0)
+
+## 0.2.0
+
+### Minor Changes
+
+- [#7](https://github.com/ueberBrot/monque/pull/7) [`eab1ab7`](https://github.com/ueberBrot/monque/commit/eab1ab710db66f84ad5d7edb9f42864619a1276f) Thanks [@ochrstn](https://github.com/ochrstn)! - API Rename: `worker()` → `register()`
+
+  The public method for registering job handlers has been renamed from `worker()` to `register()` for improved API clarity.
+
+  **Before:**
+
+  ```typescript
+  monque.worker("send-email", async (job) => {
+    await sendEmail(job.data);
+  });
+  ```
+
+  **After:**
+
+  ```typescript
+  monque.register("send-email", async (job) => {
+    await sendEmail(job.data);
+  });
+  ```
+
+  This is a **breaking change** for users upgrading from earlier versions. Update all `monque.worker()` calls to `monque.register()`.
+
+- [#29](https://github.com/ueberBrot/monque/pull/29) [`5ac7759`](https://github.com/ueberBrot/monque/commit/5ac775965f9f2ab27211b02d7b048613e48705b2) Thanks [@ueberBrot](https://github.com/ueberBrot)! - Upgrade Node.js Engine to >=22.0.0
+
+  This release updates the `engines.node` requirement in `package.json` to `>=22.0.0`.
+
+  **Breaking Change:** Users on Node.js versions older than 22.0.0 will no longer be able to install or use this package. Please upgrade to Node.js 22 (LTS) or later.
+
+### Patch Changes
+
+- [#48](https://github.com/ueberBrot/monque/pull/48) [`f37b90d`](https://github.com/ueberBrot/monque/commit/f37b90d51ab2773c405c34d423ce1810bbe50273) Thanks [@ueberBrot](https://github.com/ueberBrot)! - Fix race condition in `poll()` where jobs could be processed after shutdown was initiated.
+
+## 0.1.0
+
+### Minor Changes
+
+- [`fe193bb`](https://github.com/ueberBrot/monque/commit/fe193bb3d840667dded3c3ea093a464d3b1852ba) Thanks [@ueberBrot](https://github.com/ueberBrot)! - Initial pre-release of Monque core.
+
+  - MongoDB-backed scheduler with atomic claiming/locking to prevent duplicate processing across multiple instances.
+  - Workers + concurrency controls for background job processing.
+  - Enqueue immediate jobs and schedule recurring jobs via 5-field cron expressions.
+  - Built-in retries with configurable exponential backoff.
+  - Heartbeats, stale job detection, and recovery on startup.
+  - Event-driven observability for job lifecycle events (with change streams support and polling as a safety net).

package/dist/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025 Maurice de Bruyn
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/dist/README.md

@@ -0,0 +1,150 @@
+<p align="center">
+  <img src="../../assets/logo.svg" width="180" alt="Monque logo" />
+</p>
+
+<h1 align="center">@monque/core</h1>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@monque/core">
+    <img src="https://img.shields.io/npm/v/%40monque%2Fcore?style=for-the-badge&label=%40monque%2Fcore" alt="@monque/core version" />
+  </a>
+  <a href="https://codecov.io/gh/ueberBrot/monque">
+    <img src="https://img.shields.io/codecov/c/github/ueberBrot/monque?style=for-the-badge&logo=codecov&logoColor=white" alt="Codecov" />
+  </a>
+</p>
+
+<p align="center">MongoDB-backed job scheduler with atomic locking, exponential backoff, and cron scheduling.</p>
+
+## Installation
+
+Using Bun:
+```bash
+bun add @monque/core mongodb
+```
+
+Or using npm/yarn/pnpm:
+```bash
+npm install @monque/core mongodb
+yarn add @monque/core mongodb
+pnpm add @monque/core mongodb
+```
+
+## Usage
+
+```typescript
+import { Monque } from '@monque/core';
+import { MongoClient } from 'mongodb';
+
+const client = new MongoClient('mongodb://localhost:27017');
+await client.connect();
+
+const monque = new Monque(client.db('myapp'), {
+  collectionName: 'jobs',
+  pollInterval: 1000,
+  maxRetries: 10,
+  defaultConcurrency: 5,
+});
+
+await monque.initialize();
+
+// Register workers
+monque.register('send-email', async (job) => {
+  await sendEmail(job.data.to, job.data.subject);
+});
+
+// Start processing
+monque.start();
+
+// Enqueue jobs
+await monque.enqueue('send-email', { to: 'user@example.com', subject: 'Hello' });
+
+// Schedule recurring jobs
+await monque.schedule('0 9 * * *', 'daily-report', { type: 'summary' });
+
+// Management
+await monque.cancelJob('job-id');
+const stats = await monque.getQueueStats();
+
+// Graceful shutdown
+await monque.stop();
+```
+
+## API
+
+### `new Monque(db, options?)`
+
+Creates a new Monque instance.
+
+**Options:**
+- `collectionName` - MongoDB collection name (default: `'monque_jobs'`)
+- `pollInterval` - Polling interval in ms (default: `1000`)
+- `maxRetries` - Max retry attempts (default: `10`)
+- `baseRetryInterval` - Base backoff interval in ms (default: `1000`)
+- `shutdownTimeout` - Graceful shutdown timeout in ms (default: `30000`)
+- `defaultConcurrency` - Jobs per worker (default: `5`)
+- `lockTimeout` - Stale job threshold in ms (default: `1800000`)
+- `recoverStaleJobs` - Recover stale jobs on startup (default: `true`)
+
+### Methods
+
+- `initialize()` - Set up collection and indexes
+- `enqueue(name, data, options?)` - Enqueue a job
+- `now(name, data)` - Enqueue for immediate processing
+- `schedule(cron, name, data)` - Schedule recurring job
+- `register(name, handler, options?)` - Register a worker
+- `start()` - Start processing jobs
+- `stop()` - Graceful shutdown
+- `isHealthy()` - Check scheduler health
+
+**Management:**
+- `getJob(id)` - Get job details
+- `getJobs(filter)` - List jobs
+- `getJobsWithCursor(options)` - Paginated list
+- `getQueueStats(filter?)` - Queue statistics
+- `cancelJob(id)` - Cancel a job
+- `retryJob(id)` - Retry a job
+- `rescheduleJob(id, date)` - Reschedule a job
+- `deleteJob(id)` - Delete a job
+- `cancelJobs(filter)` - Bulk cancel
+- `retryJobs(filter)` - Bulk retry
+- `deleteJobs(filter)` - Bulk delete
+
+### Events
+
+```typescript
+monque.on('job:start', (job) => { /* job started */ });
+monque.on('job:complete', ({ job, duration }) => { /* job completed */ });
+monque.on('job:fail', ({ job, error, willRetry }) => { /* job failed */ });
+monque.on('job:error', ({ error, job? }) => { /* unexpected error */ });
+monque.on('job:cancelled', ({ job }) => { /* job cancelled */ });
+monque.on('job:retried', ({ job, previousStatus }) => { /* job retried */ });
+monque.on('job:deleted', ({ jobId }) => { /* job deleted */ });
+monque.on('stale:recovered', ({ count }) => { /* stale jobs recovered */ });
+```
+
+## Development
+
+### Running Tests
+
+```bash
+# Run tests once (fresh container each time)
+bun run test
+
+# Run tests in watch mode with container reuse (faster iteration)
+bun run test:dev
+
+# Or enable reuse globally in your shell profile
+export TESTCONTAINERS_REUSE_ENABLE=true
+bun run test:watch
+```
+
+When `TESTCONTAINERS_REUSE_ENABLE=true`, the MongoDB testcontainer persists between test runs, significantly speeding up local development. Ryuk (the testcontainers cleanup daemon) remains enabled as a safety net for orphaned containers.
+
+To manually clean up reusable containers:
+```bash
+docker ps -q --filter label=org.testcontainers=true | while read -r id; do docker stop "$id"; done
+```
+
+## License
+
+ISC