v1.0: Queue/Worker rewrite, workflow engine, docs overhaul

.changeset/README.md

@@ -1,8 +1,5 @@
 # Changesets
 
-Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
-with multi-package repos, or single-package repos to help you version and publish your code. You can
-find the full documentation for it [in our repository](https://github.com/changesets/changesets)
+Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works with multi-package repos, or single-package repos to help you version and publish your code. You can find the full documentation for it [in our repository](https://github.com/changesets/changesets)
 
-We have a quick list of common questions to get you started engaging with this project in
-[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)
+We have a quick list of common questions to get you started engaging with this project in [our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)

.changeset/adapter-drizzle-1.0.md

@@ -0,0 +1,30 @@
+---
+"@vorsteh-queue/adapter-drizzle": major
+---
+
+## @vorsteh-queue/adapter-drizzle 1.0
+
+### Breaking: QueueAdapter Interface Rewritten
+
+Implements the new `QueueAdapter` interface with additional methods:
+
+- `getJobById(id)` — retrieve a single job
+- `getNextJob(options)` — now requires `handlerNames` and `activeGroups` for FIFO support
+- `getNextJobsForHandler(name, count, groupConstraints)` — batch picking with group constraints
+- `updateJobStatus(id, update)` — new signature with `JobStatusUpdate` object
+- `cancelJob(id, reason?)` / `cancelJobs(filter)` — cancellation support
+- `getDeadJobs()` / `redriveJob(id)` / `redriveJobs(filter?)` — DLQ support
+- `findJobByUniqueKey(uniqueKey)` — unique job lookup
+- `updateJobSteps(id, steps)` — step state persistence
+
+### Breaking: Schema Changes (migration required)
+
+New columns: `group_key`, `unique_key`, `cancelled_at`, `cancellation_reason`, `steps`
+
+Changed: `timeout` from JSONB to INT (nullable, milliseconds)
+
+Changed: `progress` from nullable to non-nullable INT (default 0)
+
+Changed: `repeat_count` from nullable to non-nullable (default 0)
+
+New indexes: `idx_queue_jobs_polling`, `idx_queue_jobs_delayed`, `idx_queue_jobs_active_groups`, `idx_queue_jobs_stats`

.changeset/adapter-kysely-1.0.md

@@ -0,0 +1,32 @@
+---
+"@vorsteh-queue/adapter-kysely": major
+---
+
+## @vorsteh-queue/adapter-kysely 1.0
+
+### Breaking: QueueAdapter Interface Rewritten
+
+Implements the new `QueueAdapter` interface with additional methods:
+
+- `getJobById(id)` — retrieve a single job
+- `getNextJob(options)` — now requires `handlerNames` and `activeGroups` for FIFO support
+- `getNextJobsForHandler(name, count, groupConstraints)` — batch picking with group constraints
+- `updateJobStatus(id, update)` — new signature with `JobStatusUpdate` object
+- `cancelJob(id, reason?)` / `cancelJobs(filter)` — cancellation support
+- `getDeadJobs()` / `redriveJob(id)` / `redriveJobs(filter?)` — DLQ support
+- `findJobByUniqueKey(uniqueKey)` — unique job lookup
+- `updateJobSteps(id, steps)` — step state persistence
+
+### Breaking: Schema Changes (migration required)
+
+New columns: `group_key`, `unique_key`, `cancelled_at`, `cancellation_reason`, `steps`
+
+Changed: `timeout` from JSONB to INT (nullable, milliseconds)
+
+Changed: `progress` from nullable to non-nullable INT (default 0)
+
+Changed: `repeat_count` from nullable to non-nullable (default 0)
+
+New indexes: `idx_queue_jobs_polling`, `idx_queue_jobs_delayed`, `idx_queue_jobs_active_groups`, `idx_queue_jobs_stats`
+
+Updated `createQueueJobsTable()` helper and migration files with new schema.

.changeset/adapter-prisma-1.0.md

@@ -0,0 +1,32 @@
+---
+"@vorsteh-queue/adapter-prisma": major
+---
+
+## @vorsteh-queue/adapter-prisma 1.0
+
+### Breaking: QueueAdapter Interface Rewritten
+
+Implements the new `QueueAdapter` interface with additional methods:
+
+- `getJobById(id)` — retrieve a single job
+- `getNextJob(options)` — now requires `handlerNames` and `activeGroups` for FIFO support
+- `getNextJobsForHandler(name, count, groupConstraints)` — batch picking with group constraints
+- `updateJobStatus(id, update)` — new signature with `JobStatusUpdate` object
+- `cancelJob(id, reason?)` / `cancelJobs(filter)` — cancellation support
+- `getDeadJobs()` / `redriveJob(id)` / `redriveJobs(filter?)` — DLQ support
+- `findJobByUniqueKey(uniqueKey)` — unique job lookup
+- `updateJobSteps(id, steps)` — step state persistence
+
+### Breaking: Schema Changes (migration required)
+
+New columns: `group_key`, `unique_key`, `cancelled_at`, `cancellation_reason`, `steps`
+
+Changed: `timeout` from JSONB to INT (nullable, milliseconds)
+
+Changed: `progress` from nullable to non-nullable INT (default 0)
+
+Changed: `repeat_count` from nullable to non-nullable (default 0)
+
+New indexes: `idx_queue_jobs_polling`, `idx_queue_jobs_delayed`, `idx_queue_jobs_active_groups`, `idx_queue_jobs_stats`
+
+Updated `schema.prisma` with new model fields.

.changeset/cli-initial.md

@@ -0,0 +1,14 @@
+---
+"@vorsteh-queue/cli": minor
+---
+
+## @vorsteh-queue/cli — Initial Release
+
+CLI tool for monitoring and managing vorsteh-queue jobs.
+
+- Commands: `status`, `inspect`, `cancel`, `redrive`, `clear`
+- Transports: direct adapter connection or remote GraphQL server
+- `--json` flag on all commands for machine-readable output
+- Configuration via environment variables (`VORSTEH_QUEUE_URL`, `VORSTEH_QUEUE_TOKEN`)
+- `defineCliConfig()` helper for typed configuration
+- Built with citty (unjs CLI framework)

.changeset/core-1.0.md

@@ -0,0 +1,59 @@
+---
+"@vorsteh-queue/core": major
+---
+
+## @vorsteh-queue/core 1.0
+
+### Breaking: Queue/Worker Architecture Split
+
+The `Queue` class is now a producer-only. Job processing is handled by the new `Worker` class.
+
+Before:
+
+```typescript
+const queue = new Queue(adapter, { name: "my-queue" })
+queue.register("job", handler)
+queue.start()
+```
+
+After:
+
+```typescript
+const queue = new Queue(adapter, { name: "my-queue" })
+const worker = new Worker(adapter, { name: "my-queue", concurrency: 5 })
+worker.register("job", handler)
+worker.start()
+
+// Queue is now producer-only — use it to add jobs
+await queue.add("job", { data: "payload" })
+```
+
+### Breaking: Handler Signature
+
+Handlers now receive a `JobContext` with an `AbortSignal` for timeout/cancellation support.
+
+- Before: `(job) => Promise<result>`
+- After: `(job, { signal, step }) => Promise<result>`
+
+### Breaking: New Statuses
+
+Added `cancelled` and `dead` statuses. `QueueStats` now includes all 7 statuses.
+
+### Breaking: Removed APIs
+
+`queue.register()`, `queue.start()`, `queue.stop()`, `queue.pause()`, `queue.resume()`, `queue.enqueue()`, `queue.dequeue()`
+
+### New Features
+
+- Job cancellation (`queue.cancel()`, `worker.cancelJob()`)
+- Dead-letter queue (`queue.getDeadJobs()`, `queue.redrive()`, `queue.redriveAll()`)
+- Group FIFO ordering (`{ group: "tenant-1" }`)
+- Unique job deduplication (`{ unique: { key: "...", action: "reject" | "replace" } }`)
+- `enqueueAndWait()` — enqueue and wait for result (hybrid event + polling)
+- Typed event emitter on both Queue and Worker
+- Configurable retry strategies (exponential, linear, fixed, custom function)
+- State machine validation for job status transitions
+- Per-handler concurrency limits
+- Job Steps (`step.run()`, `step.sleep()`, `step.all()`) for durable multi-step execution
+- Job Dependencies (`dependsOn`, circular detection)
+- Rate Limiting (token-bucket per handler)

.changeset/node-22-minimum.md

@@ -0,0 +1,13 @@
+---
+"@vorsteh-queue/core": major
+"@vorsteh-queue/adapter-drizzle": major
+"@vorsteh-queue/adapter-prisma": major
+"@vorsteh-queue/adapter-kysely": major
+"@vorsteh-queue/server": major
+"@vorsteh-queue/cli": major
+"create-vorsteh-queue": major
+---
+
+**Breaking:** Minimum Node.js version raised from 20 to 22.
+
+Node.js 22 is the current active LTS. This allows the use of stable native `fetch`, improved `AbortSignal` support, and aligns with the TypeScript 6.x target.

.changeset/retry-runnow-delete.md

@@ -0,0 +1,23 @@
+---
+"@vorsteh-queue/core": minor
+"@vorsteh-queue/adapter-drizzle": minor
+"@vorsteh-queue/adapter-kysely": minor
+"@vorsteh-queue/adapter-prisma": minor
+"@vorsteh-queue/server": minor
+"@vorsteh-queue/cli": minor
+---
+
+## New operations: retry, runNow, deleteJob
+
+Added three new job management operations across the full stack:
+
+- **`retry(jobId)`** — resets a `failed` job to `pending` (clears error, resets attempts to 0)
+- **`runNow(jobId)`** — promotes a `delayed` job to `pending` immediately (sets processAt to now)
+- **`deleteJob(jobId)`** — permanently removes a single job by ID
+
+Available on:
+
+- `Queue` class: `queue.retry()`, `queue.runNow()`, `queue.deleteJob()`
+- `QueueAdapter` interface: `retryJob()`, `runJobNow()`, `deleteJob()`
+- GraphQL API: mutations `retryJob`, `runJobNow`, `deleteJob`
+- CLI: commands `retry`, `run-now`, `delete`

.changeset/server-dashboard-merge.md

@@ -0,0 +1,21 @@
+---
+"@vorsteh-queue/server": minor
+"@vorsteh-queue/core": minor
+---
+
+Integrated web dashboard into the server package and added unified configuration.
+
+**Server (`@vorsteh-queue/server`):**
+
+- Embedded the dashboard UI — served as static assets via Hono when `dashboard: true` (default)
+- Simplified auth: `tokens: string[]`, custom `middleware`, or `false` (removed basic auth)
+- Added `loadConfig()` to load `queue.config.ts` via c12
+- Restructured: `src/api/` (GraphQL schema, auth, pubsub) + `src/ui/` (React SPA)
+- Added `flows` query and implemented the `jobs` query (was a stub)
+- Dashboard communicates with the API via `gql.tada` + `graphql-request`
+- UI: Overview stats, Jobs list (filtered/paginated), Job detail, DLQ, Flows, Flow DAG visualization
+
+**Core (`@vorsteh-queue/core`):**
+
+- Added `getJobs()` and `getFlows()` to `QueueAdapter` interface
+- Implemented in Memory, Drizzle, Kysely, and Prisma adapters

.changeset/server-initial.md

@@ -0,0 +1,17 @@
+---
+"@vorsteh-queue/server": minor
+---
+
+## @vorsteh-queue/server — Initial Release
+
+GraphQL server and monitoring API for vorsteh-queue.
+
+- `createQueueServer(config)` — standalone server (Hono + Node.js)
+- `createQueueMiddleware(config)` — composable Hono middleware
+- GraphQL API (via GraphQL Yoga + Pothos):
+  - Queries: `stats`, `job`, `deadJobs`, `size`
+  - Mutations: `cancelJob`, `redriveJob`, `redriveAll`, `clearJobs`
+  - Subscriptions: `jobStatusChanged`, `statsUpdated` (SSE-based)
+- Authentication: token (Bearer), basic auth, custom middleware, or disabled
+- PubSub for real-time event streaming to GraphQL subscribers
+- `defineConfig()` helper for typed configuration

.changeset/workflow-engine.md

@@ -0,0 +1,66 @@
+---
+"@vorsteh-queue/core": minor
+---
+
+## Workflow Engine Features
+
+### Saga Compensation
+
+Steps can declare `compensate` functions that run in reverse order when a later step fails:
+
+```typescript
+await step.run("charge", () => payments.charge(amount), {
+  compensate: (result) => payments.refund(result.txId),
+})
+```
+
+### Signals / Human-in-the-Loop
+
+Jobs can pause and wait for an external signal:
+
+```typescript
+const approval = await step.waitFor("approval", "manager-decision", {
+  timeout: "24h",
+})
+// External: await queue.signal(jobId, "manager-decision", { approved: true })
+```
+
+### Event Triggers
+
+Automatically create follow-up jobs on completion:
+
+```typescript
+worker.trigger({
+  on: "order",
+  create: "send-receipt",
+  data: (result, job) => ({ email: result.email }),
+  condition: (result) => result.total > 0,
+})
+```
+
+### Flow Producer (Parent-Child Job Trees)
+
+Declarative job trees with parent-child relationships:
+
+```typescript
+const flow = await queue.addFlow({
+  name: "deploy",
+  payload: { version: "1.0" },
+  children: [
+    { name: "build", payload: { target: "linux" } },
+    { name: "test", payload: {}, children: [{ name: "lint", payload: {} }] },
+  ],
+})
+```
+
+- Parent waits in `waiting-children` status until all children complete
+- `failParentOnFailure` cascades child failures upward
+- `ctx.getChildrenResults()` provides children results to parent handlers
+- `queue.getFlowTree(flowId)` returns the full tree for visualization
+
+### New Status: `waiting-children`
+
+Added to the state machine. Valid transitions:
+
+- `pending` → `waiting-children`
+- `waiting-children` → `pending` (all children done), `cancelled`, `failed`