Skip to content
ergo

ergo-wire

npm version

Node.js ≥ 22Pure ESMZero Dependencies

Installation

Section titled “Installation”
Terminal window
npm install @centralping/ergo-wire

Overview

Section titled “Overview”

@centralping/ergo-wire is the canonical HTTP wire contract for the Ergo stack. It provides shared parse/format primitives so the server (@centralping/ergo) and client (@centralping/ergo-fetch) stay aligned without duplicating RFC grammars.

Wire Profile concerns (idempotency, Link, pagination, Retry-After) expose matching parse and format/serialize helpers. Shared scanners such as parseQuotedString are primitives without a dedicated format pair (sanitizeQuotedString is the related sanitize helper). serializeOffsetParams / serializeCursorParams and Link entries from parseLinkHeader use Object.create(null) + Object.freeze(); pagination parsers return plain mutable objects, and parseLinkHeader returns a mutable Map.

Wire Profile v1

Section titled “Wire Profile v1”
Concern Wire format Key exports
Idempotency-Key RFC 8941 quoted sf-string formatIdempotencyKey, parseIdempotencyKey, assertSfStringInner
Link RFC 8288 formatLinkHeader, parseLinkHeader, paginationLinks, cursorPaginationLinks
Offset pagination page, per_page query keys serializeOffsetParams, parseOffsetParams
Cursor pagination cursor, limit query keys serializeCursorParams, parseCursorParams
Retry-After seconds or IMF-fixdate parseRetryAfter, formatRetryAfter
Body fingerprint SHA-256 hex (Web Crypto) fingerprint

Ergonomic client options may use perPage; serialization always emits per_page on the wire.

Design Principles

Section titled “Design Principles”
  • Zero runtime dependencies — Web Platform APIs only (crypto.subtle)
  • Symmetric primitives — Wire Profile concerns pair parse with format/serialize; shared scanners like parseQuotedString are primitives without a dedicated format helper
  • Graceful parse degradation — malformed wire input does not throw: header parsers such as parseIdempotencyKey / parseRetryAfter return undefined, parseLinkHeader returns an empty Map for malformed Link values (it still throws TypeError when an optional requestUrl is provided and invalid), and pagination parsers fall back to defaults; format/serialize helpers throw TypeError on invalid values
  • Character-by-character parsing for RFC grammars (no regex for Link parsing)
  • Null-prototype policy — serializeOffsetParams / serializeCursorParams and frozen Link entries from parseLinkHeader use Object.create(null) + Object.freeze()

Usage

Section titled “Usage”
import {
  formatIdempotencyKey,
  parseIdempotencyKey,
  serializeOffsetParams,
  serializeCursorParams,
  parseLinkHeader,
  formatLinkHeader,
  parseRetryAfter
} from '@centralping/ergo-wire';


formatIdempotencyKey('my-key'); // '"my-key"'
serializeOffsetParams({page: 2, perPage: 25}); // {page:2, per_page:25}
serializeCursorParams({limit: 10, cursor: 'tok'}); // {limit:10, cursor:'tok'}

Individual modules are also available via subpath imports (no .js suffix needed):

import {sanitizeQuotedString} from '@centralping/ergo-wire/lib/quoted-string';

Exports

Section titled “Exports”

Every root export from @centralping/ergo-wire:

Module Exports
Idempotency assertSfStringInner, formatIdempotencyKey, parseIdempotencyKey
Fingerprint fingerprint
Link formatLinkHeader, paginationLinks, cursorPaginationLinks, parseLinkHeader
Pagination DEFAULT_PAGE, DEFAULT_PER_PAGE, MAX_PER_PAGE, DEFAULT_CURSOR_LIMIT, MAX_CURSOR_LIMIT, OFFSET_PAGINATION_KEYS, CURSOR_PAGINATION_KEYS, JSON_API_PAGE_STRATEGY_GROUPS, parseOffsetParams, serializeOffsetParams, parseCursorParams, serializeCursorParams
Retry-After parseRetryAfter, formatRetryAfter
Quoted-string TOKEN_CHARS, skipOWS, scanToken, sanitizeQuotedString, parseQuotedString

Subpath imports under @centralping/ergo-wire/lib/* expose the same modules individually (for example @centralping/ergo-wire/lib/quoted-string).

Consumers

Section titled “Consumers”
Package Relationship
@centralping/ergo Re-exports wire primitives from lib/ (non-breaking shims)
@centralping/ergo-router Inherits wire behavior through ergo middleware
@centralping/ergo-fetch Runtime dependency for client-side parse/format (including JSON_API_PAGE_STRATEGY_GROUPS)
Section titled “Related”
Section titled “Links”