Automatic XML ↔ JSON Conversion
High-performance, bi-directional streaming transcoder built directly into the native XHSC networking stack—automatically converting incoming XML payloads to JSON (xml2json) and mirroring JSON responses back to XML (json2xml).
Go-Native Transcoding
XML parsing and serialization run inside the XHSC Go core before the payload reaches Node.js or Bun, keeping the JS event loop unblocked.
Bi-Directional Mirroring (autoReply)
Write standard JSON handlers in TypeScript. If the client sent XML, XHSC automatically transcodes your JSON response back to application/xml.
Virtual Body Proxy
ConversionProxyMiddleware wraps req.body so XML attributes (e.g. @id) and #text nodes are accessed naturally as standard properties.
Content Sniffing
Detects XML payloads starting with < even when clients omit Content-Type or send generic text/plain headers.
Server Configuration
Enable native conversion in createServer via the conversion option:
import { createServer } from "xypriss";
const app = createServer({
server: { port: 3000 },
conversion: {
enabled: true,
xmlToJson: true, // Convert incoming XML -> JSON (req.body)
autoReply: true, // Convert outgoing JSON -> XML for XML callers
attributePrefix: "@", // Prefix for XML attributes in JSON
textContentKey: "#text", // Key for mixed text + attribute nodes
maxConversionSize: "10mb",
strictParsing: true, // Return 400 Bad Request on malformed XML
contentSniffing: true, // Auto-detect '<' payloads without XML header
},
});
app.post("/api/orders", (req, res) => {
// Even if the client sent application/xml, req.body is already JSON!
const { order } = req.body;
// Reply with standard JSON; XHSC converts it to XML if autoReply is true
res.json({
status: "accepted",
orderId: order.id,
});
});
app.start();How Bi-Directional Transcoding Works
1. Incoming Request (xml2json)
When a non-GET request arrives with Content-Type: application/xml or text/xml (or starts with < when contentSniffing is enabled):
- XHSC parses the XML body natively and converts it into JSON.
- Sets
X-XHSC-Origin-Format: xmlandX-XHSC-Origin-Content-Typeheaders so downstream middleware knows the original format. - Replaces the request
Content-Typewithapplication/jsonso your route handler receives a parsedreq.bodyobject.
2. Outgoing Response (json2xml)
When autoReply: true is enabled:
- XHSC checks if
X-XHSC-Origin-Formatisxmland the handler responseContent-Typeisapplication/json. - Unless the client explicitly sent
Accept: application/json, XHSC transcodes the JSON response body into XML and setsContent-Type: application/xml.
Accept: application/json, XHSC respects the client's preference and skips json2xml response transcoding, returning JSON directly.Virtual Body Proxy (Attributes & Text Unwrapping)
When XHSC converts XML attributes and text nodes to JSON using attributePrefix (default "@") and textContentKey (default "#text"), XyPriss's ConversionProxyMiddleware wraps req.body in a recursive Proxy so you can access properties cleanly without bracket notation:
<order id="ORD-9042" currency="USD">
<customer>Jane Doe</customer>
<total>149.99</total>
</order>app.post("/api/orders", (req, res) => {
const { order } = req.body;
// Attribute '@id' is accessible directly as 'order.id'
console.log(order.id); // "ORD-9042"
console.log(order["@id"]); // "ORD-9042" (also works)
console.log(order.currency); // "USD"
// Text-only nodes unwrap automatically
console.log(order.customer); // "Jane Doe"
console.log(order.total); // "149.99"
res.json({ received: order.id });
});Configuration Options Reference
| Option | Type | Default | Description |
|---|---|---|---|
| enabled | boolean | false | Enables the native XHSC data conversion pipeline. |
| xmlToJson | boolean | false | Automatically converts incoming XML payloads to JSON on req.body. |
| autoReply | boolean | false | Automatically converts outgoing JSON responses back to XML when the request originated as XML. |
| attributePrefix | string | "@" | Prefix used for XML attributes when converted to JSON keys. |
| textContentKey | string | "#text" | Key name for XML text content when a node contains both attributes and text. |
| maxConversionSize | number | string | — | Maximum payload size allowed for conversion (bytes or string, e.g. "10mb"). |
| strictParsing | boolean | false | If true, malformed XML returns 400 Bad Request. If false, the original body is forwarded with X-XHSC-Conversion-Error. |
| contentSniffing | boolean | false | Peeks the first byte of missing or generic Content-Type payloads; if it starts with <, treats it as application/xml. |
Explore XyPriss's high-performance BigInt-safe, streaming JSON serializer.
