@itrocks/core-responses
v0.0.11
Published
Prefabricated HTTP it.rocks responses for HTML, JSON, and PDF formats
Maintainers
baptistepillotReadme
core-responses
Prefabricated HTTP it.rocks responses for HTML, JSON, and PDF formats.
This documentation was written by an artificial intelligence and may contain errors or approximations. It has not yet been fully reviewed by a human. If anything seems unclear or incomplete, please feel free to contact the author of this package.
Installation
npm i @itrocks/core-responsesUsage
@itrocks/core-responses provides three small Response subclasses you can
use in any framework or HTTP server integration built on top of
@itrocks/request-response:
HtmlResponse– HTML pages with a convenient defaultContent-Typeand automatic<!DOCTYPE html>prefix.JsonResponse– JSON payloads with safe serialisation (includingbigint) and a typeddataproperty.PdfResponse– binary PDF documents with the appropriateContent-Type: application/pdfheader.
You typically never use this package alone: it is designed to be combined with
@itrocks/request-response (and optionally higher‑level modules such as
@itrocks/action or @itrocks/framework).
Minimal example
import { GET, Request } from '@itrocks/request-response'
import { HtmlResponse } from '@itrocks/core-responses'
// Very small helper turning a framework request into a Request
function toRequest(raw: any): Request {
return new Request(
GET,
'https',
raw.headers.host ?? 'localhost',
443,
raw.url,
raw.headers as Record<string, string>,
raw.query as Record<string, string>,
raw.body as any,
raw.session
)
}
async function helloHtml(rawRequest: any): Promise<HtmlResponse> {
const request = toRequest(rawRequest)
const name = request.parameters.name ?? 'world'
// Body will automatically be prefixed with '<!DOCTYPE html>\n'
return new HtmlResponse(`<html><body>Hello ${name}!</body></html>`)
}Integrated example with JSON and PDF
In a more realistic application you often return HTML for browser views, JSON for APIs, and sometimes PDFs (for example invoices or reports). All of them can be expressed using the specialised responses from this module.
The following pseudo‑adapter shows how you can wire them in an Express‑like
environment (any other framework works the same as long as you can access the
final Response object):
import { GET, Request, Response } from '@itrocks/request-response'
import { HtmlResponse, JsonResponse, PdfResponse } from '@itrocks/core-responses'
function toRequest(raw: any): Request {
return new Request(
GET,
'https',
raw.headers.host ?? 'localhost',
443,
raw.url,
raw.headers as Record<string, string>,
raw.query as Record<string, string>,
raw.body as any,
raw.session
)
}
function send(rawReply: any, response: Response) {
rawReply
.status(response.status)
.headers(response.headers)
.send(response.body)
}
async function htmlRoute(rawReq: any, rawReply: any) {
const request = toRequest(rawReq)
const response = new HtmlResponse('<html>...</html>')
send(rawReply, response)
}
async function jsonRoute(rawReq: any, rawReply: any) {
const request = toRequest(rawReq)
const payload = { ok: true, at: new Date().toISOString() }
const response = new JsonResponse(payload)
send(rawReply, response)
}
async function pdfRoute(rawReq: any, rawReply: any) {
const request = toRequest(rawReq)
const pdfBuffer = await buildInvoicePdf(request)
const response = new PdfResponse(pdfBuffer)
send(rawReply, response)
}API
@itrocks/core-responses exposes the following public classes:
HtmlResponse– specialisedResponsefor HTML bodies.JsonResponse– specialisedResponsefor JSON payloads.PdfResponse– specialisedResponsefor PDF documents.
All of them extend Response from
@itrocks/request-response
and are therefore compatible with any helper or adapter working with that
base type.
class HtmlResponse extends Response
Represents an HTML HTTP response.
Constructor
constructor(body?: string, statusCode?: number, headers?: Headers)Parameters:
body: string = ''– HTML body of the response. If it does not already start with<!DOCTYPE html>, the constructor automatically prefixes it with the HTML5 doctype on a first line. This helps keep all HTML responses consistent without repeating the boilerplate.statusCode: number = 200– HTTP status code.headers: Headers = {}– Additional HTTP headers. IfContent-Typeis not already set, it is automatically initialised totext/html.
Use this class whenever you want to build an HTML page response while letting the module take care of the correct content type and doctype.
class JsonResponse extends Response
Represents a JSON HTTP response with a convenient data property bound to the
underlying body.
Constructor
constructor(data: object | string, statusCode?: number, headers?: Headers)Parameters:
data: object | string– The payload to serialise as JSON. It can be either a plain object/value or a pre‑serialised JSON string.statusCode: number = 200– HTTP status code.headers: Headers = {}– Additional HTTP headers. IfContent-Typeis not already set, it is automatically initialised toapplication/json.
The constructor defines a getter/setter on the inherited body property:
- reading
bodyreturnsJSON.stringify(data)with a replacer that convertsbigintvalues to strings (so that JSON serialisation always works), - writing
bodyparses the JSON string and updatesdataaccordingly.
Typical usage is to read and write the data property from your application
code and let the response handle serialisation for you.
class PdfResponse extends Response
Represents a PDF HTTP response.
Constructor
constructor(data: any, statusCode?: number, headers?: Headers)Parameters:
data: any– Binary content of the PDF (for example aBufferorUint8Array). The class does not enforce a specific type so that it can easily integrate with different PDF generation libraries.statusCode: number = 200– HTTP status code.headers: Headers = {}– Additional HTTP headers. IfContent-Typeis not already set, it is automatically initialised toapplication/pdf.
Use this response when your action produces PDF documents (invoices,
statements, reports…) and you want a correctly initialised Response
instance.
Typical use cases
- Build HTML pages in actions or controllers while letting
HtmlResponseenforce a consistent HTML5 doctype and content type. - Return JSON payloads from API endpoints using
JsonResponse, benefiting from automatic serialisation andbiginthandling. - Serve dynamically generated PDF files (invoices, labels, reports) using
PdfResponsewith the properContent-Typeheader. - Share a small, framework‑agnostic response layer between back‑end modules
such as
@itrocks/action,@itrocks/home,@itrocks/list,@itrocks/printand your own custom actions.