better-cf 0.1.0 → 0.2.1

package/README.md

@@ -1,172 +1,148 @@
 # better-cf
 
-Type-safe Cloudflare Queue SDK + CLI.
-
-`better-cf` removes queue binding boilerplate by scanning `defineQueue` exports, generating `.better-cf/entry.ts`, and patching Wrangler queue config.
+Opinionated Cloudflare Queue SDK + automation CLI designed for modern developer experience.
 
 ## Why better-cf
 
-Cloudflare Queues are great, but setup usually repeats:
-
-- Manual queue binding names.
-- Manual `wrangler.toml` or `wrangler.jsonc` queue blocks.
-- Manual worker queue consumer plumbing.
+`better-cf` keeps Cloudflare Queue primitives but improves day-to-day ergonomics:
 
-`better-cf` keeps queue code in plain functions and auto-generates runtime wiring.
+- typed queue contracts from one place
+- less manual entry/config wiring
+- structured automation for local dev and codegen
+- predictable runtime and testing APIs
 
-## Install
+## Quickstart (Existing Project)
 
 ```bash
 npm i better-cf zod
 npm i -D wrangler @cloudflare/workers-types typescript
-```
-
-## Quickstart
-
-```bash
 npx better-cf init
+npm run dev
 ```
 
-Create queue:
-
-```ts
-import { z } from 'zod';
-import { defineQueue } from './better-cf.config';
-
-export const signupQueue = defineQueue({
-  message: z.object({ email: z.string().email(), userId: z.string() }),
-  process: async (ctx, msg) => {
-    await fetch('https://example.com', {
-      method: 'POST',
-      body: JSON.stringify(msg)
-    });
-  },
-  retry: 3
-});
-```
-
-Run dev:
+## Quickstart (New Project)
 
 ```bash
+npx better-cf create my-worker
+cd my-worker
 npm run dev
 ```
 
-Deploy:
+Use a specific package manager during create:
 
 ```bash
-npm run deploy
+npx better-cf create my-worker --use-pnpm
+npx better-cf create my-worker --use-bun
 ```
 
 ## Canonical Imports
 
-- Queue SDK: `better-cf/queue`
+- Queue runtime: `better-cf/queue`
 - Testing helpers: `better-cf/testing`
+- CLI binary: `better-cf`
 
-## Type Safety Guarantees
+## Core Workflow
 
-`createSDK<Env>()` propagates `Env` types into `ctx.env` for queue and worker handlers.
+`better-cf dev` continuously orchestrates:
 
-```ts
-import { createSDK } from 'better-cf/queue';
+1. scan queue definitions
+2. validate config
+3. generate `.better-cf/entry.ts` and type files
+4. patch wrangler queue sections
+5. infer env types
+6. run/restart `wrangler dev`
+7. re-run on source/config changes
 
-type Env = {
-  DB: D1Database;
-  EMAIL_QUEUE: Queue;
-};
+One-shot mode:
 
-export const { defineQueue } = createSDK<Env>();
+```bash
+better-cf generate
 ```
 
-Payload types are inferred from Zod schemas for `send`, `sendBatch`, `process`, and multi-job queue APIs.
+## Example Patterns
 
-## Hono Example
-
-`better-cf` supports Hono default exports.
+### Single queue with typed payload
 
 ```ts
-import { Hono } from 'hono';
-
-const app = new Hono();
-app.get('/', (ctx) => ctx.text('ok'));
+import { createSDK } from 'better-cf/queue';
+import { z } from 'zod';
 
-export default app;
-```
+type Env = { QUEUE_SIGNUP: Queue };
+const { defineQueue, defineWorker } = createSDK<Env>();
 
-The generated `.better-cf/entry.ts` resolves fetch handlers for object/function/named exports.
+export const signupQueue = defineQueue({
+  message: z.object({ email: z.string().email() }),
+  process: async (ctx, msg) => {
+    console.log(ctx.message.id, msg.email);
+  },
+  retry: 3,
+  retryDelay: '30s'
+});
 
-## Legacy Cloudflare Compatibility (Service Worker Adapter)
+export default defineWorker({
+  async fetch() {
+    return new Response('ok');
+  }
+});
+```
 
