@caido-utils/parser

A lightweight HTTP request/response parser for JavaScript and TypeScript. Parse, modify, and rebuild HTTP messages with support for headers, cookies, query parameters, and body content (JSON, URL-encoded, multipart).

Features

• Parse HTTP requests and responses from raw strings
• Modify headers, cookies, query parameters, and body parameters
• Support for JSON, URL-encoded, and multipart body types
• Automatic body type detection
• Rebuild modified messages back to raw format
• Apply mutations via a simple API

Installation

npm install @caido-utils/parser

Quick Start

import { Parser } from "@caido-utils/parser";

const rawRequest = `GET /api/users?id=123 HTTP/1.1
Host: example.com
Cookie: session=xyz
Content-Type: application/json

{"name": "test"}`;

const parser = new Parser(rawRequest);

// Read values
console.log(parser.method); // "GET"
console.log(parser.version); // "HTTP/1.1"
console.log(parser.query.get("id")); // "123"
console.log(parser.headers.get("Host")); // "example.com"

// Modify values
parser.method = "POST";
parser.query.set("id", "456");
parser.headers.set("X-Custom", "value");

// Rebuild the request
const modified = parser.build();

API Reference

Parser

The main class for parsing HTTP messages.

Constructor

new Parser(raw: string)

Creates a new parser instance from a raw HTTP request or response string.

Properties

| Property | Type | Description | | --------- | ------------------------- | -------------------------------------------------------- | | method | string | HTTP method (e.g., "GET", "POST") | | version | string | HTTP version (e.g., "HTTP/1.1") | | headers | HeadersParser | Header parser instance | | cookies | CookiesParser | Cookie parser instance | | query | QueryParser | Query string parser instance | | path | PathParser | URL path parser instance | | body | BodyParser \| undefined | Body parser instance (undefined if body type is unknown) |

Methods

build(): string

Rebuilds the HTTP message with all modifications applied.

const modified = parser.build();

HeadersParser

Manages HTTP headers.

Methods

| Method | Description | | ---------------------------------------------------- | -------------------------------------------------------------- | | get(name: string): string \| undefined | Get a header value | | set(name: string, value: string): void | Set a header value | | remove(name: string): void | Remove a header | | getAll(name: string): string[] | Get all values for a header (for multi-value headers) | | setByPattern(pattern: RegExp, value: string): void | Set all headers matching a pattern | | replace(search: string, replacement: string): void | Replace all occurrences of a string in header names and values |

parser.headers.set("Authorization", "Bearer token");
parser.headers.remove("X-Old-Header");
parser.headers.replace("old", "new"); // Replaces "old" with "new" in all headers

CookiesParser

Manages HTTP cookies.

Methods

| Method | Description | | ---------------------------------------------------- | -------------------------------------------------------------- | | get(name: string): string \| undefined | Get a cookie value | | set(name: string, value: string): void | Set a cookie value | | remove(name: string): void | Remove a cookie | | setByPattern(pattern: RegExp, value: string): void | Set all cookies matching a pattern | | replace(search: string, replacement: string): void | Replace all occurrences of a string in cookie names and values | | build(): string | Build the Cookie header string | | isEmpty(): boolean | Check if there are any cookies |

parser.cookies.set("session", "new-session");
parser.cookies.remove("expired-cookie");
parser.cookies.replace("old", "new"); // Replaces "old" with "new" in all cookies

QueryParser

Manages URL query parameters.

Methods

| Method | Description | | ---------------------------------------------------- | ----------------------------------------------------------------- | | get(name: string): string \| undefined | Get a query parameter value | | set(name: string, value: string): void | Set a query parameter value | | remove(name: string): void | Remove a query parameter | | setByPattern(pattern: RegExp, value: string): void | Set all parameters matching a pattern | | replace(search: string, replacement: string): void | Replace all occurrences of a string in parameter names and values | | build(): string | Build the query string (including ?) |

parser.query.set("page", "2");
parser.query.remove("token");
parser.query.replace("old", "new"); // Replaces "old" with "new" in all query params

PathParser

Manages the URL path.

Methods

