watch

watch polls your OpenAPI endpoint and regenerates when the hash changes. Run it next to your dev server so api.contracts.ts and api.op stay current while backend engineers "just add a field real quick."

Don't run this in production. CI uses fetch. Your laptop uses watch.

Usage

chowbea-axios watch [flags]

What it does

1. Polls your API endpoint at regular intervals
2. Compares spec hash with cached version
3. Regenerates types and operations when changes detected
4. Preserves cache on graceful shutdown (Ctrl+C)

Flags

Examples

Start watch mode

chowbea-axios watch

Custom polling interval

chowbea-axios watch --interval 5000

Five seconds is plenty unless you're stress-testing your own patience.

Debug mode

chowbea-axios watch --debug

Output

Normal mode — changes only:

╭────────────────────────────────────────
│ chowbea-axios watch
├────────────────────────────────────────
│
│ ✓ Starting watch mode - press Ctrl+C to stop (endpoint=http://localhost:3000/docs/swagger/json, intervalMs=10000)
│
│ ✓ New spec detected, regenerating... (cycleId=3, bytes=45231)
│ ✓ Generation completed (cycleId=3, operations=42, duration=1.2s)

Debug mode — every cycle:

╭────────────────────────────────────────
│ Cycle 1
├────────────────────────────────────────
│   Checking for API changes... (cycleId=1, endpoint=http://localhost:3000/docs/swagger/json)
│   No changes detected, skipping generation (cycleId=1, durationMs=150ms)

Graceful shutdown

Ctrl+C:

│ ⚠ Shutting down watch mode... (signal=SIGINT)
│ ✓ Cache preserved for next run

Cache survives. Next fetch or watch picks up where you left off.

Failure handling

The loop keeps going through transient failures and stops yelling when something is permanently broken:

1. Single failed cycle — logged at warn, loop continues
2. Consecutive failures — exponential backoff: intervalMs × 2^(failures - 1), capped at 5 minutes. Success resets the counter.
3. After 10 consecutive failures — exits with a clear error (deleted spec, 401 forever, malformed cache)
4. Cache preserved on shutdown

│ ⚠ Cycle failed, backing off (cycleId=5, failures=3, backoffMs=40000, error=ECONNREFUSED)

Slow fetches emit heartbeats so the CLI doesn't look frozen.

Setting up concurrent watch

The dev:all script from init:

{
  "scripts": {
    "dev:all": "concurrently --names 'api,dev' \"npm run api:watch\" \"npm run dev\""
  }
}

npm run dev:all

[api] │ ✓ Starting watch mode...
[dev] Starting development server...
[dev] Server running at http://localhost:5173
[api] │ ✓ New spec detected, regenerating...

Full stack wiring: The Query Layer.

Configuration

poll_interval_ms = 10000

[watch]
debug = false

--interval overrides poll_interval_ms.

Best practices

1. 5–10 second intervals — your API spec doesn't change every millisecond
2. Debug only when debugging — otherwise it's noise
3. Concurrent script — you won't remember to start watch manually
4. Not in production — fetch in CI, watch on your machine

Next Steps