1# Workerd APIs
2 
3## Worker Code (JS/TS)
4 
5### ES Modules (Recommended)
6```javascript
7export default {
8  async fetch(request, env, ctx) {
9    const value = await env.KV.get("key");           // Bindings in env
10    const response = await env.API.fetch(request);   // Service binding
11    ctx.waitUntil(logRequest(request));              // Background task
12    return new Response("OK");
13  },
14  async adminApi(request, env, ctx) { /* Named entrypoint */ },
15  async queue(batch, env, ctx) { /* Queue consumer */ },
16  async scheduled(event, env, ctx) { /* Cron handler */ }
17};
18```
19 
20### TypeScript Types
21 
22**Generate from wrangler.toml (Recommended):**
23```bash
24wrangler types  # Output: worker-configuration.d.ts
25```
26 
27**Manual types:**
28```typescript
29interface Env {
30  API: Fetcher;
31  CACHE: KVNamespace;
32  STORAGE: R2Bucket;
33  ROOMS: DurableObjectNamespace;
34  API_KEY: string;
35}
36 
37export default {
38  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
39    return new Response(await env.CACHE.get("key"));
40  }
41};
42```
43 
44**Setup:**
45```bash
46npm install -D @cloudflare/workers-types
47```
48 
49```json
50// tsconfig.json
51{"compilerOptions": {"types": ["@cloudflare/workers-types"]}}
52```
53 
54### Service Worker Syntax (Legacy)
55```javascript
56addEventListener('fetch', event => {
57  event.respondWith(handleRequest(event.request));
58});
59 
60async function handleRequest(request) {
61  const value = await KV.get("key");  // Bindings as globals
62  return new Response("OK");
63}
64```
65 
66### Durable Objects
67```javascript
68export class Room {
69  constructor(state, env) { this.state = state; this.env = env; }
70  
71  async fetch(request) {
72    const url = new URL(request.url);
73    if (url.pathname === "/increment") {
74      const value = (await this.state.storage.get("counter")) || 0;
75      await this.state.storage.put("counter", value + 1);
76      return new Response(String(value + 1));
77    }
78    return new Response("Not found", {status: 404});
79  }
80}
81```
82 
83### RPC Between Services
84```javascript
85// Caller: env.AUTH.validateToken(token) returns structured data
86const user = await env.AUTH.validateToken(request.headers.get("Authorization"));
87 
88// Callee: export methods that return data
89export default {
90  async validateToken(token) { return {id: 123, name: "Alice"}; }
91};
92```
93 
94## Web Platform APIs
95 
96### Fetch
97- `fetch()`, `Request`, `Response`, `Headers`
98- `AbortController`, `AbortSignal`
99 
100### Streams
101- `ReadableStream`, `WritableStream`, `TransformStream`
102- Byte streams, BYOB readers
103 
104### Web Crypto
105- `crypto.subtle` (encrypt/decrypt/sign/verify)
106- `crypto.randomUUID()`, `crypto.getRandomValues()`
107 
108### Encoding
109- `TextEncoder`, `TextDecoder`
110- `atob()`, `btoa()`
111 
112### Web Standards
113- `URL`, `URLSearchParams`
114- `Blob`, `File`, `FormData`
115- `WebSocket`
116 
117### Server-Sent Events (EventSource)
118```javascript
119// Server-side SSE
120const { readable, writable } = new TransformStream();
121const writer = writable.getWriter();
122writer.write(new TextEncoder().encode('data: Hello\n\n'));
123return new Response(readable, {headers: {'Content-Type': 'text/event-stream'}});
124```
125 
126### HTMLRewriter (HTML Parsing/Transformation)
127```javascript
128const response = await fetch('https://example.com');
129return new HTMLRewriter()
130  .on('a[href]', {
131    element(el) {
132      el.setAttribute('href', `/proxy?url=${encodeURIComponent(el.getAttribute('href'))}`);
133    }
134  })
135  .on('script', { element(el) { el.remove(); } })
136  .transform(response);
137```
138 
139### TCP Sockets (Experimental)
140```javascript
141const socket = await connect({ hostname: 'example.com', port: 80 });
142const writer = socket.writable.getWriter();
143await writer.write(new TextEncoder().encode('GET / HTTP/1.1\r\n\r\n'));
144const reader = socket.readable.getReader();
145const { value } = await reader.read();
146return new Response(value);
147```
148 
149### Performance
150- `performance.now()`, `performance.timeOrigin`
151- `setTimeout()`, `setInterval()`, `queueMicrotask()`
152 
153### Console
154- `console.log()`, `console.error()`, `console.warn()`
155 
156### Node.js Compat (`nodejs_compat` flag)
157```javascript
158import { Buffer } from 'node:buffer';
159import { randomBytes } from 'node:crypto';
160 
161const buf = Buffer.from('Hello');
162const random = randomBytes(16);
163```
164 
165**Available:** `node:buffer`, `node:crypto`, `node:stream`, `node:util`, `node:events`, `node:assert`, `node:path`, `node:querystring`, `node:url`
166**NOT available:** `node:fs`, `node:http`, `node:net`, `node:child_process`
167 
168## CLI Commands
169 
170```bash
171workerd serve config.capnp [constantName]          # Start server
172workerd serve config.capnp --socket-addr http=*:3000 --verbose
173workerd compile config.capnp constantName -o binary  # Compile to binary
174workerd test config.capnp [--test-only=test.js]    # Run tests
175```
176 
177## Wrangler Integration
178 
179Use Wrangler for development:
180```bash
181wrangler dev     # Uses workerd internally
182wrangler types   # Generate TypeScript types from wrangler.toml
183```
184 
185See [patterns.md](./patterns.md) for usage examples, [configuration.md](./configuration.md) for config details.
186