prefer

Parses the Prefer request header per RFC 7240. Works in concert with send()’s prefer: true option to automatically handle return=minimal (200 → 204) and return=representation behaviors.

The parser enforces the RFC 9110 §5.6.2 token and §5.6.4 quoted-string grammars. Malformed preferences (invalid characters, unterminated quotes, bare control characters) are silently skipped — valid preferences in the same header are still parsed.

Pipeline stage: Negotiation

Import

import {prefer} from '@centralping/ergo';

Options

None. The prefer() factory takes no parameters.

Return Value

Returns parsed preferences stored on the domain accumulator at acc.prefer:

{
  return: 'minimal',
  // other preferences as key-value pairs
}

When send() has prefer: true enabled and the client sends Prefer: return=minimal, success responses are automatically converted: 200 → 204 with the body stripped and a Preference-Applied: return=minimal header added.

Error Responses

None.

Usage

Standalone

import http from 'node:http';
import {compose, prefer, handler} from '@centralping/ergo';

const pipeline = compose(
  prefer(),
  (req, res, acc) => ({
    response: {body: {id: 1, name: 'item'}},
  }),
);

// With send's prefer option enabled
const server = http.createServer(
  handler(pipeline, {prefer: true}),
);
// Client: Prefer: return=minimal
// Response: 204 No Content + Preference-Applied: return=minimal

ergo-router

const router = createRouter({
  defaults: {
    send: {prefer: true},
  },
});

router.get('/items/:id', {
  execute: (req, res, acc) => ({
    response: {body: {id: 1, name: 'item'}},
  }),
});

RFC References

• RFC 7240 — Prefer Header for HTTP

API Reference

See the auto-generated prefer API docs.