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-mikroorm-initial.md

@@ -0,0 +1,22 @@
+---
+"@vorsteh-queue/adapter-mikroorm": major
+"@vorsteh-queue/core": patch
+"@vorsteh-queue/query-builder": patch
+---
+
+## @vorsteh-queue/adapter-mikroorm (new package)
+
+Initial release of the MikroORM adapter for Vorsteh Queue.
+
+### Features
+
+- `PostgresMikroormQueueAdapter` — full implementation of the `QueueAdapter` interface
+- PostgreSQL support via MikroORM v6 EntityManager with unit of work pattern
+- Raw SQL job picking with `FOR UPDATE SKIP LOCKED` for reliable concurrent processing
+- Pre-built `QueueJobSchema` (EntitySchema) for quick database setup
+- Configurable table name and schema name
+
+### Related changes
+
+- `@vorsteh-queue/core`: Added `MikroormAdapterProps` interface and extended `AdapterKind` union
+- `@vorsteh-queue/query-builder`: Added `./mikroorm` export with MikroORM-compatible `buildWhere`

.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/adapter-sequelize-initial.md

@@ -0,0 +1,22 @@
+---
+"@vorsteh-queue/adapter-sequelize": major
+"@vorsteh-queue/core": patch
+"@vorsteh-queue/query-builder": patch
+---
+
+## @vorsteh-queue/adapter-sequelize (new package)
+
+Initial release of the Sequelize adapter for Vorsteh Queue.
+
+### Features
+
+- `PostgresSequelizeQueueAdapter` — full implementation of the `QueueAdapter` interface
+- PostgreSQL support via Sequelize Model pattern with raw SQL for job picking
+- Raw SQL job picking with `FOR UPDATE SKIP LOCKED` for reliable concurrent processing
+- Pre-built `QueueJobModel` with `initQueueJobModel()` for quick model registration
+- Configurable table name and schema name
+
+### Related changes
+
+- `@vorsteh-queue/core`: Added `SequelizeAdapterProps` interface and extended `AdapterKind` union
+- `@vorsteh-queue/query-builder`: Added `./sequelize` export with Sequelize-compatible `buildWhere`

.changeset/adapter-typeorm-initial.md

@@ -0,0 +1,22 @@
+---
+"@vorsteh-queue/adapter-typeorm": major
+"@vorsteh-queue/core": patch
+"@vorsteh-queue/query-builder": patch
+---
+
+## @vorsteh-queue/adapter-typeorm (new package)
+
+Initial release of the TypeORM adapter for Vorsteh Queue.
+
+### Features
+
+- `PostgresTypeormQueueAdapter` — full implementation of the `QueueAdapter` interface
+- PostgreSQL support via TypeORM's DataSource and Repository pattern
+- Raw SQL job picking with `FOR UPDATE SKIP LOCKED` for reliable concurrent processing
+- Pre-built `QueueJobEntity` with all required columns, types, and indexes
+- Configurable table name and schema name
+
+### Related changes
+
+- `@vorsteh-queue/core`: Added `TypeormAdapterProps` interface and extended `AdapterKind` union
+- `@vorsteh-queue/query-builder`: Added `./typeorm` export with TypeORM-compatible `buildWhere`

.changeset/adapter-zenstack-initial.md

@@ -0,0 +1,22 @@
+---
+"@vorsteh-queue/adapter-zenstack": major
+"@vorsteh-queue/core": patch
+"@vorsteh-queue/query-builder": patch
+---
+
+## @vorsteh-queue/adapter-zenstack (new package)
+
+Initial release of the ZenStack ORM adapter for Vorsteh Queue.
+
+### Features
+
+- `PostgresZenstackQueueAdapter` — full implementation of the `QueueAdapter` interface
+- PostgreSQL support via ZenStack ORM v3 (Prisma-compatible API built on Kysely)
+- Raw SQL job picking with `FOR UPDATE SKIP LOCKED` for reliable concurrent processing
+- Configurable model name, table name, and schema name
+- ZModel schema provided for quick database setup
+
+### Related changes
+
+- `@vorsteh-queue/core`: Added `ZenstackAdapterProps` interface and extended `AdapterKind` union
+- `@vorsteh-queue/query-builder`: Added `./zenstack` export (re-exports Prisma-compatible `buildWhere`)

.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/drizzle-v1-migration.md

@@ -0,0 +1,33 @@
+---
+"@vorsteh-queue/adapter-drizzle": major
+"@vorsteh-queue/query-builder": major
+---
+
+## Breaking: drizzle-orm peer dependency bumped to >=1.0.0-rc.4
+
+The minimum `drizzle-orm` peer dependency has been raised from `>=0.45.x` to `>=1.0.0-rc.4` for both the adapter and query builder packages.
+
+### Breaking: Drizzle client initialization
+
+The `drizzle()` call now requires a `relations` object:
+
+**Before:**
+
+```typescript
+import * as schema from "./schema"
+const db = drizzle(pool, { schema })
+```
+
+**After:**
+
+```typescript
+import { relations } from "./schema"
+const db = drizzle({ client: pool, relations })
+```
+
+### Migration steps
+
+1. Upgrade `drizzle-orm` to `>=1.0.0-rc.4` and `drizzle-kit` to `>=1.0.0-rc.4`
+2. Define your own relations with `defineRelations` including `queueJobs`
+3. Pass `relations` (not `schema`) to your `drizzle()` call
+4. The query builder's `buildWhere` now returns a plain RQB v2 where object instead of SQL conditions

.changeset/job-where-filter.md

@@ -0,0 +1,51 @@
+---
+"@vorsteh-queue/core": major
+"@vorsteh-queue/query-builder": minor
+"@vorsteh-queue/adapter-drizzle": major
+"@vorsteh-queue/adapter-prisma": major
+"@vorsteh-queue/adapter-kysely": major
+"@vorsteh-queue/server": major
+"@vorsteh-queue/cli": major
+---
+
+## Job Where Filter
+
+### Breaking: `getJobs` and `size` Signatures
+
+Replaced flat `status`/`name` filter parameters with a composable `where` input supporting multiple filter conditions with comparison operators.
+
+**Before:**
+
+```typescript
+adapter.getJobs({ status: "failed", name: "send-email", limit: 10 })
+adapter.size()
+```
+
+**After:**
+
+```typescript
+adapter.getJobs({ where: { status: "failed", name: "send-email" }, limit: 10 })
+adapter.size({ status: "failed" })
+```
+
+### Breaking: GraphQL Schema
+
+- `jobs(queue, status, name, limit, offset)` → `jobs(queue, where: JobWhereInput, limit, offset)`
+- `size(queue)` → `size(queue, where: JobWhereInput)`
+
+### New: `@vorsteh-queue/query-builder`
+
+New package providing filter normalization, in-memory matching, and ORM-specific where-clause builders:
+
+- `normalizeWhere()` — expands shorthand filters
+- `matchesWhere()` — in-memory job matching
+- `buildWhere()` — translates to Drizzle/Kysely/Prisma conditions
+
+### Supported Operators
+
+- **String:** eq, neq, contains, startsWith, like, in, isNull
+- **Int:** eq, neq, lt, lte, gt, gte, isNull
+- **DateTime:** lt, lte, gt, gte, isNull
+- **Status:** eq, neq, in
+- **Null:** isNull
+- **Logical:** AND, OR (recursive)

.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`