nuxt-cf-jobs 0.2.0 → 0.4.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,71 @@ export default defineNitroPlugin((nitroApp) => {
 - `releaseStaleReservedJobs()`
 - `toDispatchableJob()`
 
+## Scheduled Tasks (cron)
+
+Queue jobs handle per-request deferred work; **scheduled tasks** handle cron work. `defineScheduledTask` co-locates the cron schedule with its handler, and the module derives `nitro.tasks`, `nitro.scheduledTasks`, and the Cloudflare `triggers.crons` from it — so there is no central list to keep in sync (and no way for the three to silently drift apart).
+
+```ts
+// server/tasks/cleanup.ts
+export default defineScheduledTask({
+  name: 'db:cleanup', // nitro task name (also the runTask id)
+  cron: '0 3 * * *', // or cron: ['0 3 * * *', '0 */6 * * *']
+  description: 'Nightly cleanup',
+  run() {
+    // ...same shape as nitro defineTask's run
+    return { result: 'ok' }
+  },
+})
+```
+
+Enable scanning via `cfJobs.tasksDir`:
+
+```ts
+export default defineNuxtConfig({
+  cfJobs: {
+    // `true` → auto-discover `server/tasks` in the app AND every extended layer
+    // (nuxt.options._layers), so a new layer with cron work needs no host config.
+    tasksDir: true,
+    // …or be explicit: tasksDir: ['server/tasks', '../some-layer/server/tasks']
+  },
+})
+```
+
+Notes:
+
+- `name` and `cron` must be **string literals** — the module reads them statically at build time (without executing the file, which typically imports a DB/server utils that won't load outside nitro). Computed values are skipped with a warning.
+- Plain nitro `defineTask` files in the same dirs are still registered (so they're runnable via `runTask`), just not scheduled.
+- `nitro.scheduledTasks` is populated only outside dev by default (so crons don't fire locally); override with `cfJobs.scheduledTasks: true | false`. The deploy-only `triggers.crons` is always written.
+- Opt-in: nothing is scanned or registered unless `tasksDir` is set.
+
+## 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 +362,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 @@
+