@warlock.js/queue 5.13.0 → 5.15.0

package/CHANGELOG.md

@@ -4,6 +4,33 @@ All notable changes to `@warlock.js/queue` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
 
+## 5.15.0 - 2026-09-18
+
+### BREAKING
+
+- Removed `@warlock.js/queue/notifications` (`queueNotificationDispatcher`), deprecated in 5.14. Use `bullmqQueue()` from `@warlock.js/notifications` instead. The `@warlock.js/notifications` peer dependency is also dropped, since this was the only thing in the package that needed it.
+
+### Fixed
+
+- The dashboard guard now ends the request explicitly when a middleware short-circuits, instead of leaving it to Fastify noticing the reply was already sent. The adapter has always returned a "handled" boolean for this; the hook discarded it, so whether an unauthenticated caller reached the dashboard depended on write ordering — a guard answering asynchronously could lose that race.
+
+## 5.14.0 - 2026-09-17
+
+### Added
+
+- `dashboard: { enabled, path, middleware }` in `src/config/queue.ts`: the queue connector mounts Bull Board at boot, guarded by the given middleware.
+- `QueueDashboardUnguardedError`: in production the dashboard refuses to mount without guard middleware, since it can retry and delete jobs.
+- `queueDashboard()` accepts a `middleware` option.
+
+### Deprecated
+
+- `@warlock.js/queue/notifications` (`queueNotificationDispatcher`): use `bullmqQueue()` from `@warlock.js/notifications`. It still works in 5.14, warns once, and is removed in the next release.
+
+### Fixed
+
+- The connector registers the queue config when it mounts the dashboard at boot, so an app whose only queue usage is the dashboard no longer fails to start with `QueueNotConfiguredError`.
+- `find(id)` no longer returns a completed job with `result: null` and `attemptsMade: 0` when the job finishes mid-read.
+
 ## 5.13.0 - 2026-09-17
 
 ### Added

package/README.md

@@ -90,31 +90,67 @@ await retryFailedJob("invoice:43");
 
 ## Notifications
 
+Vendor integrations live as lazy drivers inside the feature package now:
+configure the BullMQ driver from `@warlock.js/notifications` itself.
+
 ```ts title="src/config/notifications.ts"
-import { queueNotificationDispatcher } from "@warlock.js/queue/notifications";
+import { bullmqQueue } from "@warlock.js/notifications";
 
 const config: NotificationConfig = {
   channels: { mail: mailChannel() },
-  queue: queueNotificationDispatcher({ attempts: 3 }),
+  queue: bullmqQueue({ attempts: 3 }),
 };
 ```
 
 `.queue()` notifications now go through BullMQ. `SendOptions.delay` is honoured.
+`@warlock.js/queue` is dynamically imported the first time `.queue()` runs —
+notifications never pays for it unless `bullmqQueue()` is configured.
+
 
 ## Dashboard (optional)
 
 ```sh
-npm install @bull-board/api @bull-board/fastify
+warlock add bull-board
 ```
 
+Installs `@bull-board/api` and `@bull-board/fastify` and adds a `dashboard` block to
+`src/config/queue.ts`:
+
 ```ts
-import { getHttpServer } from "@warlock.js/core";
-import { queueDashboard } from "@warlock.js/queue";
+import { middleware } from "@warlock.js/core";
+import { authMiddleware } from "@warlock.js/auth";
+import type { QueueConfig } from "@warlock.js/queue";
 
-await queueDashboard(getHttpServer(), { basePath: "/admin/queues" });
+const queueConfig: QueueConfig = {
+  // ...
+  dashboard: {
+    enabled: true,
+    path: "/admin/queues",
+    // Runs before every dashboard route — the dashboard can retry and delete
+    // jobs, so guard it. An empty list here throws
+    // QueueDashboardUnguardedError at boot when NODE_ENV is "production".
+    middleware: [authMiddleware("admin")],
+  },
+};
+
+export default queueConfig;
 ```
 
-The bull-board packages are loaded only when `queueDashboard` is called. If they are missing it throws `QueueDashboardDependencyError` with the install command. Protect the route yourself; the dashboard can retry and delete jobs.
+`queueConnector()` mounts the dashboard for you at boot, once the HTTP server exists.
+Outside production an empty `middleware` list is allowed — it mounts anyway and logs one
+warning, so local development stays frictionless.
+
+> **Advanced — mounting manually:** `queueDashboard(server, { basePath, middleware, queues })`
+> is still exported for scripts, worker-only processes, or a custom mount point. The
+> bull-board packages are loaded only when it is called; a missing one throws
+> `QueueDashboardDependencyError` with the install command.
+>
+> ```ts
+> import { getHttpServer } from "@warlock.js/core";
+> import { queueDashboard } from "@warlock.js/queue";
+>
+> await queueDashboard(getHttpServer(), { basePath: "/admin/queues", middleware: [authMiddleware("admin")] });
+> ```
 
 ## License