http_server_response.js

// Copyright Titanium I.T. LLC.
import * as ensure from "util/ensure.js";

/** A response from the HTTP server to a client. */
export class HttpServerResponse {

	/**
	 * Factory method. Creates an HTTP response.
	 * @param options the response details
	 * @param options.status status code
	 * @param [options.headers] headers
	 * @param options.body body
	 * @param [options.contentType] content-type header (for convenience; same as options.headers["content-type"])
	 * @param [options.debug] appears in logs, but is otherwise unused
	 * @returns {HttpServerResponse} the response
	 */
	static create(options) {
		ensure.signature(arguments, [{
			status: Number,
			headers: [ undefined, Object ],
			body: String,
			contentType: [ undefined, String ],
			debug: [ undefined, Object, String ],
		}]);

		const { contentType, ...remainingOptions } = options;

		return new HttpServerResponse(remainingOptions, contentType);
	}

	/**
	 * Test-only factory method. Provides overridable defaults for all response details.
	 * @param [options] the response details
	 * @param options.status status code
	 * @param [options.headers] headers
	 * @param [options.body] body
	 * @param [options.contentType] content-type header (for convenience; same as options.headers["content-type"])
	 * @param [options.debug] appears in logs, but is otherwise unused
	 * @returns {HttpServerResponse} the response
	 */
	static createForTestingOnly(options = {}) {
		ensure.signature(arguments, [[ undefined, {
			status: [ undefined, Number ],
			headers: [ undefined, Object ],
			body: [ undefined, String ],
			contentType: [ undefined, String ],
			debug: [ undefined, Object, String ],
		}]]);
		const DEFAULTS = {
			status: 200,
			body: "default test body"
		};

		options = { ...DEFAULTS, ...options };
		return new HttpServerResponse(options, options.contentType);
	}

	/**
	 * Convenience factory method for creating plain text responses.
	 * @param options the response details
	 * @param options.status status code
	 * @param [options.headers] headers
	 * @param options.body body
	 * @param [options.debug] appears in logs, but is otherwise unused
	 * @returns {HttpServerResponse} the response
	 */
	static createPlainTextResponse(options) {
		ensure.signature(arguments, [{
			status: Number,
			headers: [ undefined, Object ],
			body: String,
			debug: [ undefined, Object, String ],
		}]);

		return new HttpServerResponse(options, "text/plain; charset=utf-8");
	}

	/**
	 * Convenience factory method for creating HTML responses.
	 * @param options the response details
	 * @param options.status status code
	 * @param [options.headers] headers
	 * @param options.body body
	 * @param [options.debug] appears in logs, but is otherwise unused
	 * @returns {HttpServerResponse} the response
	 */
	static createHtmlResponse(options) {
		ensure.signature(arguments, [{
			status: Number,
			headers: [ undefined, Object ],
			body: String,
			debug: [ undefined, Object, String ],
		}]);

		return new HttpServerResponse(options, "text/html; charset=utf-8");
	}

	/**
	 * Convenience factory method for creating JSON responses.
	 * @param options the response details
	 * @param options.status status code
	 * @param [options.headers] headers
	 * @param options.body body
	 * @param [options.debug] appears in logs, but is otherwise unused
	 * @returns {HttpServerResponse} the response
	 */
	static createJsonResponse(options) {
		ensure.signature(arguments, [{
			status: Number,
			headers: [ undefined, Object ],
			body: Object,
			debug: [ undefined, Object, String ],
		}]);

		options = { ...options, body: JSON.stringify(options.body) };
		return new HttpServerResponse(options, "application/json");
	}

	/** Only for use by tests. (Use a factory method instead.) */
	constructor(options, contentType) {
		this._status = options.status;
		const contentTypeHeaders = contentType !== undefined ? { "content-type": contentType } : {};
		this._headers = { ...contentTypeHeaders, ...options.headers };
		this._body = options.body;

		// We provide this field so it can be viewed in failing tests. It's not used in any way.
		if (options.debug instanceof Error) this._debug = options.debug.stack;
		else if (options.debug !== undefined) this._debug = options.debug;
	}

	/**
	 * @returns {number} status code
	 */
	get status() {
		return this._status;
	}

	/**
	 * @returns {object} headers
	 */
	get headers() {
		return this._headers;
	}

	/**
	 * @returns {string} body
	 */
	get body() {
		return this._body;
	}

}