-Set compatibility mode in `better-cf.config.ts`:
+### Batch mode
 
 ```ts
-export const betterCfConfig = {
-  legacyServiceWorker: true
-};
+const auditQueue = defineQueue({
+  message: z.object({ action: z.string() }),
+  batch: { maxSize: 10, timeout: '30s', maxConcurrency: 2 },
+  processBatch: async (ctx, messages) => {
+    console.log(messages.length, ctx.batch.queue);
+    ctx.batch.ackAll();
+  }
+});
 ```
 
-This mode is adapter-only and not feature-parity guaranteed with module worker patterns.
-
-## CLI Commands
-
-- `better-cf init`: scaffold config, worker, scripts.
-- `better-cf generate`: scan + generate `.better-cf/*` + patch Wrangler config.
-- `better-cf dev`: generate + watch + run `wrangler dev` (local only for queues).
-- `better-cf deploy`: generate + run `wrangler deploy`.
-
-## Queue Config Mapping
-
-| better-cf | Wrangler |
-|---|---|
-| `retry` | `max_retries` |
-| `retryDelay` | `retry_delay` |
-| `deadLetter` | `dead_letter_queue` |
-| `batch.maxSize` | `max_batch_size` |
-| `batch.timeout` | `max_batch_timeout` |
-| `batch.maxConcurrency` | `max_concurrency` |
-
-## Local Dev Constraints
-
-Cloudflare queue local development does not support `wrangler dev --remote` for queue consumers. `better-cf dev --remote` is blocked intentionally.
-
-## Testing Queues
-
-Use `better-cf/testing`:
+### Queue unit testing
 
 ```ts
 import { testQueue } from 'better-cf/testing';
 
-const result = await testQueue(queueHandle, {
-  env: mockEnv,
-  message: { id: '1' }
+const result = await testQueue(signupQueue, {
+  env: {},
+  message: { email: 'dev@example.com' }
 });
+
+expect(result.acked).toHaveLength(1);
 ```
 
-## Compatibility Matrix
+## Comparison with Cloudflare Queue Workflows
+
+| Concern | Cloudflare path | better-cf path |
+|---|---|---|
+| Queue contract shape | Convention/custom runtime checks | `defineQueue({ message: z.object(...) })` |
+| Entry + config wiring | Manual exports + Wrangler maintenance | Generated entry + automated Wrangler patching |
+| Local dev orchestration | Team-managed scripts | One `better-cf dev` loop |
+| Queue test harness | Custom mocks/harnesses | `testQueue` helper |
+
+Detailed comparison: `/apps/docs/src/content/docs/comparison/cloudflare-vs-better-cf.mdx`
 
-- Wrangler: `>=3.91.0 <5`
-- Node: `>=18.18`
-- Config formats: `wrangler.toml`, `wrangler.json`, `wrangler.jsonc`
-- Runtime styles: module worker (first-class), service-worker adapter (compatibility mode)
-- Frameworks: Workers + Hono
+## Limitations
 
-## Not Supported (v1)
+### Not supported
 
-- Pull consumers / HTTP pull consumers.
-- Queue create/delete lifecycle outside deploy workflow.
-- Queue metrics dashboard/API abstraction.
-- Runtime dynamic queue registration.
-- Remote queue local-dev parity for unsupported Cloudflare modes.
+- Pull-message runtime abstraction implementation
+- Queue metrics/dashboard abstraction
+- Dynamic runtime queue declaration
+- Unsupported remote queue local-dev parity modes
 
-## Known Gaps
+### Known gaps
 
-- Non-literal config expressions reduce static wrangler extraction quality.
-- Legacy adapter mode may not match every service-worker edge case.
-- Non-standard worker export patterns beyond documented variants are out of scope.
-- Monorepo autodetection is basic; explicit `workerEntry` may be needed.
+- Non-literal config extraction can reduce static mapping fidelity
+- Legacy service-worker adapter is compatibility-oriented
+- Non-standard worker export patterns beyond documented variants are out of scope
 
-## Roadmap
+Use native Cloudflare APIs directly where the SDK intentionally does not abstract.
 
-Planned future namespaces:
+## Docs
 
-- `better-cf/workflow`
-- `better-cf/durable-object`
+- Site source: `apps/docs`
+- Getting started page: `apps/docs/src/content/docs/getting-started.md`
+- File structure guide: `apps/docs/src/content/docs/guides/file-structure.md`
+- Cookbook page: `apps/docs/src/content/docs/examples/cookbook.md`