@molecule/api-middleware-analytics

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

API request-metrics middleware for molecule.dev.

Tracks every request as an api.request analytics event — method, path, status code, and duration — via the bonded analytics provider (getAnalytics() from @molecule/api-bond), emitting on the response finish event.

Quick Start

import express from 'express'
import { createAnalyticsMiddleware } from '@molecule/api-middleware-analytics'

const app = express()
app.use(createAnalyticsMiddleware({ excludePaths: ['/health', '/metrics'] }))

Type

middleware

Installation

npm install @molecule/api-middleware-analytics @molecule/api-bond

API

Interfaces

AnalyticsMiddlewareOptions

Options for the analytics middleware.

interface AnalyticsMiddlewareOptions {
  /**
   * Paths to exclude from tracking.
   * @default ['/health']
   */
  excludePaths?: string[]
}

Functions

createAnalyticsMiddleware(options)

Creates an analytics middleware that tracks every API request.

function createAnalyticsMiddleware(
  options?: AnalyticsMiddlewareOptions,
): (req: unknown, res: unknown, next: (err?: unknown) => void) => void

• options — Configuration options including paths to exclude from tracking.

Returns: Express-compatible middleware that tracks requests on the finish event.

Injection Notes

Requirements

Peer dependencies:

• @molecule/api-bond ^1.0.1

Runtime Dependencies

• @molecule/api-bond

• An analytics provider must be bonded (bond('analytics', provider) — e.g. @molecule/api-analytics-posthog or -mixpanel) for events to go anywhere. Without one the middleware still runs but every track call is a silent no-op — requests flow, metrics never appear. Wiring later is fine: the provider is resolved lazily on each event.

• excludePaths entries are EXACT matches against req.path (falling back to req.url) — no prefixes or globs ('/health' does not exclude /health/live).

• Tracking is fire-and-forget; a failing analytics backend never blocks or fails the request.