Express.js Integration

1# Using bun
2bun add @vestig/express vestig
3 
4# Using npm
5npm install @vestig/express vestig
6 
7# Using pnpm
8pnpm add @vestig/express vestig

1import express from 'express'
2import {
3  vestigMiddleware,
4  withVestig,
5  vestigErrorHandler,
6} from '@vestig/express'
7 
8const app = express()
9 
10// Add vestig middleware (logs requests, sets up correlation context)
11app.use(vestigMiddleware)
12 
13// Use withVestig for typed logging in route handlers
14app.get('/api/users', withVestig(async (req, res, { log, ctx }) => {
15  log.info('Fetching users', { requestId: ctx.requestId })
16  res.json({ users: [] })
17}))
18 
19// Error handler (should be last)
20app.use(vestigErrorHandler)
21 
22app.listen(3000)

1import express from 'express'
2import { vestigMiddleware } from '@vestig/express'
3 
4const app = express()
5app.use(vestigMiddleware)

1import { createVestigMiddleware } from '@vestig/express'
2 
3app.use(createVestigMiddleware({
4  // Log level for middleware
5  level: 'info',
6 
7  // PII sanitization preset
8  sanitize: 'gdpr',
9 
10  // Paths to skip logging (health checks, metrics)
11  skipPaths: ['/health', '/metrics', '/favicon.ico'],
12 
13  // Custom request ID header
14  requestIdHeader: 'X-Request-ID',
15 
16  // Enable request/response timing
17  timing: true,
18 
19  // Log level for incoming requests
20  requestLogLevel: 'info',
21 
22  // Log level for outgoing responses
23  responseLogLevel: 'info',
24 
25  // Use structured JSON output
26  structured: true,
27}))

1import { withVestig } from '@vestig/express'
2 
3app.get('/api/users/:id', withVestig(async (req, res, { log, ctx, timing }) => {
4  // Typed logger with namespace
5  log.info('Fetching user', {
6    userId: req.params.id,
7    requestId: ctx.requestId
8  })
9 
10  // Mark checkpoints for performance tracking
11  timing.mark('db_query_start')
12 
13  const user = await db.users.findById(req.params.id)
14 
15  timing.mark('db_query_end')
16  log.debug('User fetched', {
17    elapsed: timing.elapsed(),
18    userId: user?.id
19  })
20 
21  if (!user) {
22    return res.status(404).json({ error: 'User not found' })
23  }
24 
25  res.json({ user })
26}))

1interface RouteHandlerContext {
2  // Logger instance (child of middleware logger)
3  log: Logger
4 
5  // Correlation context with request/trace IDs
6  ctx: {
7    requestId: string
8    traceId: string
9    spanId: string
10    timestamp: string
11    // ... other context
12  }
13 
14  // Request timing utilities
15  timing: {
16    start: number          // Start timestamp
17    elapsed: () => number  // Get elapsed time in ms
18    mark: (name: string) => void  // Mark a checkpoint
19    getMark: (name: string) => number | undefined
20  }
21}

1app.get('/api/users', withVestig(handler, {
2  // Custom namespace for this route
3  namespace: 'api:users',
4 
5  // Log level for this route
6  level: 'debug',
7 
8  // Log request on entry
9  logRequest: true,
10 
11  // Log response on completion
12  logResponse: true,
13}))

1import { createRouteHandler } from '@vestig/express'
2 
3// Create factory with defaults
4const apiHandler = createRouteHandler({
5  namespace: 'api',
6  logRequest: true,
7  logResponse: true,
8})
9 
10// Use factory for consistent configuration
11app.get('/api/users', apiHandler(async (req, res, { log }) => {
12  log.info('Fetching users')
13  res.json({ users: [] })
14}))
15 
16app.get('/api/orders', apiHandler(async (req, res, { log }) => {
17  log.info('Fetching orders')
18  res.json({ orders: [] })
19}))

1import { vestigErrorHandler } from '@vestig/express'
2 
3// Should be the last middleware
4app.use(vestigErrorHandler)

1{
2  "error": {
3    "message": "User not found"
4  },
5  "requestId": "req_abc123",
6  "traceId": "0af7651916cd43dd8448eb211c80319c"
7}

1import { createVestigErrorHandler } from '@vestig/express'
2 
3app.use(createVestigErrorHandler({
4  // Include stack traces (only in development)
5  includeStack: process.env.NODE_ENV !== 'production',
6 
7  // Log level for errors
8  level: 'error',
9 
10  // PII sanitization for error details
11  sanitize: 'default',
12 
13  // Include correlation IDs in error response
14  includeCorrelationInResponse: true,
15}))

1import { notFoundHandler, vestigErrorHandler } from '@vestig/express'
2 
3// 404 handler before error handler
4app.use(notFoundHandler)
5 
6// Error handler last
7app.use(vestigErrorHandler)

