better-cf 0.1.0

package/README.md

@@ -0,0 +1,172 @@
+# 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.
+
+## 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 queue code in plain functions and auto-generates runtime wiring.
+
+## Install
+
+```bash
+npm i better-cf zod
+npm i -D wrangler @cloudflare/workers-types typescript
+```
+
+## Quickstart
+
+```bash
+npx better-cf init
+```
+
+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:
+
+```bash
+npm run dev
+```
+
+Deploy:
+
+```bash
+npm run deploy
+```
+
+## Canonical Imports
+
+- Queue SDK: `better-cf/queue`
+- Testing helpers: `better-cf/testing`
+
+## Type Safety Guarantees
+
+`createSDK<Env>()` propagates `Env` types into `ctx.env` for queue and worker handlers.
+
+```ts
+import { createSDK } from 'better-cf/queue';
+
+type Env = {
+  DB: D1Database;
+  EMAIL_QUEUE: Queue;
+};
+
+export const { defineQueue } = createSDK<Env>();
+```
+
+Payload types are inferred from Zod schemas for `send`, `sendBatch`, `process`, and multi-job queue APIs.
+
+## Hono Example
+
+`better-cf` supports Hono default exports.
+
+```ts
+import { Hono } from 'hono';
+
+const app = new Hono();
+app.get('/', (ctx) => ctx.text('ok'));
+
+export default app;
+```
+
+The generated `.better-cf/entry.ts` resolves fetch handlers for object/function/named exports.
+
+## Legacy Cloudflare Compatibility (Service Worker Adapter)
+
+Set compatibility mode in `better-cf.config.ts`:
+
+```ts
+export const betterCfConfig = {
+  legacyServiceWorker: true
+};
+```
+
+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`:
+
+```ts
+import { testQueue } from 'better-cf/testing';
+
+const result = await testQueue(queueHandle, {
+  env: mockEnv,
+  message: { id: '1' }
+});
+```
+
+## Compatibility Matrix
+
+- 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
+
+## Not Supported (v1)
+
+- 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.
+
+## 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.
+
+## Roadmap
+
+Planned future namespaces:
+
+- `better-cf/workflow`
+- `better-cf/durable-object`

package/bin/better-cf.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { run } from '../dist/cli/index.js';
+
+run(process.argv.slice(2));

package/dist/cli/index.d.ts

@@ -0,0 +1,3 @@
+declare function run(argv?: string[]): Promise<void>;
+
+export { run };