Wide Events for Next.js

1bun add vestig @vestig/next

1// middleware.ts
2import { createWideEventMiddleware } from '@vestig/next/wide-events'
3 
4export const middleware = createWideEventMiddleware({
5  // Skip static assets and internal routes
6  skipPaths: ['/_next', '/favicon.ico', '/api/health'],
7 
8  // Tail sampling configuration
9  tailSampling: {
10    enabled: true,
11    alwaysKeepStatuses: ['error'],
12    slowThresholdMs: 2000,
13    successSampleRate: 0.1, // 10% of successful requests
14  },
15})
16 
17export const config = {
18  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
19}

1// middleware.ts
2export { wideEventMiddleware as middleware } from '@vestig/next/wide-events'
3 
4export const config = {
5  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
6}

1// app/api/checkout/route.ts
2import { NextResponse } from 'next/server'
3import { getWideEvent, setWideEventUser } from '@vestig/next/wide-events'
4 
5export async function POST(req: Request) {
6  const event = getWideEvent()
7 
8  // Add user context
9  const user = await authenticate(req)
10  setWideEventUser({
11    id: user.id,
12    subscription: user.plan,
13  })
14 
15  // Add business context
16  event?.merge('order', {
17    items: order.items.length,
18    total: order.total,
19  })
20 
21  // Process checkout...
22 
23  return NextResponse.json({ orderId: order.id })
24}

1import { getWideEvent } from '@vestig/next/wide-events'
2 
3const event = getWideEvent()
4if (event) {
5  event.set('custom', 'field', 'value')
6}

1import { requireWideEvent } from '@vestig/next/wide-events'
2 
3// Throws if not in a wide event context
4const event = requireWideEvent()
5event.set('order', 'id', orderId)

1import { setWideEventUser } from '@vestig/next/wide-events'
2 
3setWideEventUser({
4  id: user.id,
5  email: user.email,
6  subscription: user.plan,  // Used for VIP tier sampling
7  role: user.role,
8})

1import { setWideEventPerformance } from '@vestig/next/wide-events'
2 
3const start = performance.now()
4const users = await db.users.findMany()
5 
6setWideEventPerformance({
7  db_query_ms: performance.now() - start,
8  db_rows: users.length,
9})

1import { setWideEventField, mergeWideEventFields } from '@vestig/next/wide-events'
2 
3// Single field
4setWideEventField('order', 'id', orderId)
5 
6// Multiple fields
7mergeWideEventFields('payment', {
8  method: 'stripe',
9  amount: 9999,
10  currency: 'usd',
11})

1import { setWideEventFeatureFlags } from '@vestig/next/wide-events'
2 
3setWideEventFeatureFlags({
4  new_checkout: true,
5  beta_features: false,
6  experiment_id: 'exp-123',
7})

1// Using the standalone helper (works anywhere in request context)
2import { setWideEventError } from '@vestig/next/wide-events'
3 
4try {
5  await processPayment(order)
6} catch (error) {
7  setWideEventError(error, { orderId: order.id })
8  throw error
9}
10 
11// Or using the event builder method directly (more symmetric API)
12const event = getWideEvent()
13try {
14  await processPayment(order)
15} catch (error) {
16  event?.setError(error, { orderId: order.id })
17  throw error
18}

1import { timeWideEventOperation } from '@vestig/next/wide-events'
2 
3const endDbQuery = timeWideEventOperation('db_users_query')
4const users = await db.users.findMany()
5endDbQuery()  // Adds performance.db_users_query_ms field

1import { getWideEventElapsed } from '@vestig/next/wide-events'
2 
3const elapsed = getWideEventElapsed()
4console.log(`Request running for ${elapsed}ms`)

1// ❌ This will NOT work - no context available
2'use server'
3export async function updateStatus(userId: string) {
4  const event = requireWideEvent() // Throws: "called outside of a wide event context"
5}
6 
7// ✅ This WILL work - withWideEvent creates/inherits context
8'use server'
9import { withWideEvent } from '@vestig/next/wide-events'
10 
11export const updateStatus = withWideEvent(
12  async (userId: string, { event }) => {
13    event.set('user', 'id', userId)
14    // ...
15  },
16  { name: 'action.updateStatus' }
17)