1import { createNotFoundHandler } from '@vestig/express'
2 
3app.use(createNotFoundHandler('Resource not found'))

1// Incoming request headers are parsed:
2// - X-Request-ID → requestId
3// - X-Correlation-ID → correlationId
4// - traceparent → W3C trace context
5 
6// Response headers are set:
7// - X-Request-ID
8// - X-Correlation-ID
9// - traceparent

1app.get('/api/orders', withVestig(async (req, res, { ctx }) => {
2  console.log(ctx.requestId)   // 'req_abc123'
3  console.log(ctx.traceId)     // '0af7651916cd43dd8448eb211c80319c'
4  console.log(ctx.spanId)      // 'b7ad6b7169203331'
5  console.log(ctx.timestamp)   // '2025-01-01T12:00:00.000Z'
6}))

1import { createTraceparent } from 'vestig'
2 
3app.get('/api/orders', withVestig(async (req, res, { ctx }) => {
4  // Forward correlation context to downstream services
5  const response = await fetch('https://inventory-service.local/api/check', {
6    headers: {
7      'X-Request-ID': ctx.requestId,
8      'X-Correlation-ID': ctx.correlationId ?? ctx.requestId,
9      'traceparent': createTraceparent(ctx.traceId, ctx.spanId),
10    },
11  })
12}))

1app.get('/api/complex', withVestig(async (req, res, { log, timing }) => {
2  log.info('Starting complex operation')
3 
4  // Mark checkpoint before database query
5  timing.mark('db_start')
6  const data = await db.query('SELECT * FROM items')
7  timing.mark('db_end')
8 
9  // Calculate DB query time
10  const dbStart = timing.getMark('db_start')
11  const dbEnd = timing.getMark('db_end')
12  const dbTime = dbEnd && dbStart ? dbEnd - dbStart : 0
13 
14  // Mark checkpoint before external API
15  timing.mark('api_start')
16  const enriched = await externalApi.enrich(data)
17  timing.mark('api_end')
18 
19  log.info('Operation complete', {
20    totalElapsed: timing.elapsed(),
21    dbQueryMs: dbTime,
22    items: data.length,
23  })
24 
25  res.json({ items: enriched })
26}))

1import express from 'express'
2import {
3  createVestigMiddleware,
4  withVestig,
5  createRouteHandler,
6  createVestigErrorHandler,
7  createNotFoundHandler,
8} from '@vestig/express'
9import { createLogger } from 'vestig'
10 
11const app = express()
12 
13// Parse JSON bodies
14app.use(express.json())
15 
16// Vestig middleware with custom config
17app.use(createVestigMiddleware({
18  level: 'info',
19  sanitize: 'gdpr',
20  skipPaths: ['/health', '/ready'],
21  structured: process.env.NODE_ENV === 'production',
22}))
23 
24// Create route handler factory for API routes
25const apiHandler = createRouteHandler({
26  namespace: 'api',
27  logRequest: true,
28})
29 
30// Health check (skipped by middleware)
31app.get('/health', (req, res) => {
32  res.json({ status: 'ok' })
33})
34 
35// API routes with logging
36app.get('/api/users', apiHandler(async (req, res, { log, ctx }) => {
37  log.info('Fetching users list')
38 
39  const users = await db.users.findMany({
40    limit: parseInt(req.query.limit as string) || 10,
41  })
42 
43  log.debug('Users retrieved', { count: users.length })
44  res.json({ users })
45}))
46 
47app.post('/api/users', apiHandler(async (req, res, { log, ctx }) => {
48  log.info('Creating new user', { email: req.body.email })
49 
50  const user = await db.users.create(req.body)
51 
52  log.info('User created', { userId: user.id })
53  res.status(201).json({ user })
54}))
55 
56app.get('/api/users/:id', apiHandler(async (req, res, { log }) => {
57  const { id } = req.params
58 
59  log.info('Fetching user', { userId: id })
60  const user = await db.users.findById(id)
61 
62  if (!user) {
63    const error = new Error('User not found') as Error & { statusCode: number }
64    error.statusCode = 404
65    throw error
66  }
67 
68  res.json({ user })
69}))
70 
71// 404 handler
72app.use(createNotFoundHandler('Resource not found'))
73 
74// Error handler with correlation IDs
75app.use(createVestigErrorHandler({
76  includeStack: process.env.NODE_ENV !== 'production',
77  includeCorrelationInResponse: true,
78}))
79 
80// Start server
81const PORT = process.env.PORT || 3000
82app.listen(PORT, () => {
83  const log = createLogger({ namespace: 'server' })
84  log.info('Server started', { port: PORT })
85})

1import type {
2  MiddlewareOptions,
3  RouteHandlerContext,
4  RouteHandlerOptions,
5  VestigRouteHandler,
6  ErrorHandlerOptions,
7  VestigRequest,
8  RequestTiming,
9} from '@vestig/express'