@wooksjs/event-http 0.6.5 → 0.7.0

package/skills/wooksjs-event-http/response.md

@@ -1,336 +1,267 @@
-# Response & Status — @wooksjs/event-http
+# Response API — @wooksjs/event-http
 
-> Covers setting status codes, response headers, outgoing cookies, cache control, and content type.
+> Status, headers, cookies, cache control, error handling, and response sending.
 
 ## Concepts
 
-In Wooks, the response is built through composables rather than mutating the `res` object directly. You call `useResponse()`, `useSetHeaders()`, `useSetCookies()`, etc. to configure the response. All settings are collected in the context store and applied when the framework sends the response.
+`useResponse()` returns an `HttpResponse` instance for the current request. All response operations — status, headers, cookies, cache control — are methods on this single object. Methods are chainable.
 
-The framework automatically handles content type detection, serialization, and status code defaults. You only need to explicitly set these when you want non-default behavior.
+The response is also controlled implicitly by return values: returning an object sends JSON, returning a string sends text, returning nothing sends 204.
 
-## `useResponse()`
+## API Reference
 
-Core response composable for status codes and raw response access:
+### `useResponse(ctx?): HttpResponse`
 
-```ts
-import { useResponse } from '@wooksjs/event-http'
-
-app.post('/users', () => {
-  const { status } = useResponse()
-  status(201)  // Set status to 201 Created
-  return { id: 1, name: 'Alice' }
-})
-```
-
-### Properties & methods
-
-| Name | Type | Description |
-|------|------|-------------|
-| `status(code?)` | `(code?) => EHttpStatusCode` | Get/set the response status code |
-| `rawResponse(opts?)` | `(opts?) => ServerResponse` | Access the raw Node.js response |
-| `hasResponded()` | `() => boolean` | True if response already sent |
-
-### `status()` as a hookable function
-
-The `status` function doubles as a hookable accessor:
+Returns the `HttpResponse` for the current request.
 
 ```ts
-const { status } = useResponse()
-
-// Set status
-status(404)
-
-// Read status (call without args)
-const currentStatus = status()
+import { useResponse } from '@wooksjs/event-http'
 
-// Or use .value (hooked property)
-status.value = 200
-console.log(status.value)  // 200
+const response = useResponse()
+response.setStatus(200).setHeader('x-custom', 'value')
 ```
 
-### Raw response access
+### Status
 
 ```ts
-const { rawResponse } = useResponse()
-
-// Passthrough mode: lets you write directly but still uses framework headers
-const res = rawResponse({ passthrough: true })
-res.write('chunk 1')
-
-// Default mode: marks response as "handled", framework won't write again
-const res2 = rawResponse()
-res2.writeHead(200)
-res2.end('done')
+response.status = 201 // set via property
+response.setStatus(201) // set via method (chainable)
+const code = response.status // get current status
 ```
 
-## `useStatus()`
+If not set explicitly, status is inferred automatically (see core.md Auto-status).
 
-Standalone status hook — returns a hookable accessor for the status code:
+### Headers
 
 ```ts
-import { useStatus } from '@wooksjs/event-http'
-
-app.get('/check', () => {
-  const statusHook = useStatus()
-  statusHook.value = 202
-  return 'Accepted'
-})
+response.setHeader('x-custom', 'value') // set a header (chainable)
+response.setHeaders({ 'x-one': '1', 'x-two': '2' }) // batch-set headers
+response.setHeader('x-multi', ['a', 'b']) // multi-value header
+response.getHeader('x-custom') // get header value
+response.removeHeader('x-custom') // remove a header (chainable)
+response.headers() // all headers as Record
+response.setContentType('application/xml') // shorthand for content-type
+response.getContentType() // get content-type
+response.enableCors('*') // set Access-Control-Allow-Origin (chainable)
 ```
 
-This is useful when a utility function needs to set the status without pulling in the full `useResponse()`.
+### Cookies (outgoing)
 
