sprucehttp_sjs 2.0.0 → 2.1.0

package/README.md

@@ -35,6 +35,8 @@ 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.
 ```
@@ -45,6 +47,8 @@ sjs.streamMode(); // Set the response to stream mode.
 
 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");
@@ -89,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!");
@@ -104,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
@@ -121,6 +131,8 @@ sjs.writeData("<h1>I'm <i>not</i> a teapot</h1>");
 ### ``siteConfig``:
 Returns the site-specific configuration set in your config file.
 
+Returns an object representing the site configuration.
+
 ```js
 console.log(sjs.siteConfig);
 /*

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() {
-		process.send({
-			type: "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.
+	 * @return {Promise<void>} A Promise that resolves when the server acknowledges the status line.
 	 */
 	writeStatusLine(statusCode, reasonPhrase) {
-		process.send({
-			type: "status",
-			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.
+	 * @return {Promise<void>} A Promise that resolves when the server acknowledges the header.
 	 */
 	writeHeader(name, value) {
-		process.send({
-			type: "header",
-			name,
-			value
+		return new Promise(function (resolve) {
+			process.send({
+				type: "header",
+				name,
+				value
+			}, resolve);
 		});
 	},
 
@@ -45,7 +54,8 @@ module.exports = {
 	 * 
 	 * When not in stream mode, the Content-Length header is automatically updated.
 	 * @param {string | Buffer} data The data to send.
-	 * @deprecated Use writeDataAsync instead. Data cannot be reliably sent synchronously.
+	 * @returns {void}
+	 * @deprecated Use writeDataAsync instead. Data cannot be reliably sent synchronously. Will be removed in a future major version.
 	 */
 	writeData(data) {
 		(async () => { await this.writeDataAsync(data); })();
@@ -54,8 +64,11 @@ module.exports = {
 	/**
 	 * 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(data) {
 		// eslint-disable-next-line no-async-promise-executor
@@ -86,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() {
-		process.send({
-			type: "clear"
+		return new Promise(function (resolve) {
+			process.send({
+				type: "clear"
+			}, resolve);
 		});
 	},
 
@@ -215,7 +231,7 @@ module.exports = {
 	/**
 	 * Returns details about the mTLS peer's certificate, if present.
 	 * 
-	 * @returns {PeerCertificate}
+	 * @returns {import("node:tls").PeerCertificate}
 	 */
 	get mTlsPeerCertificate() {
 		let retVal = undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "sprucehttp_sjs",
-	"version": "2.0.0",
+	"version": "2.1.0",
 	"description": "A module for responding to requests within SpruceHTTP in an SJS file",
 	"main": "index.js",
 	"scripts": {