| Method | Description | | ---------------------------------------------------- | ---------------------------------------------------- | | set(path: string): void | Set the path | | replace(search: string, replacement: string): void | Replace all occurrences of a string in path segments | | build(): string | Build the path string |

parser.path.set("/api/v2/users");
parser.path.replace("v1", "v2"); // Replaces "v1" with "v2" in path segments

BodyParser

Base interface for body parsers. The actual implementation depends on the detected body type.

Methods

| Method | Description | | ---------------------------------------------------- | ----------------------------------------------------------------- | | get(name: string): string \| undefined | Get a body parameter value | | set(name: string, value: string): void | Set a body parameter value | | remove(name: string): void | Remove a body parameter | | setByPattern(pattern: RegExp, value: string): void | Set all parameters matching a pattern | | replace(search: string, replacement: string): void | Replace all occurrences of a string in parameter names and values | | build(): string | Build the body string | | params: Param[] | Array of all parameters |

parser.body?.set("username", "john");
parser.body?.remove("password");
parser.body?.replace("old", "new"); // Replaces "old" with "new" in all body params

Mutations

Apply multiple mutations at once using the mutations API.

import { applyMutations, type Mutation } from "@caido-utils/parser/mutations";

const mutations: Mutation[] = [
  { kind: "method_set", target: "", value: "POST" },
  { kind: "query_set", target: "id", value: "456" },
  { kind: "query_remove", target: "token", value: "" },
  { kind: "header_set", target: "X-Custom", value: "value" },
  { kind: "cookie_set", target: "session", value: "new-session" },
  { kind: "body_set", target: "username", value: "john" },
  { kind: "path_set", target: "", value: "/api/v2/users" },
];

const modified = applyMutations(rawRequest, mutations);

Mutation Types

| Kind | Target | Value | Description | | ---------------- | -------------- | ------------------ | ------------------------------------------------- | | method_set | ignored | HTTP method | Change the HTTP method | | version_set | ignored | HTTP version | Change the HTTP version | | path_set | ignored | URL path | Change the URL path | | path_replace | string to find | replacement string | Replace all occurrences in path segments | | query_set | param name | param value | Set a query parameter | | query_remove | param name | ignored | Remove a query parameter | | query_replace | string to find | replacement string | Replace all occurrences in query params | | header_set | header name | header value | Set a header | | header_remove | header name | ignored | Remove a header | | header_replace | string to find | replacement string | Replace all occurrences in headers | | cookie_set | cookie name | cookie value | Set a cookie | | cookie_remove | cookie name | ignored | Remove a cookie | | cookie_replace | string to find | replacement string | Replace all occurrences in cookies | | body_set | param name | param value | Set a body parameter | | body_remove | param name | ignored | Remove a body parameter | | body_replace | string to find | replacement string | Replace all occurrences in body params | | raw_replace | string to find | replacement string | Replace all occurrences in the entire raw request |

Body Type Support

The parser automatically detects and handles the following body types:

JSON

const raw = `POST /api/users HTTP/1.1
Content-Type: application/json

{"user": {"name": "john", "email": "[email protected]"}}`;

const parser = new Parser(raw);
parser.body?.set("user.email", "[email protected]"); // Nested access via dot notation

URL-encoded

const raw = `POST /api/users HTTP/1.1
Content-Type: application/x-www-form-urlencoded

username=john&password=secret`;

const parser = new Parser(raw);
parser.body?.set("username", "jane");

Multipart

const raw = `POST /api/upload HTTP/1.1
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary

------WebKitFormBoundary
Content-Disposition: form-data; name="file"

file content
------WebKitFormBoundary--`;

const parser = new Parser(raw);
parser.body?.set("file", "new content");

Response Parsing

The parser also handles HTTP responses:

const rawResponse = `HTTP/1.1 200 OK
Content-Type: application/json
Set-Cookie: session=xyz; Path=/

{"status": "ok"}`;

const parser = new Parser(rawResponse);
console.log(parser.method); // "HTTP/1.1" (first line)
console.log(parser.headers.get("Content-Type")); // "application/json"
console.log(parser.cookies.get("session")); // "xyz"

License

MIT