server-timing-parse

Zero-dependency parser and serializer for HTTP Server-Timing response headers.

Parse Server-Timing: db;desc="Database Query";dur=53, app;dur=47.2 into structured data — no external dependencies.

Quick Start

npm install server-timing-parse

import { parseServerTiming, serializeServerTiming } from 'server-timing-parse';

// Parse
const metrics = parseServerTiming('db;desc="Database Query";dur=53');
// → [ServerTimingMetric { name: 'db', description: 'Database Query', duration: 53 }]

// Multi-metric
const multi = parseServerTiming('db;dur=53, app;dur=47.2');
// → [ServerTimingMetric { name: 'db', duration: 53 }, ServerTimingMetric { name: 'app', duration: 47.2 }]

// Serialize
const header = serializeServerTiming([
  { name: 'db', description: 'Database Query', duration: 53 },
  { name: 'app', duration: 47.2 },
]);
// → 'db;desc="Database Query";dur=53, app;dur=47.2'

Why server-timing-parse?

HTTP Server-Timing headers expose performance metrics (database query time, cache latency, application processing time) to developer tools and clients. The W3C Server-Timing spec defines a structured format — but no zero-dependency npm package existed to parse it.

Existing options:

• server-timing npm package — creates/serializes headers but cannot parse incoming header values. Also pulls in 2 runtime dependencies.
• No Python equivalent — this library fills the gap for the Node.js ecosystem.

Key Features

• Zero runtime dependencies — no package.json dependencies array
• TypeScript definitions included — index.d.ts ships with the package
• Frozen objects — parsed metrics are deeply immutable
• Handles real-world edge cases — escaped quotes in descriptions, semicolons inside quoted strings, unknown params (ignored for forward-compatibility), large decimal durations
• Both parser and serializer — full round-trip support

API Reference

parseServerTiming(header: string): readonly ServerTimingMetric[]

Parses a Server-Timing header value into an array of frozen metric objects.

parseServerTiming('db;desc="DB";dur=53, app;dur=47.2')
// → [
//     ServerTimingMetric { name: 'db', description: 'DB', duration: 53 },
//     ServerTimingMetric { name: 'app', description: null, duration: 47.2 }
//   ]

Errors: Throws InvalidServerTimingHeader for malformed input (non-string input, unclosed quotes, invalid duration format, negative durations, empty metric name).

serializeServerTiming(metrics: ServerTimingMetric[]): string

Serializes an array of metric objects into a Server-Timing header string. Canonical output order: name;desc="...";dur=...

serializeServerTiming([{ name: 'db', description: 'DB', duration: 53 }])
// → 'db;desc="DB";dur=53'

Errors: Throws InvalidServerTimingHeader for invalid input (non-array, missing name, non-string name).

ServerTimingMetric

interface ServerTimingMetric {
  readonly name: string;
  readonly description: string | null;
  readonly duration: number | null;
}

InvalidServerTimingHeader

Error class thrown for malformed header input.

Limitations

• Whitespace inside quoted descriptions is preserved (e.g., desc=" spaces " → description " spaces ")
• Duration must be non-negative; negative durations raise InvalidServerTimingHeader
• Empty metric names raise InvalidServerTimingHeader
• Semicolons inside quoted descriptions are handled correctly (desc="a;b;c" → description a;b;c)

Non-goals

• Enforcing Server-Timing policy or middleware that automatically injects metrics
• Network I/O, HTTP server/client functionality
• Integration with specific APM vendors (Datadog, New Relic, etc.)
• Async or streaming metric collection
• Parsing the W3C PerformanceServerTiming interface (browser-side API)

License

MIT