nuxt-cf-jobs 0.2.0 → 0.3.0

package/README.md

@@ -73,13 +73,13 @@ jobsIgnore: ['**/_*.ts', '**/*.d.ts', '**/*.test.ts', '**/*.spec.ts']
 The generated registry is available as `#cf-jobs/app` by default.
 
 ```ts
+import type { JobName, JobPayload } from '#cf-jobs/app'
 import {
   buildJobPayload,
   getJobDefinition,
   getQueue,
-  prepareJob,
-  type JobName,
-  type JobPayload,
+
+  prepareJob
 } from '#cf-jobs/app'
 
 const name: JobName = 'sync/table'
@@ -201,8 +201,7 @@ export default defineEventHandler(async (event) => {
   await repository.migrate()
 
   const publisher = createQueuePublisher(env, queue =>
-    queue === 'default' ? 'QUEUE_DEFAULT' : undefined,
-  )
+    queue === 'default' ? 'QUEUE_DEFAULT' : undefined,)
 
   const record = await prepareJob({
     name: 'sync/table',
@@ -220,8 +219,8 @@ export default defineEventHandler(async (event) => {
 Consume durable queue messages with `runDurableJobMessage()` and the D1 repository:
 
 ```ts
-import { runDurableJobMessage } from 'nuxt-cf-jobs/durable'
 import { createD1DurableJobRepository } from 'nuxt-cf-jobs/d1'
+import { runDurableJobMessage } from 'nuxt-cf-jobs/durable'
 import { jobRegistry } from '#cf-jobs/app'
 
 export default defineNitroPlugin((nitroApp) => {
@@ -276,6 +275,34 @@ export default defineNitroPlugin((nitroApp) => {
 - `releaseStaleReservedJobs()`
 - `toDispatchableJob()`
 
+## CLI
+
+The package ships a `cf-jobs` binary, an `artisan queue:*`-style tool for inspecting and managing the durable D1 job tables. It queries D1 through `wrangler d1 execute`, so it works against both the local miniflare database (default) and production (`--remote`), auto-detecting the D1 binding from your wrangler config.
+
+```bash
+# backpressure overview: per-queue ready/reserved/delayed, ready-lag, failures, stuck reservations
+pnpm cf-jobs            # alias for `cf-jobs status`
+pnpm cf-jobs status --remote
+
+# inspect jobs
+pnpm cf-jobs jobs --queue billing --state ready --limit 20
+pnpm cf-jobs failed                       # artisan queue:failed
+pnpm cf-jobs schedule                     # artisan schedule:list (cron + next run)
+pnpm cf-jobs tasks                        # every discovered task
+
+# manage (prompt for confirmation; pass --yes to skip, required when non-interactive)
+pnpm cf-jobs retry <id>                   # artisan queue:retry — re-queue a failed job
+pnpm cf-jobs retry --queue billing        # re-queue a whole queue's failures
+pnpm cf-jobs forget <id>                  # artisan queue:forget
+pnpm cf-jobs flush                        # artisan queue:flush — delete all failed jobs
+pnpm cf-jobs clear --state reserved       # artisan queue:clear — drop active jobs (e.g. stuck reservations)
+pnpm cf-jobs migrate                      # create the job tables/indexes in D1
+```
+
+Every command accepts `--config <wrangler path>`, `--db <binding>`, `--remote`, `--json`, and `--jobs-table` / `--failed-table` overrides. `status` flags queues whose oldest ready job is lagging and reservations stuck for more than five minutes (a crashed or timed-out consumer). Run `cf-jobs <command> --help` for the full argument list.
+
+`cf-jobs` shells out to `wrangler`; it resolves the binary from `node_modules/.bin`, falling back to `wrangler` on `PATH` (override with `CF_JOBS_WRANGLER_BIN`).
+
 ## Runtime Validation
 
 The generated registry validates jobs at startup. It fails loudly for:
@@ -298,9 +325,9 @@ assertQueueBindings()
 Use the narrow subpaths when you can:
 
 ```ts
-import { defineJob } from 'nuxt-cf-jobs/server'
-import { runDurableJobMessage } from 'nuxt-cf-jobs/durable'
 import { createD1DurableJobRepository } from 'nuxt-cf-jobs/d1'
+import { runDurableJobMessage } from 'nuxt-cf-jobs/durable'
+import { defineJob } from 'nuxt-cf-jobs/server'
 import { createFakeQueue } from 'nuxt-cf-jobs/testing'
 ```
 

package/dist/cli/index.d.mts

@@ -0,0 +1 @@
+