-### Type: `TStatusHook`
+Set-Cookie headers are managed via `HttpResponse`:
 
 ```ts
-import type { TStatusHook } from '@wooksjs/event-http'
+response.setCookie('session', 'abc123', {
+  httpOnly: true,
+  secure: true,
+  sameSite: 'Strict',
+  maxAge: 3600, // seconds (also accepts time strings)
+  path: '/',
+  domain: '.example.com',
+  expires: new Date('2025-12-31'),
+})
 
-function myMiddleware(status: TStatusHook) {
-  status.value = 403
-}
+response.getCookie('session') // { value, attrs } or undefined
+response.removeCookie('session')
+response.clearCookies()
+response.setCookieRaw('name=value; Path=/; HttpOnly') // raw Set-Cookie string
 ```
 
-## `useSetHeaders()`
-
-Set outgoing response headers:
-
-```ts
-import { useSetHeaders } from '@wooksjs/event-http'
+**`TCookieAttributes`:**
 
-app.get('/data', () => {
-  const { setHeader, setContentType, enableCors } = useSetHeaders()
+| Attribute  | Type                                     | Description        |
+| ---------- | ---------------------------------------- | ------------------ |
+| `expires`  | `Date \| string \| number`               | Expiration date    |
+| `maxAge`   | `number \| TTimeMultiString`             | Max age in seconds |
+| `domain`   | `string`                                 | Cookie domain      |
+| `path`     | `string`                                 | Cookie path        |
+| `secure`   | `boolean`                                | Secure flag        |
+| `httpOnly` | `boolean`                                | HttpOnly flag      |
+| `sameSite` | `boolean \| 'Lax' \| 'None' \| 'Strict'` | SameSite policy    |
 
-  setHeader('x-request-id', '12345')
-  setContentType('application/xml')
-  enableCors('https://example.com')
+### Cache control
 
-  return '<data>hello</data>'
+```ts
+response.setCacheControl({
+  public: true,
+  maxAge: 3600,
+  sMaxage: 7200,
+  noStore: false,
+  noCache: false,
+  mustRevalidate: true,
 })
+
+response.setAge(300) // Age header (seconds)
+response.setExpires(new Date('2025-12-31')) // Expires header
+response.setExpires('2025-12-31') // also accepts strings
+response.setPragmaNoCache() // Pragma: no-cache
 ```
 
-### Methods
+### Body and content type inference
 
-| Name | Signature | Description |
-|------|-----------|-------------|
-| `setHeader` | `(name, value) => void` | Set a response header |
-| `getHeader` | `(name) => string \| undefined` | Read a previously set header |
-| `removeHeader` | `(name) => void` | Remove a set header |
-| `setContentType` | `(value) => void` | Shortcut for `setHeader('content-type', value)` |
-| `headers` | `() => Record<string, string>` | Get all set headers as an object |
-| `enableCors` | `(origin?) => void` | Set `Access-Control-Allow-Origin` (default `*`) |
+Return values are automatically serialized:
 
-## `useSetHeader(name)`
+| Return type                      | Content-Type          | Status         |
+| -------------------------------- | --------------------- | -------------- |
+| `string`                         | `text/plain`          | Auto           |
+| `number` / `boolean`             | `text/plain`          | Auto           |
+| `object` / `array`               | `application/json`    | Auto           |
+| `Buffer` / `Uint8Array`          | (none — set manually) | Auto           |
+| `Readable` stream                | (none — set manually) | Auto           |
+| `Response` (fetch)               | From fetch response   | Auto           |
+| `undefined` / `null` / no return | —                     | 204 No Content |
 
-Returns a hookable accessor for a single response header:
+### Raw response access
+
+For escape hatches (SSE, WebSocket upgrades, etc.):
 
 ```ts
-import { useSetHeader } from '@wooksjs/event-http'
+// Take full control — framework won't send anything
+const res = response.getRawRes()
+res.writeHead(200, { 'content-type': 'text/event-stream' })
+res.write('data: hello\n\n')
 
