sprucehttp_sjs 1.0.12 → 2.1.0

package/README.md

@@ -10,19 +10,19 @@ A module for responding to requests within SpruceHTTP in an SJS file.
 	- [writeData(data)](#writedatadata)
 	- [writeDataAsync(data)](#writedataasyncdata)
 	- [clearResponse()](#clearresponse)
-	- [siteConfig()](#siteconfig)
-	- [requestIP()](#requestip)
-	- [method()](#method)
-	- [path()](#path)
-	- [pathInfo()](#pathinfo)
-	- [query()](#query)
+	- [siteConfig](#siteconfig)
+	- [requestIP](#requestip)
+	- [method](#method)
+	- [path](#path)
+	- [pathInfo](#pathinfo)
+	- [query](#query)
 	- [queryValue(key)](#queryvaluekey)
-	- [httpVersion()](#httpversion)
-	- [headers()](#headers)
+	- [httpVersion](#httpversion)
+	- [headers](#headers)
 	- [headerValue(name)](#headervaluename)
-	- [body()](#body)
-	- [bodyStream()](#bodystream)
-	- [getMTlsPeerCertificate()](#getmtlspeercertificate)
+	- [body](#body)
+	- [bodyStream([options])](#bodystreamoptions)
+	- [mTlsPeerCertificate](#mtlspeercertificate)
 
 ## Documentation:
 Importing the module:
@@ -35,16 +35,20 @@ Sets the response into stream mode. This cannot be undone for the duration of th
 
 Stream mode means that responses are not buffered by the webserver, and thus are sent immediately as they're received from the SJS script. This means that the status line and headers _**must**_ be sent first before the data, and the ``\r\n`` after the headers must be sent by the script as well.
 
+Returns a Promise that resolves when the server acknowledges the switch to stream mode.
+
 ```js
 sjs.streamMode(); // Set the response to stream mode.
 ```
 
 ### ``writeStatusLine(statusCode[, reasonPhrase])``:
  - ``statusLine:`` number: The HTTP status code to send.
- - ``reasonPhrase:`` string: The reason phrase to send.
+ - ``reasonPhrase:`` string: Optional. The reason phrase to send.
 
 Writes the status line to the response.
 
+Returns a Promise that resolves when the server acknowledges the status line.
+
 To send a 200 "OK" response, without needing to specify the reason phrase.
 ```js
 sjs.writeStatusLine(200);
@@ -61,6 +65,8 @@ sjs.writeStatusLine(418, "I'm a teapot");
 
 Writes a header to the response.
 
+Returns a Promise that resolves when the server acknowledges the header.
+
 To write the "Content-Type: text/html" header.
 ```js
 sjs.writeHeader("Content-Type", "text/html");
@@ -71,6 +77,8 @@ sjs.writeHeader("Content-Type", "text/html");
 
 Writes data (the body) to the response. When not in stream mode, the Content-Length header is automatically updated.
 
+This function is deprecated. Use ``writeDataAsync`` instead, as data cannot be reliably sent synchronously.
+
 Writes text data to the body.
 ```js
 sjs.writeData("Hello, world!");
@@ -87,6 +95,8 @@ sjs.writeData(fs.readFileSync("image.png", 'binary'));
 
 Writes data (the body) to the response asynchronously. When not in stream mode, the Content-Length header is automatically updated.
 
+Returns a Promise that resolves when the data has been written.
+
 Writes text data to the body.
 ```js
 await sjs.writeDataAsync("Hello, world!");
@@ -102,6 +112,8 @@ await sjs.writeDataAsync(fs.readFileSync("image.png", 'binary'));
 Clears the currently written response and resets the status line, headers, and body.
 This is useful when you want to send a different response than the one you have already written.
 
+Returns a Promise that resolves when the response has been cleared.
+
 This function does not work in stream mode.
 
 ```js
@@ -116,11 +128,13 @@ sjs.writeHeader("Content-Type", "text/html");
 sjs.writeData("<h1>I'm <i>not</i> a teapot</h1>");
 ```
 
-### ``siteConfig()``:
+### ``siteConfig``:
 Returns the site-specific configuration set in your config file.
 
+Returns an object representing the site configuration.
+
 ```js
-console.log(sjs.siteConfig());
+console.log(sjs.siteConfig);
 /*
 {
 	"type": "local",
@@ -141,46 +155,46 @@ console.log(sjs.siteConfig());
 */
 ```
 
-### ``requestIP()``:
+### ``requestIP``:
 Returns the requestor's IP address.
 
 ```js
-console.log(sjs.requestIP());
+console.log(sjs.requestIP);
 // ::ffff:127.0.0.1
 ```
 
-### ``method()``:
+### ``method``:
 Returns the request method.
 
 ```js
-console.log(sjs.method());
+console.log(sjs.method);
 // get
 ```
 
-### ``path()``:
+### ``path``:
 Returns the request path.
 
 ```js
-console.log(sjs.path());
+console.log(sjs.path);
 // /index.sjs
 ```
 
-### ``pathInfo()``:
+### ``pathInfo``:
 Returns the request's info path.
 
 ```js
 // Using path /index.sjs/info
-console.log(sjs.path());
-console.log(sjs.pathInfo());
+console.log(sjs.path);
+console.log(sjs.pathInfo);
 // /index.sjs
 // /info
 ```
 
-### ``query()``:
+### ``query``:
 Returns the request query.
 
 ```js
-console.log(sjs.query());
+console.log(sjs.query);
 /*
 {
 	"name": "John",
@@ -199,19 +213,19 @@ console.log(sjs.queryValue("name"));
 // John
 ```
 
-### ``httpVersion()``:
+### ``httpVersion``:
 Returns the HTTP version of the request.
 
 ```js
-console.log(sjs.httpVersion());
+console.log(sjs.httpVersion);
 // http/1.1
 ```
 
-### ``headers()``:
+### ``headers``:
 Returns the request headers.
 
 ```js
-console.log(sjs.headers());
+console.log(sjs.headers);
 /*
 {
 	"connection": "keep-alive",
@@ -232,15 +246,16 @@ console.log(sjs.headerValue("user-agent"));
 // Bruh/1.0 (Macintosh; PPC Mac OS X 7_0_1) AppleBruhKit 1.3 (XHTML, like IE) Netscape/69.420 Moment/360 NoScope/1.0
 ```
 
-### ``body()``:
+### ``body``:
 Returns the request body as a buffer.
 
 ```js
-console.log(sjs.body().toString("utf8"));
+console.log(sjs.body.toString("utf8"));
 // Hello, world!
 ```
 
-### ``bodyStream()``:
+### ``bodyStream([options])``:
+ - ``options:`` BufferEncoding | ReadStreamOptions: Optional. The options to pass to fs.createReadStream.
 Returns the request body as a ReadStream.
 
 ```js
@@ -248,10 +263,10 @@ console.log(sjs.bodyStream().read(13).toString("utf8"));
 // Hello, world!
 ```
 
-### ``getMTlsPeerCertificate()``:
+### ``mTlsPeerCertificate``:
 Returns details about the mTLS peer's certificate, if present.
 
 ```js
-console.log(sjs.getMTlsPeerCertificate().subject.CN);
+console.log(sjs.mTlsPeerCertificate.subject.CN);
 // sprucehttp.com
 ```

package/index.js

@@ -1,16 +1,19 @@
 // This is still CommonJS to support both the old and new versions of the module system.
 // eslint-disable-next-line @typescript-eslint/no-require-imports
-const fs = require("fs");
+const fs = require("node:fs");
 
 module.exports = {
 	/**
 	 * Sets the response into stream mode.
 	 * 
 	 * Stream mode means that responses are not buffered by the webserver.
+	 * @returns {Promise<void>} A Promise that resolves when the server acknowledges the switch to stream mode.
 	 */
-	streamMode: function () {
-		process.send({
-			type: "streamMode"
+	streamMode() {
+		return new Promise(function (resolve) {
+			process.send({
+				type: "streamMode"
+			}, resolve);
 		});
 	},
 
@@ -18,12 +21,15 @@ module.exports = {
 	 * Writes the status line to the response.
 	 * @param {number} statusCode The HTTP status code to send.
 	 * @param {string} [reasonPhrase] The reason phrase to send.
-	 */
-	writeStatusLine: function (statusCode, reasonPhrase) {
-		process.send({
-			type: "status",
-			statusCode,
-			reasonPhrase
+	 * @return {Promise<void>} A Promise that resolves when the server acknowledges the status line.
+	 */
+	writeStatusLine(statusCode, reasonPhrase) {
+		return new Promise(function (resolve) {
+			process.send({
+				type: "status",
+				statusCode,
+				reasonPhrase
+			}, resolve);
 		});
 	},
 
@@ -31,12 +37,15 @@ module.exports = {
 	 * Writes a header to the response.
 	 * @param {string} name The name of the header to send.
 	 * @param {string} value The value of the header to send.
-	 */
-	writeHeader: function (name, value) {
-		process.send({
-			type: "header",
-			name,
-			value
+	 * @return {Promise<void>} A Promise that resolves when the server acknowledges the header.
+	 */
+	writeHeader(name, value) {
+		return new Promise(function (resolve) {
+			process.send({
+				type: "header",
+				name,
+				value
+			}, resolve);
 		});
 	},
 
@@ -45,18 +54,23 @@ module.exports = {
 	 * 
 	 * When not in stream mode, the Content-Length header is automatically updated.
 	 * @param {string | Buffer} data The data to send.
+	 * @returns {void}
+	 * @deprecated Use writeDataAsync instead. Data cannot be reliably sent synchronously. Will be removed in a future major version.
 	 */
-	writeData: function (data) {
+	writeData(data) {
 		(async () => { await this.writeDataAsync(data); })();
 	},
 
 	/**
 	 * Writes data (the body) to the response asynchronously.
 	 * 
+	 * Will be renamed to writeData in a future major version.
+	 * 
 	 * When not in stream mode, the Content-Length header is automatically updated.
 	 * @param {string | Buffer} data The data to send.
+	 * @returns {Promise<void>} A Promise that resolves when the data has been written.
 	 */
-	writeDataAsync: function (data) {
+	writeDataAsync(data) {
 		// eslint-disable-next-line no-async-promise-executor
 		return new Promise(async function (resolve) {
 			// Send the data in 1 MiB chunks
@@ -85,10 +99,13 @@ module.exports = {
 	 * This is useful when you want to send a different response than the one you have already written.
 	 * 
 	 * This function does not work in stream mode.
+	 * @returns {Promise<void>} A Promise that resolves when the response has been cleared.
 	 */
-	clearResponse: function () {
-		process.send({
-			type: "clear"
+	clearResponse() {
+		return new Promise(function (resolve) {
+			process.send({
+				type: "clear"
+			}, resolve);
 		});
 	},
 
@@ -97,7 +114,7 @@ module.exports = {
 	 * 
 	 * @returns {{[key: string]: string}} The site-specific configuration.
 	 */
-	siteConfig: function () {
+	get siteConfig() {
 		return JSON.parse(process.env.siteConfig);
 	},
 
@@ -106,7 +123,7 @@ module.exports = {
 	 * 
 	 * @returns {string} The requestor's IP address.
 	 */
-	requestIP: function () {
+	get requestIP() {
 		return process.env.reqIP;
 	},
 
@@ -115,7 +132,7 @@ module.exports = {
 	 * 
 	 * @returns {string} The request method.
 	 */
-	method: function () {
+	get method() {
 		return process.env.reqMethod.toLowerCase();
 	},
 
@@ -124,7 +141,7 @@ module.exports = {
 	 * 
 	 * @returns {string} The full request path.
 	 */
-	path: function () {
+	get path() {
 		return process.env.reqPath;
 	},
 
@@ -133,7 +150,7 @@ module.exports = {
 	 * 
 	 * @returns {string} The request's info path.
 	 */
-	pathInfo: function () {
+	get pathInfo() {
 		return process.env.reqPathInfo;
 	},
 
@@ -142,7 +159,7 @@ module.exports = {
 	 * 
 	 * @returns {{[key: string]: string}} The parsed query string of the request.
 	 */
-	query: function () {
+	get query() {
 		return JSON.parse(process.env.reqQuery || "{}");
 	},
 
@@ -152,8 +169,8 @@ module.exports = {
 	 * @param {string} key The key of the query to get.
 	 * @returns {string} The value of the query parameter.
 	 */
-	queryValue: function (key) {
-		return this.query()[key];
+	queryValue(key) {
+		return this.query[key];
 	},
 
 	/**
@@ -161,7 +178,7 @@ module.exports = {
 	 * 
 	 * @returns {string} The HTTP version of the request.
 	 */
-	httpVersion: function () {
+	get httpVersion() {
 		return process.env.reqHttpVersion;
 	},
 
@@ -170,7 +187,7 @@ module.exports = {
 	 * 
 	 * @returns {{[key: string]: string}} The headers of the request.
 	 */
-	headers: function () {
+	get headers() {
 		return JSON.parse(process.env.reqHeaders || "{}");
 	},
 
@@ -180,8 +197,8 @@ module.exports = {
 	 * @param {string} name The name of the header to get.
 	 * @returns {string} The value of the header.
 	 */
-	headerValue: function (name) {
-		return this.headers()[name];
+	headerValue(name) {
+		return this.headers[name];
 	},
 
 	/**
@@ -189,7 +206,7 @@ module.exports = {
 	 * 
 	 * @returns {Buffer} The body of the request.
 	 */
-	body: function () {
+	get body() {
 		let retVal = undefined;
 		if (process.env.reqBody) {
 			retVal = fs.readFileSync(process.env.reqBody);
@@ -203,7 +220,7 @@ module.exports = {
 	 * @param {BufferEncoding | ReadStreamOptions} [options] The options to pass to fs.createReadStream.
 	 * @returns {fs.ReadStream} A ReadStream of the body of the request.
 	 */
-	bodyStream: function (options) {
+	bodyStream(options) {
 		let retVal = undefined;
 		if (process.env.reqBody) {
 			retVal = fs.createReadStream(process.env.reqBody, options);
@@ -214,9 +231,9 @@ module.exports = {
 	/**
 	 * Returns details about the mTLS peer's certificate, if present.
 	 * 
-	 * @returns {PeerCertificate}
+	 * @returns {import("node:tls").PeerCertificate}
 	 */
-	getMTlsPeerCertificate: function() {
+	get mTlsPeerCertificate() {
 		let retVal = undefined;
 		if (process.env.mTlsPeerCertificate) {
 			retVal = JSON.parse(process.env.mTlsPeerCertificate);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "sprucehttp_sjs",
-	"version": "1.0.12",
+	"version": "2.1.0",
 	"description": "A module for responding to requests within SpruceHTTP in an SJS file",
 	"main": "index.js",
 	"scripts": {
@@ -13,15 +13,15 @@
 		"spruce",
 		"sprucehttp"
 	],
-	"homepage": "https://stibarc.dev/spruce/",
+	"homepage": "https://sprucehttp.com/",
 	"bugs": {
-		"url": "https://stibarc.dev/spruce/reportbug/",
-		"email": "herronjo@stibarc.dev"
+		"url": "https://sprucehttp.com/reportbug/",
+		"email": "herronjo@sprucehttp.com"
 	},
 	"author": {
 		"name": "Joshua Herron",
-		"email": "herronjo@stibarc.dev",
-		"url": "https://stibarc.dev"
+		"email": "herronjo@sprucehttp.com",
+		"url": "https://sprucehttp.com"
 	},
 	"license": "Copyright (c) STiBaRC LLC. All rights reserved."
 }