@blamejs/core 0.8.42 → 0.8.49

package/lib/render.js

@@ -1,52 +1,31 @@
 "use strict";
 /**
- * Response helpers — render a value into an HTTP response with the
- * right Content-Type, status, and body shape, in one call.
- *
- * Without these helpers every route handler reimplements the same
- * five lines: pick a status code, set Content-Type, JSON.stringify
- * (or render a template), set Content-Length, end the response. With
- * them, each response shape is a single call:
- *
- *   render.json(res, { ok: true })
- *   render.text(res, "OK")
- *   render.redirect(res, "/login")
- *   render.htmlString(res, "<h1>Hi</h1>")
- *   r.html(res, "home", { user: req.user })   // engine-bound (see create())
- *
- * The template engine isn't required to use any of the non-HTML
- * helpers. Operators who never render server-side HTML just import
- * the module-level json/text/redirect.
- *
- * Public API:
- *
- *   render.json(res, body, opts?)
- *     → JSON-stringifies body, sets Content-Type application/json;
- *       opts.status (default 200) + opts.headers merged.
- *
- *   render.text(res, body, opts?)
- *     → text/plain. opts.status / opts.headers / opts.charset (default utf-8).
- *
- *   render.htmlString(res, htmlString, opts?)
- *     → text/html for a pre-rendered string; same opts shape.
- *
- *   render.redirect(res, location, opts?)
- *     → opts.status (default 302; 301/303/307/308 also valid).
- *       Location is set; body empty.
- *
- *   render.create({ engine }) → {
- *     html(res, viewName, data?, opts?)         engine-rendered HTML
- *     json, text, htmlString, redirect          re-exported for one-import ergonomics
- *   }
- *     engine is a template engine instance from
- *     b.template.create({ viewsDir }). html() throws if rendering
- *     fails — wire b.middleware.errorHandler downstream to convert
- *     to a sanitized 500 response.
- *
- * All helpers fall through silently when res is already finished
- * (`writableEnded === true`). Mid-stream double-writes from a route
- * that already sent a response (e.g. a Promise rejection after
- * res.end) won't corrupt the wire.
+ * @module b.render
+ * @nav    HTTP
+ * @title  Render
+ *
+ * @intro
+ *   Server-side HTML / JSON / XML response helpers. Each helper picks
+ *   the right Content-Type, sets a sensible Cache-Control + security
+ *   header default, and ends the response in one call — replacing the
+ *   five-line writeHead / stringify / Content-Length / end ritual that
+ *   every route handler otherwise reimplements.
+ *
+ *   Module-level helpers (`json` / `text` / `htmlString` / `redirect`)
+ *   work without a template engine. `create({ engine })` wraps a
+ *   `b.template.create` instance and returns the same helpers plus
+ *   `html(res, viewName, data?)` for engine-rendered pages. Operators
+ *   who never render server-side HTML import only the module-level
+ *   helpers and skip the engine wiring entirely.
+ *
+ *   All helpers fall through silently when `res.writableEnded === true`,
+ *   so a late Promise rejection after `res.end` can't corrupt the wire
+ *   with a half-written second body. The default `Cache-Control` is
+ *   `private, no-cache, must-revalidate` — overridable via
+ *   `opts.headers["Cache-Control"]` for CDN-cacheable responses.
+ *
+ * @card
+ *   Server-side HTML / JSON / XML response helpers.
  */
 
 var DEFAULT_CHARSET = "utf-8";
