HRest Node (hrest-node)

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

HRest Node provides the enterprise-grade integration layer for the Hyper-REST (HRest) protocol in Node.js and TypeScript environments. By acting as standard Express middleware, it intercepts binary HRest requests, performs high-speed binary-to-JSON decoding via WebAssembly (WASM), and forwards standard JSON to your application.

This architecture ensures seamless adoption. You can maintain your existing Express/TypeScript routers without modifying request handlers, while drastically reducing payload sizes over the network.

Installation

Install the production release directly from NPM:

npm install hrest-node

Integration (Express)

HRest operates as middleware. Ensure it is registered before your primary body parsers if you expect heavy binary traffic.

import express from 'express';
import fs from 'fs';
import { createHrestMiddleware, HrestConfig } from 'hrest-node';

const app = express();

// 1. Load your generated binary contracts
const reqContractStr = fs.readFileSync('../contracts/hrest-req-contract.json', 'utf-8');
const resContractStr = fs.readFileSync('../contracts/hrest-res-contract.json', 'utf-8');

// 2. Configure HRest Middleware
const hrestConfig: HrestConfig = {
    reqContractJson: reqContractStr,
    resContractJson: resContractStr,
    fallbackJson: true,       // Allow standard JSON requests to pass through untouched
    serveContract: true,      // Automatically expose the contract at /hrest-contract
    validateHash: true,       // Prevent version mismatch between client and server
};

const hrestMiddleware = createHrestMiddleware(hrestConfig);

// 3. Mount the middleware globally (or per route)
app.use(hrestMiddleware);
app.use(express.json()); // Standard JSON parsing for non-hrest traffic

Defining Routes and Contract Generation

The HRest CLI analyzes your codebase to auto-generate the optimal dictionary contracts. In TypeScript environments, use the hrestRoute<Req, Res>() dummy function to mark your endpoints for the AST scanner.

import { Router, Request, Response } from 'express';
import { hrestRoute } from 'hrest-node';

// Define standard TypeScript interfaces
export interface ComplexUser {
    id: number;
    name: string;
}

export interface StatsResponse {
    success: boolean;
}

export const router = Router();

// Add the hrestRoute<Req, Res>() marker in your route definition.
// At runtime, it has zero overhead and simply calls next().
router.post('/api/hrest', hrestRoute<ComplexUser, StatsResponse>(), (req: Request, res: Response) => {
    // The request body is already translated to standard JSON
    const user = req.body as ComplexUser;
    
    // Process business logic
    res.json({ success: true } as StatsResponse);
});

Architecture

hrest-node utilizes hrest-core compiled to WebAssembly (WASM). This allows the heavy dictionary-based compression logic and binary structure validation to run near-native speeds outside the standard V8 JavaScript garbage collection cycle, providing stable memory usage under highly concurrent workloads.

License

MIT (c) 2026 HyperRest Project