Create evlog Framework Integration

Add a new framework integration to evlog. Every integration follows the same architecture built on the shared createMiddlewareLogger utility. This skill walks through all touchpoints. Every single touchpoint is mandatory -- do not skip any.

PR Title

Recommended format for the pull request title:

feat({framework}): add {Framework} middleware integration

Touchpoints Checklist

Important: Do NOT consider the task complete until all 16 touchpoints have been addressed.

Naming Conventions

Use these placeholders consistently:

Shared Utilities

All integrations share the same core utilities. Never reimplement logic that exists in shared/. These are also publicly available as evlog/toolkit for community-built integrations (see Custom Integration docs).

Test Helpers

Step 1: Integration Source

Create packages/evlog/src/{framework}/index.ts.

The integration file should be minimal — typically 50-80 lines of framework-specific glue. All pipeline logic (enrich, drain, keep, header filtering) is handled by createMiddlewareLogger.

Template Structure

import type { RequestLogger } from '../types'
import { createMiddlewareLogger, type BaseEvlogOptions } from '../shared/middleware'
import { extractSafeHeaders } from '../shared/headers'       // for Web API Headers (Hono, Elysia)
// OR
import { extractSafeNodeHeaders } from '../shared/headers'    // for Node.js headers (Express, Fastify)
import { createLoggerStorage } from '../shared/storage'

const { storage, useLogger } = createLoggerStorage(
  'middleware context. Make sure the evlog middleware is registered before your routes.',
)

export interface Evlog{Framework}Options extends BaseEvlogOptions {}

export { useLogger }

// Type augmentation for typed logger access (framework-specific)
// For Express: declare module 'express-serve-static-core' { interface Request { log: RequestLogger } }
// For Hono: export type EvlogVariables = { Variables: { log: RequestLogger } }

export function evlog(options: Evlog{Framework}Options = {}): FrameworkMiddleware {
  return async (frameworkContext, next) => {
    const { logger, finish, skipped } = createMiddlewareLogger({
      method: /* extract from framework context */,
      path: /* extract from framework context */,
      requestId: /* extract x-request-id or crypto.randomUUID() */,
      headers: extractSafeHeaders(/* framework request Headers object */),
      ...options,
    })

    if (skipped) {
      await next()
      return
    }

    // Store logger in framework-specific context
    // e.g., c.set('log', logger) for Hono
    // e.g., req.log = logger for Express

    // Wrap next() in AsyncLocalStorage.run() for useLogger() support
    // Express: storage.run(logger, () => next())
    // Hono: await storage.run(logger, () => next())
  }
}

Reference Implementations

• Hono (~40 lines): packages/evlog/src/hono/index.ts — Web API Headers, c.set('log', logger), wraps next() in try/catch
• Express (~80 lines): packages/evlog/src/express/index.ts — Node.js headers, req.log, res.on('finish'), AsyncLocalStorage for useLogger()
• Elysia (~70 lines): packages/evlog/src/elysia/index.ts — Web API Headers, derive() plugin, onAfterHandle/onError, AsyncLocalStorage for useLogger()

Key Architecture Rules

1. Use createMiddlewareLogger — never call createRequestLogger directly
2. Use the right header extractor — extractSafeHeaders for Web API Headers, extractSafeNodeHeaders for Node.js IncomingHttpHeaders
3. Spread user options into createMiddlewareLogger — drain, enrich, keep are handled automatically by finish()
4. Store logger in the framework's idiomatic context (e.g., c.set() for Hono, req.log for Express, .derive() for Elysia)
5. Export useLogger() — backed by AsyncLocalStorage so the logger is accessible from anywhere in the call stack
6. Call finish() in both success and error paths — it handles emit + enrich + drain
7. Re-throw errors after finish() so framework error handlers still work
8. Export options interface with drain/enrich/keep for feature parity across all frameworks
9. Export type helpers for typed context access (e.g., EvlogVariables for Hono)
10. Framework SDK is a peer dependency — never bundle it
11. Never duplicate pipeline logic — callEnrichAndDrain is internal to createMiddlewareLogger

Framework-Specific Patterns

Hono: Use MiddlewareHandler return type, c.set('log', logger), c.res.status for status, c.req.raw.headers for headers.

Express: Standard (req, res, next) middleware, res.on('finish') for response end, storage.run(logger, () => next()) for useLogger(). Type augmentation targets express-serve-static-core (NOT express). Error handler uses ErrorRequestHandler type.

Elysia: Return new Elysia({ name: 'evlog' }) plugin, use .derive({ as: 'global' }) to create logger and attach log to context, onAfterHandle for success path, onError for error path. Use storage.enterWith(logger) in derive for useLogger() support. Note: onAfterResponse is fire-and-forget and may not complete before app.handle() returns in tests — use onAfterHandle instead.

Fastify: Use fastify-plugin wrapper, fastify.decorateRequest('log', null), onRequest/onResponse hooks.

NestJS: NestInterceptor with intercept(), tap()/catchError() on observable, forRoot() dynamic module.

Step 2: Build Config

Add a build entry in packages/evlog/tsdown.config.ts:

'{framework}/index': 'src/{framework}/index.ts',

Place it after the existing framework entries (workers, next, hono, express).

Also add the framework SDK to the external array:

external: [
  // ... existing externals
  '{framework-package}',  // e.g., 'elysia', 'fastify', 'express'
],

Step 3: Package Exports

In packages/evlog/package.json, add four entries:

In exports (after the last framework entry):

"./{framework}": {
  "types": "./dist/{framework}/index.d.mts",
  "import": "./dist/{framework}/index.mjs"
}

In typesVersions["*"]:

"{framework}": [
  "./dist/{framework}/index.d.mts"
]

In peerDependencies (with version range):

"{framework-package}": "^{latest-major}.0.0"

In peerDependenciesMeta (mark as optional):

"{framework-package}": {
  "optional": true
}

In keywords — add the framework name to the keywords array.

Step 4: Tests

Create packages/evlog/test/{framework}.test.ts.

Import shared test helpers from ./helpers/framework:

import {
  assertDrainCalledWith,
  assertEnrichBeforeDrain,
  assertSensitiveHeadersFiltered,
  createPipelineSpies,
} from './helpers/framework'

Required test categories:

1. Middleware creates logger — verify c.get('log') or req.log returns a RequestLogger
2. Auto-emit on response — verify event includes status, method, path, duration
3. Error handling — verify errors are captured and event has error level + error details
4. Route filtering — verify skipped routes don't create a logger
5. Request ID forwarding — verify x-request-id header is used when present
6. Context accumulation — verify logger.set() data appears in emitted event
7. Drain callback — use assertDrainCalledWith() helper
8. Enrich callback — use assertEnrichBeforeDrain() helper
9. Keep callback — verify tail sampling callback receives context and can force-keep logs
10. Sensitive header filtering — use assertSensitiveHeadersFiltered() helper
11. Drain/enrich error resilience — verify errors in drain/enrich do not break the request
12. Skipped routes skip drain/enrich — verify drain/enrich are not called for excluded routes
13. useLogger() returns same logger — verify useLogger() === req.log (or framework equivalent)
14. useLogger() throws outside c