@@ -88,6 +67,29 @@ function _mergedHeaders(base, extra) {
 // response override via `opts.headers["Cache-Control"]`.
 var DEFAULT_DYNAMIC_CACHE_CONTROL = "private, no-cache, must-revalidate";
 
+/**
+ * @primitive b.render.json
+ * @signature b.render.json(res, body, opts)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.render.text, b.render.htmlString, b.render.create
+ *
+ * JSON-stringifies `body` and writes it to `res` with Content-Type
+ * `application/json; charset=utf-8`, an explicit `Content-Length`,
+ * and the dynamic-response Cache-Control. Status defaults to 200;
+ * any custom headers in `opts.headers` merge over the defaults so
+ * operators can pin a different Cache-Control or add CORS headers
+ * without losing Content-Type. Returns `undefined` — the response
+ * is fully written by the time the call returns.
+ *
+ * @opts
+ *   status:  200,   // numeric HTTP status (200/201/202/4xx/5xx)
+ *   headers: {},    // merged over defaults; later wins
+ *
+ * @example
+ *   b.render.json(res, { ok: true, id: 42 }, { status: 201 });
+ *   // → response: 201, application/json, body `{"ok":true,"id":42}`
+ */
 function json(res, body, opts) {
   opts = opts || {};
   var encoded = JSON.stringify(body);
@@ -99,6 +101,27 @@ function json(res, body, opts) {
   _writeResponse(res, opts.status || 200, headers, encoded);
 }
 
+/**
+ * @primitive b.render.text
+ * @signature b.render.text(res, body, opts)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.render.json, b.render.htmlString
+ *
+ * Coerces `body` to a string and writes it as `text/plain` with the
+ * supplied charset (default `utf-8`). `null` / `undefined` body
+ * becomes the empty string rather than the literal text `"null"` —
+ * a common gotcha when forwarding a value-or-nothing handler result.
+ *
+ * @opts
+ *   status:  200,
+ *   headers: {},
+ *   charset: "utf-8",
+ *
+ * @example
+ *   b.render.text(res, "OK");
+ *   // → 200, Content-Type "text/plain; charset=utf-8", body "OK"
+ */
 function text(res, body, opts) {
   opts = opts || {};
   var encoded = body == null ? "" : String(body);
@@ -111,6 +134,28 @@ function text(res, body, opts) {
   _writeResponse(res, opts.status || 200, headers, encoded);
 }
 
+/**
+ * @primitive b.render.htmlString
+ * @signature b.render.htmlString(res, htmlBody, opts)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.render.json, b.render.create
+ *
+ * Writes a pre-rendered HTML string with `Content-Type: text/html;
+ * charset=<charset>`. Use when an HTML body is already in hand — for
+ * engine-bound view rendering, prefer `b.render.create({ engine })`
+ * and the returned `html(res, viewName, data)` helper which threads
+ * `res.locals` (CSP nonce, request id, current user) into the view.
+ *
+ * @opts
+ *   status:  200,
+ *   headers: {},
+ *   charset: "utf-8",
+ *
+ * @example
+ *   b.render.htmlString(res, "<h1>Hi</h1>");
+ *   // → 200, text/html; charset=utf-8, body "<h1>Hi</h1>"
+ */
 function htmlString(res, htmlBody, opts) {
   opts = opts || {};
   var encoded = htmlBody == null ? "" : String(htmlBody);
@@ -123,6 +168,28 @@ function htmlString(res, htmlBody, opts) {
   _writeResponse(res, opts.status || 200, headers, encoded);
 }
 
+/**
+ * @primitive b.render.redirect
+ * @signature b.render.redirect(res, location, opts)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.safeRedirect, b.render.json
+ *
+ * Sends a 3xx response with the given `Location` header and an empty
+ * body. Throws when `location` is empty or when `opts.status` falls
+ * outside the 300–399 range. Default status is 302; pass 301 / 303 /
+ * 307 / 308 for the other RFC 7231 / 7538 redirect semantics. For
+ * untrusted user-supplied destinations, validate first via
+ * `b.safeRedirect` before passing the result here.
+ *
+ * @opts
+ *   status:  302,   // 301 / 302 / 303 / 307 / 308
+ *   headers: {},
+ *
+ * @example
+ *   b.render.redirect(res, "/login", { status: 303 });
+ *   // → 303, Location "/login", empty body
+ */
 function redirect(res, location, opts) {
   opts = opts || {};
   if (typeof location !== "string" || location.length === 0) {
@@ -142,6 +209,31 @@ function redirect(res, location, opts) {
 
 // ---- Engine-bound instance ----
 
+/**
+ * @primitive b.render.create
+ * @signature b.render.create(opts)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.template.create, b.render.htmlString
+ *
+ * Binds a template engine to a renderer and returns the module-level
+ * helpers (`json` / `text` / `htmlString` / `redirect`) plus
+ * `html(res, viewName, data?, opts?)`. The `html` helper auto-merges
+ * `res.locals` into the template data so request-scoped values
+ * (CSP nonce, request id, current user) thread through every render
+ * without per-route plumbing. Operator-supplied `data` keys take
+ * precedence over locals — explicit beats implicit. Throws when
+ * `opts.engine.render` is not a function.
+ *
+ * @opts
+ *   engine: <required>,   // a template engine instance from b.template.create({ viewsDir })
+ *
+ * @example
+ *   var engine = b.template.create({ viewsDir: "/srv/views" });
+ *   var r      = b.render.create({ engine: engine });
+ *   r.html(res, "home", { user: "ada" });
+ *   // → 200, text/html; charset=utf-8, body = engine.render("home", merged-locals)
+ */
 function create(opts) {
   opts = opts || {};
   if (!opts.engine || typeof opts.engine.render !== "function") {