@wooksjs/event-http 0.6.6 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wooksjs/event-http",
-  "version": "0.6.6",
+  "version": "0.7.0",
   "description": "@wooksjs/event-http",
   "keywords": [
     "api",
@@ -26,7 +26,7 @@
     "directory": "packages/event-http"
   },
   "bin": {
-    "setup-skills": "scripts/setup-skills.js"
+    "wooksjs-event-http-skill": "scripts/setup-skills.js"
   },
   "files": [
     "dist",
@@ -47,14 +47,14 @@
   "devDependencies": {
     "typescript": "^5.9.3",
     "vitest": "^3.2.4",
-    "@wooksjs/event-core": "^0.6.6",
-    "wooks": "^0.6.6"
+    "@wooksjs/event-core": "^0.7.0",
+    "wooks": "^0.7.0"
   },
   "peerDependencies": {
     "@prostojs/logger": "^0.4.3",
-    "@prostojs/router": "^0.3.1",
-    "@wooksjs/event-core": "^0.6.6",
-    "wooks": "^0.6.6"
+    "@prostojs/router": "^0.3.2",
+    "@wooksjs/event-core": "^0.7.0",
+    "wooks": "^0.7.0"
   },
   "scripts": {
     "build": "rolldown -c ../../rolldown.config.mjs",

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

@@ -1,37 +1,44 @@
 ---
 name: wooksjs-event-http
-description: Wooks HTTP framework — composable, lazy-evaluated HTTP server for Node.js. Load when building HTTP apps or REST APIs with wooks; defining routes or using the wooks router; using use-composables (useRequest, useResponse, useCookies, useHeaders, useBody, useProxy, useSearchParams, useRouteParams, useAuthorization, useSetHeaders, useSetCookies, useStatus, useAccept, useSetCacheControl); creating custom event context composables; working with @wooksjs/event-core context store (init, get, set, hook); serving static files; proxying requests; handling HTTP errors; setting status codes, content types, or cache control.
+description: Use this skill when working with @wooksjs/event-http — to create HTTP servers with createHttpApp(), register route handlers with app.get()/post()/put()/patch()/delete(), read request data with useRequest()/useHeaders()/useCookies()/useSearchParams()/useAuthorization()/useAccept(), control responses with useResponse() and HttpResponse (status, headers, cookies, cache control, streaming), throw HTTP errors with HttpError, test handlers with prepareTestHttpContext(), or integrate with existing Node.js servers via getServerCb().
 ---
 
 # @wooksjs/event-http
 
-A composable HTTP framework for Node.js built on async context (AsyncLocalStorage). Instead of middleware chains and mutated `req`/`res` objects, you call composable functions (`useRequest()`, `useCookies()`, etc.) anywhere in your handler — values are computed on demand and cached per request.
+HTTP adapter for Wooks. Composable-based request handling where every piece of data is available on demand, typed, and cached per request. No middleware, no `req`/`res` parameters — just function calls.
 
 ## How to use this skill
 
 Read the domain file that matches the task. Do not load all files — only what you need.
 
-| Domain | File | Load when... |
-|--------|------|------------|
-| Event context (core machinery) | [event-core.md](event-core.md) | Understanding the context store API (`init`/`get`/`set`/`hook`), creating custom composables, lazy evaluation and caching, building your own `use*()` functions |
-| HTTP app setup | [core.md](core.md) | Creating an HTTP app, server lifecycle, `createHttpApp`, `getServerCb`, testing with `prepareTestHttpContext`, logging |
-| Routing | [routing.md](routing.md) | Defining routes, route params (`:id`), wildcards (`*`), regex constraints (`:id(\\d+)`), optional params (`:tab?`), repeated params, path builders, HTTP method shortcuts, handler return values, router config |
-| Request utilities | [request.md](request.md) | `useRequest`, `useHeaders`, `useCookies`, `useSearchParams`, `useAuthorization`, `useAccept`, `useEventId`, reading IP, body limits |
-| Response & status | [response.md](response.md) | `useResponse`, `useStatus`, `useSetHeaders`, `useSetHeader`, `useSetCookies`, `useSetCookie`, `useSetCacheControl`, content type, status hooks, cookie hooks |
-| Error handling | [error-handling.md](error-handling.md) | `HttpError`, throwing errors, custom error bodies, error rendering, guard patterns |
-| Addons (body, static, proxy) | [addons.md](addons.md) | `useBody` (body parsing), `serveFile` (static files), `useProxy` (request proxying) |
+| Domain               | File                       | Load when...                                                                           |
+| -------------------- | -------------------------- | -------------------------------------------------------------------------------------- |
+| Core setup & routing | [core.md](core.md)         | Creating an app, registering routes, starting a server, understanding the architecture |
+| Request composables  | [request.md](request.md)   | Reading request data: headers, cookies, query params, body, authorization, IP          |
+| Response API         | [response.md](response.md) | Setting status, headers, cookies, cache control, sending responses, error handling     |
+| Testing              | [testing.md](testing.md)   | Writing tests for handlers and composables with `prepareTestHttpContext`               |
 
 ## Quick reference
 
 ```ts
-import { createHttpApp, useRouteParams } from '@wooksjs/event-http'
-
-const app = createHttpApp()
-app.get('/hello/:name', () => {
-  const { get } = useRouteParams<{ name: string }>()
-  return { greeting: `Hello ${get('name')}!` }
-})
-app.listen(3000)
+import { createHttpApp } from '@wooksjs/event-http'
+
+// Composables (no arguments — context via AsyncLocalStorage)
+import {
+  useRequest,
+  useResponse,
+  useHeaders,
+  useCookies,
+  useSearchParams,
+  useAuthorization,
+  useAccept,
+  useRouteParams,
+  useLogger,
+} from '@wooksjs/event-http'
+
+// Errors
+import { HttpError } from '@wooksjs/event-http'
+
+// Testing
+import { prepareTestHttpContext } from '@wooksjs/event-http'
 ```
-
-Key composables: `useRequest()`, `useResponse()`, `useRouteParams()`, `useHeaders()`, `useSetHeaders()`, `useCookies()`, `useSetCookies()`, `useSearchParams()`, `useAuthorization()`, `useAccept()`, `useSetCacheControl()`, `useStatus()`, `useBody()`, `useProxy()`.

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

@@ -1,297 +1,152 @@
-# Core Concepts — @wooksjs/event-http
+# Core setup & routing — @wooksjs/event-http
 
-> Covers HTTP app creation, server setup, how the HTTP adapter integrates with the event context system, testing, and logging.
+> Creating an app, registering routes, server lifecycle, and architecture overview.
 
-For the underlying event context store API (`init`, `get`, `set`, `hook`, etc.) and how to create custom composables, see [event-core.md](event-core.md).
+## Concepts
 
-## Mental Model
+`@wooksjs/event-http` wraps a Node.js HTTP server with Wooks' composable architecture. Each incoming request gets its own `EventContext` (from `@wooksjs/event-core`), and handlers are plain functions that return their response. All request data is accessed through composables — on demand, typed, cached.
 
-`@wooksjs/event-http` is the HTTP adapter for Wooks. It turns every incoming HTTP request into an event with its own isolated context store. Instead of middleware chains and mutated `req`/`res` objects, you call composable functions (`useRequest()`, `useCookies()`, `useSetHeaders()`, etc.) from anywhere in your handler — values are computed on demand and cached per request.
-
-Key principles:
-1. **Never mutate `req`** — Accumulate request context in the store instead.
-2. **Never parse before needed** — Cookies, body, search params are only parsed when a composable is first called.
-3. **No middleware sprawl** — Composable functions replace middleware. Each one is a focused, importable utility.
+The adapter creates context, seeds it with the `IncomingMessage` and `HttpResponse`, looks up routes, and runs handlers. Handlers never receive `req`/`res` parameters.
 
 ## Installation
 
 ```bash
-npm install wooks @wooksjs/event-http
-```
-
-## Creating an HTTP App
-
-```ts
-import { createHttpApp } from '@wooksjs/event-http'
-
-const app = createHttpApp()
-
-app.get('/hello', () => 'Hello World!')
-
-app.listen(3000, () => {
-  console.log('Server running on port 3000')
-})
-```
-
-`createHttpApp(opts?, wooks?)` returns a `WooksHttp` instance. Options:
-
-```ts
-interface TWooksHttpOptions {
-  logger?: TConsoleBase          // custom logger
-  eventOptions?: TEventOptions   // event-level logger config
-  onNotFound?: TWooksHandler     // custom 404 handler
-  router?: {
-    ignoreTrailingSlash?: boolean // treat /path and /path/ as the same
-    ignoreCase?: boolean         // case-insensitive matching
-    cacheLimit?: number          // max cached parsed routes
-  }
-  requestLimits?: {              // app-level body limits (overridable per-request)
-    maxCompressed?: number       // default: 1 MB
-    maxInflated?: number         // default: 10 MB
-    maxRatio?: number            // default: 100 (zip-bomb protection)
-    readTimeoutMs?: number       // default: 10 000 ms
-  }
-}
+pnpm add @wooksjs/event-http
 ```
 
-Example — raise body limits for the entire app:
+Peer dependencies: `@wooksjs/event-core`, `wooks`, `@prostojs/router`, `@prostojs/logger`.
 
-```ts
-const app = createHttpApp({
-  requestLimits: {
-    maxCompressed: 50 * 1024 * 1024,  // 50 MB
-    maxInflated: 100 * 1024 * 1024,   // 100 MB
-    maxRatio: 200,
-  },
-})
-```
+## API Reference
 
-These defaults apply to every request but can still be overridden per-request via `useRequest()` (see [request.md](request.md)).
+### `createHttpApp(opts?): WooksHttp`
 
-## Using with an Existing Node.js Server
+Creates and returns a `WooksHttp` instance.
 
 ```ts
-import http from 'http'
 import { createHttpApp } from '@wooksjs/event-http'
 
 const app = createHttpApp()
 app.get('/hello', () => 'Hello World!')
-
-const server = http.createServer(app.getServerCb())
-server.listen(3000)
+app.listen(3000)
 ```
 
-## How HTTP Context Works
-
-When a request arrives, the adapter creates an HTTP-specific event context:
-
-```
-Request arrives (req, res)
-  → createHttpContext({ req, res }, options)
-    → AsyncLocalStorage.run(httpContextStore, handler)
-      → router matches path → handler runs
-        → handler calls useRequest(), useCookies(), etc.
-          → each composable calls useHttpContext()
-            → reads/writes the HTTP context store via init(), get(), set()
-```
+**Options (`TWooksHttpOptions`):**
 
-### The HTTP Context Store
+| Option          | Type                       | Description                                                   |
+| --------------- | -------------------------- | ------------------------------------------------------------- |
+| `logger`        | `TConsoleBase`             | Custom logger instance                                        |
+| `onNotFound`    | `TWooksHandler`            | Handler called when no route matches (default: 404 HttpError) |
+| `router`        | router options             | Custom router configuration                                   |
+| `requestLimits` | `Omit<TRequestLimits, 'perRequest'>` | Default body size/timeout limits for all requests             |
+| `responseClass` | `typeof WooksHttpResponse` | Custom response subclass (default: `WooksHttpResponse`)       |
+| `defaultHeaders` | `Record<string, string \| string[]>` | Default headers applied to every response (e.g. from `securityHeaders()`) |
 
-The HTTP adapter extends the base event context with these sections:
+### Route registration
 
 ```ts
-interface THttpContextStore {
-  searchParams?: TSearchParamsCache               // cached query params
-  cookies?: Record<string, string | null>          // cached parsed cookies
-  setCookies?: Record<string, TSetCookieData>      // outgoing response cookies
-  accept?: Record<string, boolean>                 // cached Accept header checks
-  authorization?: TAuthCache                       // cached auth header parsing
-  setHeader?: Record<string, string | string[]>    // outgoing response headers
-  request?: TRequestCache                          // cached request data (body, IP, etc.)
-  response?: { responded: boolean }                // response sent flag
-  status?: { code: EHttpStatusCode }               // response status code
-}
+app.get(path, handler)
+app.post(path, handler)
+app.put(path, handler)
+app.patch(path, handler)
+app.delete(path, handler)
+app.head(path, handler)
+app.options(path, handler)
+app.all(path, handler) // matches any HTTP method
 ```
 
-Every section is lazily initialized — it only exists when a composable first writes to it. This means zero overhead for unused features.
-
-### Extending the HTTP Store for Custom Composables
-
-When creating custom composables for HTTP, extend the store type via the generic parameter on `useHttpContext`:
+Handlers are plain functions. Return value becomes the response body:
 
 ```ts
-import { useHttpContext } from '@wooksjs/event-http'
-
-interface TMyStore {
-  myFeature?: {
-    parsedToken?: { userId: string; role: string } | null
-    isAdmin?: boolean
-  }
-}
-
-export function useMyFeature() {
-  const { store } = useHttpContext<TMyStore>()
-  const { init } = store('myFeature')
-
-  const parsedToken = () =>
-    init('parsedToken', () => {
-      const { authRawCredentials, isBearer } = useAuthorization()
-      if (!isBearer()) return null
-      return decodeToken(authRawCredentials()!)
-    })
-
-  const isAdmin = () =>
-    init('isAdmin', () => parsedToken()?.role === 'admin')
-
-  return { parsedToken, isAdmin }
-}
-```
-
-For the full context store API and more composable patterns, see [event-core.md](event-core.md).
-
-## Server Lifecycle
+app.get('/users/:id', () => {
+  const { params } = useRouteParams<{ id: string }>()
+  return { id: params.id } // → 200 application/json
+})
 
-### `listen(...)`
+app.post('/users', async () => {
+  const { parseBody } = useBody() // from @wooksjs/http-body
+  const user = await parseBody<{ name: string }>()
+  return { created: user.name } // → 201 application/json (POST auto-status)
+})
+```
 
-Starts a built-in HTTP server:
+### Server lifecycle
 
 ```ts
+// Start server
 await app.listen(3000)
 await app.listen(3000, '0.0.0.0')
-await app.listen({ port: 3000, host: '0.0.0.0' })
-```
-
-### `close(server?)`
 
-Stops the server:
-
-```ts
-await app.close()
-```
-
-### `getServer()`
-
-Returns the underlying `http.Server` instance (only available after `listen()`):
-
-```ts
-const server = app.getServer()
-```
-
-### `attachServer(server)`
-
-Attaches an external server so `close()` can stop it:
-
-```ts
+// Use with existing server
+import http from 'http'
 const server = http.createServer(app.getServerCb())
-app.attachServer(server)
 server.listen(3000)
-// later: await app.close()
+app.attachServer(server)
+
+// Stop server
+await app.close()
 ```
 
 ### `getServerCb()`
 
-Returns the raw `(req, res) => void` callback for use with any Node.js HTTP server:
+Returns a `(req, res) => void` callback for use with any Node.js HTTP server:
 
 ```ts
 const cb = app.getServerCb()
 http.createServer(cb).listen(3000)
-// or with https:
-https.createServer(sslOpts, cb).listen(443)
-```
-
-## Sharing Router Between Adapters
-
-Multiple adapters can share the same Wooks router:
-
-```ts
-import { Wooks } from 'wooks'
-import { createHttpApp } from '@wooksjs/event-http'
-
-const wooks = new Wooks()
-const app1 = createHttpApp({}, wooks)
-const app2 = createHttpApp({}, wooks)  // shares the same routes
+// or with https, http2, etc.
 ```
 
-Or share via another adapter instance:
+## Routing
 
-```ts
-const app1 = createHttpApp()
-const app2 = createHttpApp({}, app1)  // shares app1's router
-```
+Built on [`@prostojs/router`](https://github.com/prostojs/router). Supports:
 
-## Logging
+- Static routes: `/api/users`
+- Parametric routes: `/users/:id`
+- Wildcards: `/static/*`
+- Multiple wildcards: `/static/*/assets/*`
+- Regex constraints: `/api/time/:hours(\\d{2})h:minutes(\\d{2})m`
+- Regex wildcards: `/static/*(\\d+)`
 
-Get a scoped logger from the app:
+Route params accessed via `useRouteParams()`:
 
 ```ts
-const app = createHttpApp()
-const logger = app.getLogger('[my-app]')
-logger.log('App started')
-```
-
-Inside a handler, use the event-scoped logger:
-
-```ts
-import { useEventLogger } from '@wooksjs/event-core'
-
-app.get('/process', () => {
-  const logger = useEventLogger('my-handler')
-  logger.log('Processing request')  // tagged with event ID
-  return 'ok'
+app.get('/users/:id', () => {
+  const { params } = useRouteParams<{ id: string }>()
+  return { userId: params.id }
 })
 ```
 
-## Testing
+## Auto-status
 
-`@wooksjs/event-http` exports a test utility for running composables outside a real server:
+When no explicit status is set, it's inferred from the HTTP method and response body:
 
-```ts
-import { prepareTestHttpContext } from '@wooksjs/event-http'
+| Method | With body    | Without body   |
+| ------ | ------------ | -------------- |
+| GET    | 200 OK       | 204 No Content |
+| POST   | 201 Created  | 204 No Content |
+| PUT    | 201 Created  | 204 No Content |
+| PATCH  | 202 Accepted | 204 No Content |
+| DELETE | 202 Accepted | 204 No Content |
 
-const runInContext = prepareTestHttpContext({
-  url: '/users/42',
-  method: 'GET',
-  headers: { authorization: 'Bearer test-token' },
-  params: { id: '42' },
-})
+## Handler chain
 
-runInContext(() => {
-  const { get } = useRouteParams()
-  console.log(get('id'))  // '42'
-
-  const { isBearer } = useAuthorization()
-  console.log(isBearer())  // true
-})
-```
-
-### `prepareTestHttpContext(options)`
+Multiple handlers can be registered for the same route. If one throws, the next is tried:
 
 ```ts
-interface TTestHttpContext {
-  url: string
-  method?: string              // default: 'GET'
-  headers?: Record<string, string>
-  params?: Record<string, string | string[]>
-  requestLimits?: TRequestLimits  // app-level body limits for testing
-  cachedContext?: {
-    cookies?: Record<string, string | null>
-    authorization?: TAuthCache
-    body?: unknown             // pre-parsed body
-    rawBody?: string | Buffer | Promise<Buffer>
-    raw?: Partial<THttpContextStore>  // raw store sections
-  }
-}
+app.get('/resource', authHandler, mainHandler)
 ```
 
+If all handlers throw, the last error is sent as the response.
+
 ## Best Practices
 
-- **Use `createHttpApp()` factory** — Don't instantiate `WooksHttp` directly unless you need to extend the class.
-- **Use `getServerCb()` for custom servers** — This gives you full control over HTTPS, HTTP/2, or any custom server setup.
-- **One composable per concern** — Split auth, validation, user-fetching into separate composables. Compose them in handlers.
-- **Use `prepareTestHttpContext()` for unit testing composables** — Test composable logic without starting a server.
+- Return values directly — the framework handles serialization and status codes
+- Use `HttpError` for error responses: `throw new HttpError(404)` or `throw new HttpError(400, 'Invalid input')`
+- Use `useResponse()` only when you need explicit control over headers, cookies, or status
+- For `getServerCb()`, call `attachServer(server)` if you want `close()` to work
 
 ## Gotchas
 
-- Composables must be called within a request handler (inside the async context). Calling them at module load time throws.
-- `listen()` returns a promise — always `await` it or attach error handling.
-- The framework auto-detects content type from your return value (string -> text/plain, object -> application/json). Override with `useSetHeaders().setContentType()`.
+- Handlers receive no arguments — all data comes from composables
+- `listen()` returns a Promise — `await` it or handle rejection
+- `getServerCb()` doesn't automatically attach the server — call `attachServer()` if needed