1// app/actions/user.ts
2'use server'
3 
4import { withWideEvent } from '@vestig/next/wide-events'
5 
6export const createUser = withWideEvent(
7  async (data: CreateUserInput, { event }) => {
8    event.set('action', 'type', 'user.create')
9    event.set('user', 'email', data.email)
10 
11    const user = await db.users.create({ data })
12 
13    event.set('user', 'id', user.id)
14    return user
15  },
16  { name: 'action.user.create' }
17)

1// app/actions/index.ts
2import { createWideEventAction } from '@vestig/next/wide-events'
3 
4const action = createWideEventAction({
5  tailSampling: {
6    enabled: true,
7    successSampleRate: 0.1,
8  },
9})
10 
11export const createUser = action(
12  async (data, { event }) => {
13    event.set('user', 'email', data.email)
14    return await db.users.create({ data })
15  },
16  { name: 'action.user.create' }
17)
18 
19export const updateUser = action(
20  async ({ id, data }, { event }) => {
21    event.set('user', 'id', id)
22    return await db.users.update({ where: { id }, data })
23  },
24  { name: 'action.user.update' }
25)

1// Middleware creates wide event for request
2// ↓
3// Route handler processes request
4// ↓
5// Server action enriches the same wide event
6// ↓
7// One comprehensive event emitted at the end

1// middleware.ts
2import { createWideEventMiddleware } from '@vestig/next/wide-events'
3 
4export const middleware = createWideEventMiddleware({
5  tailSampling: {
6    enabled: true,
7    alwaysKeepStatuses: ['error'],
8    slowThresholdMs: 2000,
9    successSampleRate: 0.1,
10    vipTiers: ['premium', 'enterprise'],
11  },
12})
13 
14export const config = {
15  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
16}

1// app/api/checkout/route.ts
2import { NextResponse } from 'next/server'
3import {
4  setWideEventUser,
5  mergeWideEventFields,
6  timeWideEventOperation,
7  setWideEventError,
8} from '@vestig/next/wide-events'
9 
10export async function POST(req: Request) {
11  try {
12    // Auth and user context
13    const user = await authenticate(req)
14    setWideEventUser({
15      id: user.id,
16      subscription: user.plan,
17    })
18 
19    // Load cart with timing
20    const endCartLoad = timeWideEventOperation('db_cart')
21    const cart = await db.carts.get(user.id)
22    endCartLoad()
23 
24    mergeWideEventFields('cart', {
25      items: cart.items.length,
26      total: cart.total,
27    })
28 
29    // Process payment with timing
30    const endPayment = timeWideEventOperation('stripe_api')
31    const payment = await stripe.charge(cart)
32    endPayment()
33 
34    mergeWideEventFields('payment', {
35      provider: 'stripe',
36      status: payment.status,
37      amount: payment.amount,
38    })
39 
40    // Create order
41    const order = await db.orders.create({ user, cart, payment })
42    mergeWideEventFields('order', {
43      id: order.id,
44      items: order.items.length,
45    })
46 
47    return NextResponse.json({ orderId: order.id }, { status: 201 })
48 
49  } catch (error) {
50    setWideEventError(error)
51    return NextResponse.json(
52      { error: 'Checkout failed' },
53      { status: 500 }
54    )
55  }
56}

1{
2  "event_type": "http.request",
3  "status": "success",
4  "duration_ms": 850,
5  "http.method": "POST",
6  "http.path": "/api/checkout",
7  "user.id": "user-123",
8  "user.subscription": "premium",
9  "cart.items": 3,
10  "cart.total": 9999,
11  "payment.provider": "stripe",
12  "payment.status": "succeeded",
13  "order.id": "order-456",
14  "performance.db_cart_ms": 45,
15  "performance.stripe_api_ms": 230
16}

1interface WideEventMiddlewareOptions {
2  /** Log level (default: 'info') */
3  level?: LogLevel
4 
5  /** Enable/disable (default: true) */
6  enabled?: boolean
7 
8  /** PII sanitization preset (default: 'default') */
9  sanitize?: SanitizePreset
10 
11  /** Paths to skip (prefix matching) */
12  skipPaths?: string[]
13 
14  /** Custom request ID header (default: 'x-request-id') */
15  requestIdHeader?: string
16 
17  /** Use structured JSON output (default: true) */
18  structured?: boolean
19 
20  /** Tail sampling configuration */
21  tailSampling?: TailSamplingConfig
22}