Molecule.dev

@molecule/api-middleware-analytics

Middleware · analytics · API (Node) · v1.0.2 · Apache-2.0

API request metrics middleware via getAnalytics()

npm install @molecule/api-middleware-analytics

npm · Source on GitHub

How it works

@molecule/api-middleware-analytics is analytics middleware for the API, mounted once at startup.

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

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

Works with: @molecule/api-bond

Reference

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.

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.

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.