-const xRequestId = useSetHeader('x-request-id')
-xRequestId.value = '12345'
-console.log(xRequestId.value)     // '12345'
-console.log(xRequestId.isDefined) // true
+// Passthrough — you write to res, but framework still finalizes
+const res = response.getRawRes(true)
 ```
 
-### Type: `THeaderHook`
+### `responded` property
 
 ```ts
-import type { THeaderHook } from '@wooksjs/event-http'
-
-function setCorrelationId(header: THeaderHook) {
-  if (!header.isDefined) {
-    header.value = generateId()
-  }
+if (response.responded) {
+  // Response already sent — don't try to send again
 }
 ```
 
-## `useSetCookies()`
+## HttpError
 
-Set outgoing response cookies:
+For error responses, throw `HttpError`:
 
 ```ts
-import { useSetCookies } from '@wooksjs/event-http'
+import { HttpError } from '@wooksjs/event-http'
 
-app.post('/login', () => {
-  const { setCookie, removeCookie, clearCookies } = useSetCookies()
+throw new HttpError(404) // 404 with default message
+throw new HttpError(400, 'Invalid email') // 400 with custom message
+throw new HttpError(422, { message: 'Validation failed', fields: ['email'] }) // structured body
+```
 
-  setCookie('session_id', 'abc123', {
-    httpOnly: true,
-    secure: true,
-    sameSite: 'Strict',
-    maxAge: '7d',  // supports time strings like '1h', '30m', '7d'
-    path: '/',
-  })
+`HttpError` skips stack trace capture for performance (these are expected control-flow errors).
 
-  return { success: true }
-})
-```
+**Error rendering (`WooksHttpResponse`):**
 
-### Methods
+The default response class renders errors based on the `Accept` header:
 
-| Name | Signature | Description |
-|------|-----------|-------------|
-| `setCookie` | `(name, value, attrs?) => void` | Set a response cookie |
-| `getCookie` | `(name) => TSetCookieData \| undefined` | Read a previously set cookie |
-| `removeCookie` | `(name) => void` | Remove a set cookie |
-| `clearCookies` | `() => void` | Remove all set cookies |
-| `cookies` | `() => string[]` | Render all cookies as Set-Cookie header strings |
+- `application/json` → JSON `{ statusCode, message, error }`
+- `text/html` → Styled HTML error page with SVG icons
+- `text/plain` → Plain text error
 
-### Cookie Attributes
+Override by providing a custom `responseClass` to `createHttpApp()`:
 
 ```ts
-interface TCookieAttributes {
-  expires: Date | string | number       // expiration date
-  maxAge: number | TTimeMultiString     // max age (seconds or time string)
-  domain: string                        // cookie domain
-  path: string                          // cookie path
-  secure: boolean                       // HTTPS only
-  httpOnly: boolean                     // no JS access
-  sameSite: boolean | 'Lax' | 'None' | 'Strict'
+class MyResponse extends WooksHttpResponse {
+  protected renderError(data, ctx) {
+    this._status = data.statusCode
+    this._headers['content-type'] = 'application/json'
+    this._body = JSON.stringify({ error: data.message })
+  }
 }
-```
 
-Time strings (`TTimeMultiString`) support formats like `'1h'`, `'30m'`, `'7d'`, `'1y'`.
+const app = createHttpApp({ responseClass: MyResponse })
+```
 
-## `useSetCookie(name)`
+### Default headers and security headers
 
-Hookable accessor for a single outgoing cookie:
+Pre-populate response headers for every request via `defaultHeaders`:
 
 ```ts
-import { useSetCookie } from '@wooksjs/event-http'
-
-const sessionCookie = useSetCookie('session_id')
+import { createHttpApp, securityHeaders } from '@wooksjs/event-http'
 
-// Set value
-sessionCookie.value = 'abc123'
-
-// Set attributes
-sessionCookie.attrs = { httpOnly: true, secure: true }
-
-// Read
-console.log(sessionCookie.value)  // 'abc123'
-console.log(sessionCookie.attrs)  // { httpOnly: true, secure: true }
+const app = createHttpApp({ defaultHeaders: securityHeaders() })
 ```
 
-### Type: `TCookieHook`
-
-```ts
-import type { TCookieHook } from '@wooksjs/event-http'
-
-function enforceSecureCookie(cookie: TCookieHook) {
-  cookie.attrs = { ...cookie.attrs, secure: true, httpOnly: true }
-}
-```
+`securityHeaders(opts?)` returns recommended HTTP security headers:
 
-## `useSetCacheControl()`
+| Header                         | Default                                                                           |
+| ------------------------------ | --------------------------------------------------------------------------------- |
+| `content-security-policy`      | `default-src 'self'; base-uri 'self'; form-action 'self'; frame-ancestors 'self'` |
+| `cross-origin-opener-policy`   | `same-origin`                                                                     |
+| `cross-origin-resource-policy` | `same-origin`                                                                     |
+| `referrer-policy`              | `no-referrer`                                                                     |
+| `x-content-type-options`       | `nosniff`                                                                         |
+| `x-frame-options`              | `SAMEORIGIN`                                                                      |
 
-Set cache-related response headers:
+Options: `string` (override) or `false` (disable). `strictTransportSecurity` is opt-in only.
 
 ```ts
-import { useSetCacheControl } from '@wooksjs/event-http'
-
-app.get('/assets/:file', () => {
-  const { setCacheControl, setExpires, setAge, setPragmaNoCache } = useSetCacheControl()
-
-  setCacheControl({
-    maxAge: 3600,
-    public: true,
-    noTransform: true,
-  })
-
-  // Or set individual cache headers
-  setAge(300)                   // Age: 300
-  setExpires(new Date('2025-12-31'))  // Expires: Wed, 31 Dec 2025 ...
-  setPragmaNoCache()            // Pragma: no-cache
-
-  return serveFile(...)
+securityHeaders({
+  contentSecurityPolicy: false,
+  referrerPolicy: 'strict-origin-when-cross-origin',
+  strictTransportSecurity: 'max-age=31536000; includeSubDomains',
 })
 ```
 
-### Cache-Control Directives
+Per-endpoint: `response.setHeaders(securityHeaders({ ... }))`.
 
-```ts
-interface TCacheControl {
-  maxAge?: number | TTimeMultiString
-  sMaxage?: number | TTimeMultiString
-  noCache?: boolean
-  noStore?: boolean
-  noTransform?: boolean
-  mustRevalidate?: boolean
-  proxyRevalidate?: boolean
-  public?: boolean
-  private?: boolean
-  immutable?: boolean
-  staleWhileRevalidate?: number | TTimeMultiString
-  staleIfError?: number | TTimeMultiString
-}
-```
-
-## Content Type Auto-Detection
-
-The framework automatically sets the content type based on the handler return value:
-
-| Return type | Content-Type |
-|-------------|-------------|
-| `string` | `text/plain` |
-| `number` | `text/plain` |
-| `boolean` | `text/plain` |
-| `object` / `array` | `application/json` |
-| `Readable` stream | (must set manually) |
-| `undefined` | (no body, 204) |
+## Common Patterns
 
-Override by calling `setContentType()` before returning:
+### Pattern: Full response control
 
 ```ts
-app.get('/html', () => {
-  const { setContentType } = useSetHeaders()
-  setContentType('text/html')
-  return '<h1>Hello</h1>'
+app.get('/data', () => {
+  useResponse()
+    .setStatus(200)
+    .setHeader('x-request-id', useRequest().reqId())
+    .setCookie('visited', 'true', { httpOnly: true })
+    .setCacheControl({ public: true, maxAge: 3600 })
+
+  return { data: 'hello' }
 })
 ```
 
-## Common Patterns
-
-### Pattern: JSON API Response
+### Pattern: Redirect
 
 ```ts
-app.get('/api/users/:id', async () => {
-  const { get } = useRouteParams<{ id: string }>()
-  const user = await db.findUser(get('id'))
-  if (!user) throw new HttpError(404, 'User not found')
-  return user  // auto-serialized as JSON with 200
+app.get('/old-path', () => {
+  useResponse().setStatus(301).setHeader('location', '/new-path')
 })
 ```
 
-### Pattern: File Download
+### Pattern: Streaming response
 
 ```ts
-app.get('/download/:file', () => {
-  const { setHeader } = useSetHeaders()
-  const { get } = useRouteParams<{ file: string }>()
-  setHeader('content-disposition', `attachment; filename="${get('file')}"`)
-  return createReadStream(`/uploads/${get('file')}`)
+import { createReadStream } from 'fs'
+
+app.get('/file', () => {
+  useResponse().setContentType('application/octet-stream')
+  return createReadStream('/path/to/file')
 })
 ```
 
-### Pattern: Redirect
+### Pattern: Server-Sent Events
 
 ```ts
-import { BaseHttpResponse } from '@wooksjs/event-http'
-
-app.get('/old-page', () => {
-  return new BaseHttpResponse().setStatus(302).setHeader('location', '/new-page')
+app.get('/events', () => {
+  const res = useResponse().getRawRes()
+  res.writeHead(200, {
+    'content-type': 'text/event-stream',
+    'cache-control': 'no-cache',
+    connection: 'keep-alive',
+  })
+  // Write events...
+  return res // returning the raw response signals "already handled"
 })
 ```
 
 ## Best Practices
 
-- **Let the framework auto-detect content type** — Only call `setContentType()` when you need a non-default type.
-- **Use `useSetCookies()` for multiple cookies, `useSetCookie(name)` for hookable access to a single cookie**.
-- **Set status before returning** — If you need a custom status, call `status(code)` before the handler returns.
-- **Use time strings for maxAge** — `'7d'` is clearer than `604800`.
+- Return values for simple responses — only use `useResponse()` when you need headers, cookies, or explicit status
+- Use `HttpError` for all error responses — don't manually set error status and body
+- The chainable API means you can do `useResponse().setStatus(200).setHeader(...)` in one statement
+- For custom error rendering, subclass `WooksHttpResponse` and override `renderError()`
 
 ## Gotchas
 
-- If you call `rawResponse()` without `{ passthrough: true }`, the framework marks the response as sent and won't write anything else.
-- Headers set via `useSetHeaders()` are merged with any `BaseHttpResponse` headers. The `BaseHttpResponse` headers take precedence on collision.
-- Cookies set via `useSetCookies()` are merged with `BaseHttpResponse.setCookie()` cookies.
+- Calling `send()` twice throws — check `response.responded` if unsure
+- `getRawRes()` without `passthrough` marks the response as "responded" — the framework won't touch it
+- `getRawRes(true)` (passthrough mode) lets you write headers/data while the framework still finalizes cookies and status
+- Cookie `maxAge` is in seconds, not milliseconds
+- `setContentType()` overwrites any previously set content-type

package/skills/wooksjs-event-http/testing.md

@@ -0,0 +1,150 @@
+# Testing — @wooksjs/event-http
+
+> Writing tests for handlers and composables with `prepareTestHttpContext`.
+
+## Concepts
+
+`prepareTestHttpContext` creates a fully initialized HTTP event context for testing. It sets up an `EventContext` with `httpKind` seeds (fake `IncomingMessage`, `HttpResponse`, route params, and optional pre-seeded body), then returns a runner function that executes callbacks inside the context scope.
+
+## API Reference
+
+### `prepareTestHttpContext(options): (cb) => T`
+
+```ts
+import { prepareTestHttpContext } from '@wooksjs/event-http'
+```
+
+**Options (`TTestHttpContext`):**
+
+| Option           | Type                                 | Required | Description                                     |
+| ---------------- | ------------------------------------ | -------- | ----------------------------------------------- |
+| `url`            | `string`                             | Yes      | Request URL (e.g. `/api/users?page=1`)          |
+| `method`         | `string`                             | No       | HTTP method (default: `'GET'`)                  |
+| `headers`        | `Record<string, string>`             | No       | Request headers                                 |
+| `params`         | `Record<string, string \| string[]>` | No       | Pre-set route parameters                        |
+| `requestLimits`  | `TRequestLimits`                     | No       | Custom request limits                           |
+| `rawBody`        | `string \| Buffer`                   | No       | Pre-seed the raw body (skips stream reading)    |
+| `defaultHeaders` | `Record<string, string \| string[]>` | No       | Default headers to pre-populate on the response |
+
+**Returns:** `(cb: () => T) => T` — a runner function.
+
+```ts
+const run = prepareTestHttpContext({
+  url: '/users/42',
+  method: 'GET',
+  headers: { authorization: 'Bearer abc123' },
+  params: { id: '42' },
+})
+
+run(() => {
+  // All composables work here
+  const { method } = useRequest()
+  const { params } = useRouteParams()
+  const { authIs } = useAuthorization()
+  expect(method).toBe('GET')
+  expect(params.id).toBe('42')
+  expect(authIs('bearer')).toBe(true)
+})
+```
+
+## Common Patterns
+
+### Pattern: Testing a custom composable
+
+```ts
+import { describe, it, expect } from 'vitest'
+import { prepareTestHttpContext, useHeaders } from '@wooksjs/event-http'
+import { defineWook, cached } from '@wooksjs/event-core'
+
+const useApiKey = defineWook((ctx) => {
+  const headers = useHeaders(ctx)
+  return {
+    apiKey: headers['x-api-key'] as string | undefined,
+    isValid: () => headers['x-api-key'] === 'secret',
+  }
+})
+
+describe('useApiKey', () => {
+  it('extracts API key from headers', () => {
+    const run = prepareTestHttpContext({
+      url: '/api/data',
+      headers: { 'x-api-key': 'secret' },
+    })
+
+    run(() => {
+      const { apiKey, isValid } = useApiKey()
+      expect(apiKey).toBe('secret')
+      expect(isValid()).toBe(true)
+    })
+  })
+})
+```
+
+### Pattern: Testing body parsing
+
+```ts
+import { useBody } from '@wooksjs/http-body'
+
+it('parses JSON body', async () => {
+  const run = prepareTestHttpContext({
+    url: '/api/users',
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    rawBody: JSON.stringify({ name: 'Alice' }),
+  })
+
+  await run(async () => {
+    const { parseBody } = useBody()
+    const body = await parseBody<{ name: string }>()
+    expect(body.name).toBe('Alice')
+  })
+})
+```
+
+### Pattern: Testing response composable
+
+```ts
+it('sets response headers', () => {
+  const run = prepareTestHttpContext({ url: '/test' })
+
+  run(() => {
+    const response = useResponse()
+    response.setHeader('x-custom', 'value')
+    response.setCookie('session', 'abc', { httpOnly: true })
+
+    expect(response.getHeader('x-custom')).toBe('value')
+    expect(response.getCookie('session')?.value).toBe('abc')
+  })
+})
+```
+
+### Pattern: Testing cookies
+
+```ts
+it('reads cookies from request', () => {
+  const run = prepareTestHttpContext({
+    url: '/dashboard',
+    headers: { cookie: 'session=abc123; theme=dark' },
+  })
+
+  run(() => {
+    const { getCookie } = useCookies()
+    expect(getCookie('session')).toBe('abc123')
+    expect(getCookie('theme')).toBe('dark')
+    expect(getCookie('missing')).toBeNull()
+  })
+})
+```
+
+## Best Practices
+
+- Always use `prepareTestHttpContext` — don't manually construct `EventContext` for HTTP tests
+- Pre-seed `rawBody` for body parsing tests to avoid stream setup
+- Pre-seed `params` to test route parameter logic without a router
+- The runner function supports async callbacks — `await run(async () => { ... })`
+
+## Gotchas
+
+- `prepareTestHttpContext` uses a real `IncomingMessage` and `ServerResponse` (from `new Socket({})`) — they're functional but not connected to a network
+- The `HttpResponse` in tests is the base `HttpResponse`, not `WooksHttpResponse` — error rendering won't do content negotiation
+- `rawBody` pre-seeding stores a resolved Promise — `useRequest().rawBody()` returns immediately