@hyperttp/parser

English | Русский

Automated response parsing and content conversion plugin for Hyperttp.

Features

• Detects JSON, HTML, XML, text, and binary responses automatically.
• Supports explicit auto, json, text, html, xml, buffer, and stream response types.
• Explicit response types take precedence over Content-Type.
• Supports protocol-neutral callbacks for data extraction and response-type detection.
• Passes through values that have already been converted.
• Returns a new UniversalResponse when data changes instead of mutating the input.

Installation

npm install @hyperttp/parser
# or
bun add @hyperttp/parser

Usage

The hyperttp package registers the parser automatically:

import { HyperClient } from "hyperttp";

const client = new HyperClient({
  responseConverter: {
    parseHTML: true,
    htmlMode: "full",
  },
});

const user = await client.get<{ id: number }>(
  "https://api.example.com/users/1",
  "json",
);

Disable the built-in parser with responseConverter: false:

const client = new HyperClient({
  responseConverter: false,
});

When using @hyperttp/core directly, register the plugin explicitly:

import { HyperCore } from "@hyperttp/core";
import { withParser } from "@hyperttp/parser";

const core = new HyperCore();
core.use(withParser({ htmlMode: "full" }));

Importing @hyperttp/parser alone does not register the plugin.

Response types

| Type | Result | | --- | --- | | auto | Detect from Content-Type or URL extension | | json | Parsed JavaScript value | | text | String | | html | Parsed HTML or the original string when parseHTML: false | | xml | Parsed by fast-xml-parser | | buffer | Buffer in Node.js or Uint8Array in Bun | | stream | Passed through without conversion |

Configuration

withParser(options?) supports charset, parseHTML, htmlMode, xmlParserOptions, shouldParse, getData/bodyExtractor, getResponseType/detectResponseType, and isEmptyResponse. Callbacks can be synchronous or asynchronous and receive the response, request, and request context.

For REST, HEAD responses are skipped by default, and statuses 204, 205, and 304 are returned with data: null. Other protocols can define their own behavior through callbacks.

maxBodySize and parseErrors are reserved options in v2.0.0 and are not currently applied during conversion.

License

MIT © dirold2