Utils

Active contributors: dougwilson, wesleytodd, ulisesgascon

Purpose

lib/utils.js is a grab-bag of small helpers used by application.js, request.js, and response.js. Most of them are "compile-on-set" functions that turn a setting value into a runnable function (ETag, query parser, trust proxy), plus a handful of content-type helpers.

271 lines, fully internal — app.set('etag', 'weak') ends up calling compileETag from this file.

Directory layout

lib/
└── utils.js   # this file

Key abstractions

Symbol	Type	What it does
exports.methods	array	node:http's METHODS lowercased. Drives app.METHOD generation in lib/application.js.
exports.etag	function	Strong ETag generator. Built by createETagGenerator({ weak: false }).
exports.wetag	function	Weak ETag generator. Built by createETagGenerator({ weak: true }).
exports.normalizeType(type)	function	Normalises a single MIME or extension to { value, params }. Falls back to application/octet-stream.
exports.normalizeTypes(types)	function	types.map(normalizeType).
exports.compileETag(val)	function	Compiles true / 'weak' / 'strong' / false / function into the ETag function used by res.send.
exports.compileQueryParser(val)	function	Compiles true / 'simple' / 'extended' / false / function into the parser used by req.query.
exports.compileTrust(val)	function	Compiles boolean / number / string / array / function into the (addr, hop) => boolean predicate used by req.ip, req.protocol, req.host.
exports.setCharset(type, charset)	function	Adds or replaces the charset parameter on a Content-Type value. Uses the content-type package.
acceptParams(str)	private	Parses a single Accept entry like text/html; q=0.8 into { value, quality, params }.
createETagGenerator(opts)	private	Wraps the etag package with a body-to-Buffer normalisation.
parseExtendedQueryString(str)	private	qs.parse(str, { allowPrototypes: true }).

How it works

Compilation pattern

The "compile" helpers turn a flexible user input into a single function with a fixed signature, so the runtime path stays branch-free.

graph TD
    UserSet["app.set 'trust proxy', 'loopback'"] --> AppSet[app.set switch]
    AppSet --> CompileT[compileTrust 'loopback']
    CompileT --> SplitTrim[split on commas + trim]
    SplitTrim --> Compile[proxyaddr.compile arr]
    Compile --> Fn[trust = function addr, hop -> bool]
    Fn --> Stored[app.settings 'trust proxy fn']
    Stored --> ReqIP[req.ip uses it]

The same pattern repeats for etag, query parser, and trust proxy. The runtime helpers (req.ip, req.protocol, res.send's ETag generation) just call the compiled function — they don't need to know anything about how it was configured.

Trust proxy compilation specifics

compileTrust accepts:

Input	Resulting function
function	Used directly.
true	Always returns true.
number n	(addr, i) => i < n — trust the first n hops.
string	Comma-split and trimmed, then passed to proxyaddr.compile.
array	Passed to proxyaddr.compile.
(otherwise)	proxyaddr.compile([]) — i.e., trust nothing.

This shape is what the request helpers in lib/request.js rely on.

ETag generators

function createETagGenerator(options) {
  return function generateETag(body, encoding) {
    var buf = !Buffer.isBuffer(body) ? Buffer.from(body, encoding) : body;
    return etag(buf, options);
  };
}

compileETag returns either wetag (weak), etag (strong), undefined (when false), or a user-provided function. res.send then calls it as etagFn(chunk, encoding).

setCharset

A small wrapper used by res.set and res.send:

exports.setCharset = function setCharset(type, charset) {
  if (!type || !charset) return type;
  var parsed = contentType.parse(type);
  parsed.parameters.charset = charset;
  return contentType.format(parsed);
};

It uses the content-type package so it correctly handles edge cases like quoted parameter values.

Integration points

• Imports: node:http (METHODS), content-type, etag, mime-types, proxy-addr, qs, node:querystring, node:buffer (Buffer).
• Consumed by: lib/application.js (compile helpers, methods), lib/response.js (normalizeType, normalizeTypes, setCharset), and any code path reading the compiled settings.

Entry points for modification

• New ETag mode → add a case in compileETag, possibly a new createETagGenerator flavour.
• New query parser mode → add a case in compileQueryParser.
• Change trust-proxy semantics → modify compileTrust and the consumers in lib/request.js.

Key source files

File	Purpose
lib/utils.js	Compile helpers, content-type helpers, methods list
lib/application.js	Calls compile helpers from inside app.set
lib/request.js	Reads query parser fn, trust proxy fn, subdomain offset
lib/response.js	Reads etag fn, calls normalizeType and setCharset

Related pages

• Application for the settings store these helpers feed.
• Reference / Configuration for the user-facing setting names.