1# Workers Patterns
2 
3## Error Handling
4 
5```typescript
6class HTTPError extends Error {
7  constructor(public status: number, message: string) { super(message); }
8}
9 
10export default {
11  async fetch(request: Request, env: Env): Promise<Response> {
12    try {
13      return await handleRequest(request, env);
14    } catch (error) {
15      if (error instanceof HTTPError) {
16        return new Response(JSON.stringify({ error: error.message }), {
17          status: error.status, headers: { 'Content-Type': 'application/json' }
18        });
19      }
20      return new Response('Internal Server Error', { status: 500 });
21    }
22  },
23};
24```
25 
26## CORS
27 
28```typescript
29const corsHeaders = { 'Access-Control-Allow-Origin': '*', 'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS' };
30if (request.method === 'OPTIONS') return new Response(null, { headers: corsHeaders });
31```
32 
33## Routing
34 
35```typescript
36const router = { 'GET /api/users': handleGetUsers, 'POST /api/users': handleCreateUser };
37 
38const handler = router[`${request.method} ${url.pathname}`];
39return handler ? handler(request, env) : new Response('Not Found', { status: 404 });
40```
41 
42**Production**: Use Hono, itty-router, or Worktop (see [frameworks.md](./frameworks.md))
43 
44## Request Validation (Zod)
45 
46```typescript
47import { z } from 'zod';
48 
49const userSchema = z.object({
50  name: z.string().min(1).max(100),
51  email: z.string().email(),
52  age: z.number().int().positive().optional(),
53});
54 
55async function handleCreateUser(request: Request) {
56  try {
57    const body = await request.json();
58    const validated = userSchema.parse(body);  // Throws on invalid data
59    return new Response(JSON.stringify({ id: 1, ...validated }), {
60      status: 201,
61      headers: { 'Content-Type': 'application/json' },
62    });
63  } catch (err) {
64    if (err instanceof z.ZodError) {
65      return new Response(JSON.stringify({ errors: err.errors }), { status: 400 });
66    }
67    throw err;
68  }
69}
70```
71 
72**With Hono**: Use `@hono/zod-validator` for automatic validation (see [frameworks.md](./frameworks.md))
73 
74## Performance
75 
76```typescript
77// ❌ Sequential
78const user = await fetch('/api/user/1');
79const posts = await fetch('/api/posts?user=1');
80 
81// ✅ Parallel
82const [user, posts] = await Promise.all([fetch('/api/user/1'), fetch('/api/posts?user=1')]);
83```
84 
85## Streaming
86 
87```typescript
88const stream = new ReadableStream({
89  async start(controller) {
90    for (let i = 0; i < 1000; i++) {
91      controller.enqueue(new TextEncoder().encode(`Item ${i}\n`));
92      if (i % 100 === 0) await new Promise(r => setTimeout(r, 0));
93    }
94    controller.close();
95  }
96});
97```
98 
99## Transform Streams
100 
101```typescript
102response.body.pipeThrough(new TextDecoderStream()).pipeThrough(
103  new TransformStream({ transform(chunk, c) { c.enqueue(chunk.toUpperCase()); } })
104).pipeThrough(new TextEncoderStream());
105```
106 
107## Testing
108 
109```typescript
110import { describe, it, expect } from 'vitest';
111import worker from '../src/index';
112 
113describe('Worker', () => {
114  it('returns 200', async () => {
115    const req = new Request('http://localhost/');
116    const env = { MY_VAR: 'test' };
117    const ctx = { waitUntil: () => {}, passThroughOnException: () => {} };
118    expect((await worker.fetch(req, env, ctx)).status).toBe(200);
119  });
120});
121```
122 
123## Deployment
124 
125```bash
126npx wrangler deploy              # production
127npx wrangler deploy --env staging
128npx wrangler versions upload --message "Add feature"
129npx wrangler rollback
130```
131 
132## Monitoring
133 
134```typescript
135const start = Date.now();
136const response = await handleRequest(request, env);
137ctx.waitUntil(env.ANALYTICS.writeDataPoint({
138  doubles: [Date.now() - start], blobs: [request.url, String(response.status)]
139}));
140```
141 
142## Security & Rate Limiting
143 
144```typescript
145// Security headers
146const security = { 'X-Content-Type-Options': 'nosniff', 'X-Frame-Options': 'DENY' };
147 
148// Auth
149const auth = request.headers.get('Authorization');
150if (!auth?.startsWith('Bearer ')) return new Response('Unauthorized', { status: 401 });
151 
152// Gradual rollouts (deterministic user bucketing)
153const hash = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(userId));
154if (new Uint8Array(hash)[0] % 100 < rolloutPercent) return newFeature(request);
155```
156 
157Rate limiting: See [Durable Objects](../durable-objects/README.md)
158 
159## R2 Multipart Upload
160 
161```typescript
162// For files > 100MB
163const upload = await env.MY_BUCKET.createMultipartUpload('large-file.bin');
164try {
165  const parts = [];
166  for (let i = 0; i < chunks.length; i++) {
167    parts.push(await upload.uploadPart(i + 1, chunks[i]));
168  }
169  await upload.complete(parts);
170} catch (err) { await upload.abort(); throw err; }
171```
172 
173Parallel uploads, resume on failure, handle files > 5GB
174 
175## Workflows (Step Orchestration)
176 
177```typescript
178import { WorkflowEntrypoint, WorkflowStep, WorkflowEvent } from 'cloudflare:workers';
179 
180export class MyWorkflow extends WorkflowEntrypoint {
181  async run(event: WorkflowEvent<{ userId: string }>, step: WorkflowStep) {
182    const user = await step.do('fetch-user', async () => 
183      fetch(`/api/users/${event.payload.userId}`).then(r => r.json())
184    );
185    await step.sleep('wait', '1 hour');
186    await step.do('notify', async () => sendEmail(user.email));
187  }
188}
189```
190 
191Multi-step jobs with automatic retries, state persistence, resume from failure
192 
193## See Also
194 
195- [API](./api.md) - Runtime APIs
196- [Gotchas](./gotchas.md) - Common issues
197- [Configuration](./configuration.md) - Setup
198- [Frameworks](./frameworks.md) - Hono, routing, validation
199