HRest TypeScript (hrest-ts)

Benchmark | Core | CLI | Python | Node | Go | TS

Enterprise-grade TypeScript Client SDK for the HRest Binary Protocol

hrest-ts is a Zero-Dependency, Isomorphic client SDK. It works seamlessly in both Browser (React, Vue, Angular) and Node.js environments using standard Uint8Array and DataView primitives.

It automatically intercepts standard fetch API calls, transparently encoding JSON into binary TLV (Type-Length-Value) before sending, and decoding it back into JSON upon receiving.

Installation

npm install hrest-ts

Quick Start

1. Initialize the Client

Initialize the SDK once at the root of your application using the centralized config pattern. This requires the JSON contract files generated by running npx hrestc gen contract on your backend repository.

import { createHrestClient } from 'hrest-ts';

// Webpack/Vite will bundle these JSONs automatically
import reqContract from './hrest-req-contract.json';
import resContract from './hrest-res-contract.json';

// Create the interceptor client
const hrest = createHrestClient({
    reqContract,
    resContract,
    fallbackJson: true // Fallback to normal application/json if route isn't in contract
});

2. Make API Calls

Use the hrest.fetch method exactly as you would use the native window.fetch. Everything is handled transparently!

async function runTask() {
    const response = await hrest.fetch('/api/v1/run', {
        method: 'POST',
        // Pass JSON normally. It will be intercepted and encoded to binary!
        body: JSON.stringify({
            event: "click",
            headless: true,
            task_id: 42
        })
    });

    // The response is already decoded from binary back to JSON!
    const data = await response.json();
    console.log("Success:", data);
}

How it works

1. hrest.fetch detects an outgoing JSON body.
2. It looks up the route (POST /api/v1/run) in the memory HrestRegistry.
3. If found, it translates your JSON keys into binary FieldIDs (e.g. event -> 0x01).
4. It sets the Content-Type: application/hrest and X-Hrest-Req-Hash headers.
5. On response, it detects application/hrest, reads the binary ArrayBuffer, and translates the FieldIDs back into JSON strings before returning the mocked Response object to you.

Architecture

• Monorepo Structure: This package is a thin network wrapper around hrest-vcore, which contains the pure binary algorithms and HrestRegistry.
• Clean Architecture: Strictly isolates Domain and Application layers (inside hrest-vcore) from the Infrastructure layer (Fetch Wrapper inside hrest-ts).
• Isomorphic: Uses only standard Web APIs (DataView, TextEncoder, TextDecoder, fetch). No Node.js specific Buffer.
• High Performance: Zigzag varint encoding for small integers, highly optimized Uint8Array manipulation.

License

MIT © 2026 HyperRest Project