# Workerd APIs

## Worker Code (JS/TS)

### ES Modules (Recommended)

```javascript
export default {
  async fetch(request, env, ctx) {
    const value = await env.KV.get('key') // Bindings in env
    const response = await env.API.fetch(request) // Service binding
    ctx.waitUntil(logRequest(request)) // Background task
    return new Response('OK')
  },
  async adminApi(request, env, ctx) {
    /* Named entrypoint */
  },
  async queue(batch, env, ctx) {
    /* Queue consumer */
  },
  async scheduled(event, env, ctx) {
    /* Cron handler */
  },
}
```

### TypeScript Types

**Generate from wrangler.toml (Recommended):**

```bash
wrangler types  # Output: worker-configuration.d.ts
```

**Manual types:**

```typescript
interface Env {
  API: Fetcher
  CACHE: KVNamespace
  STORAGE: R2Bucket
  ROOMS: DurableObjectNamespace
  API_KEY: string
}

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    return new Response(await env.CACHE.get('key'))
  },
}
```

**Setup:**

```bash
npm install -D @cloudflare/workers-types
```

```json
// tsconfig.json
{ "compilerOptions": { "types": ["@cloudflare/workers-types"] } }
```

### Service Worker Syntax (Legacy)

```javascript
addEventListener('fetch', (event) => {
  event.respondWith(handleRequest(event.request))
})

async function handleRequest(request) {
  const value = await KV.get('key') // Bindings as globals
  return new Response('OK')
}
```

### Durable Objects

```javascript
export class Room {
  constructor(state, env) {
    this.state = state
    this.env = env
  }

  async fetch(request) {
    const url = new URL(request.url)
    if (url.pathname === '/increment') {
      const value = (await this.state.storage.get('counter')) || 0
      await this.state.storage.put('counter', value + 1)
      return new Response(String(value + 1))
    }
    return new Response('Not found', { status: 404 })
  }
}
```

### RPC Between Services

```javascript
// Caller: env.AUTH.validateToken(token) returns structured data
const user = await env.AUTH.validateToken(request.headers.get('Authorization'))

// Callee: export methods that return data
export default {
  async validateToken(token) {
    return { id: 123, name: 'Alice' }
  },
}
```

## Web Platform APIs

### Fetch

- `fetch()`, `Request`, `Response`, `Headers`
- `AbortController`, `AbortSignal`

### Streams

- `ReadableStream`, `WritableStream`, `TransformStream`
- Byte streams, BYOB readers

### Web Crypto

- `crypto.subtle` (encrypt/decrypt/sign/verify)
- `crypto.randomUUID()`, `crypto.getRandomValues()`

### Encoding

- `TextEncoder`, `TextDecoder`
- `atob()`, `btoa()`

### Web Standards

- `URL`, `URLSearchParams`
- `Blob`, `File`, `FormData`
- `WebSocket`

### Server-Sent Events (EventSource)

```javascript
// Server-side SSE
const { readable, writable } = new TransformStream()
const writer = writable.getWriter()
writer.write(new TextEncoder().encode('data: Hello\n\n'))
return new Response(readable, { headers: { 'Content-Type': 'text/event-stream' } })
```

### HTMLRewriter (HTML Parsing/Transformation)

```javascript
const response = await fetch('https://example.com')
return new HTMLRewriter()
  .on('a[href]', {
    element(el) {
      el.setAttribute('href', `/proxy?url=${encodeURIComponent(el.getAttribute('href'))}`)
    },
  })
  .on('script', {
    element(el) {
      el.remove()
    },
  })
  .transform(response)
```

### TCP Sockets (Experimental)

```javascript
const socket = await connect({ hostname: 'example.com', port: 80 })
const writer = socket.writable.getWriter()
await writer.write(new TextEncoder().encode('GET / HTTP/1.1\r\n\r\n'))
const reader = socket.readable.getReader()
const { value } = await reader.read()
return new Response(value)
```

### Performance

- `performance.now()`, `performance.timeOrigin`
- `setTimeout()`, `setInterval()`, `queueMicrotask()`

### Console

- `console.log()`, `console.error()`, `console.warn()`

### Node.js Compat (`nodejs_compat` flag)

```javascript
import { Buffer } from 'node:buffer'
import { randomBytes } from 'node:crypto'

const buf = Buffer.from('Hello')
const random = randomBytes(16)
```

**Available:** `node:buffer`, `node:crypto`, `node:stream`, `node:util`, `node:events`, `node:assert`, `node:path`, `node:querystring`, `node:url`
**NOT available:** `node:fs`, `node:http`, `node:net`, `node:child_process`

## CLI Commands

```bash
workerd serve config.capnp [constantName]          # Start server
workerd serve config.capnp --socket-addr http=*:3000 --verbose
workerd compile config.capnp constantName -o binary  # Compile to binary
workerd test config.capnp [--test-only=test.js]    # Run tests
```

## Wrangler Integration

Use Wrangler for development:

```bash
wrangler dev     # Uses workerd internally
wrangler types   # Generate TypeScript types from wrangler.toml
```

See [patterns.md](./patterns.md) for usage examples, [configuration.md](./configuration.md) for config details.