biscuits-send v1.0.3

responseHandler Module

This module provides a simple and efficient way to handle HTTP responses in a Node.js application. It handles various data types (e.g., JSON, plain text, binary) and manages headers, content types, and status codes automatically.

Installation

To use this module in your Node.js application, simply require it in your project:

const responseHandler = require('./responseHandler');

Usage

The responseHandler function is designed to be used within a server response flow. It accepts the following parameters:

responseHandler(res, code, data, headers);

Parameters:

res (required): The HTTP response object (res), which is passed into the request handler.

code (optional): The HTTP status code (default is 200).

data (optional): The response data, which can be a string, object, Buffer, or Stream (default is '').

headers (optional): An object containing additional headers to be set in the response.

Example Usage:

const http = require('http');
const responseHandler = require('./responseHandler');

const server = http.createServer((req, res) => {
  const data = { message: 'Hello, world!' };
  responseHandler(res, 200, data, { 'X-Custom-Header': 'Some Value' });
});

server.listen(3000, () => {
  console.log('Server is running on port 3000');
});

In this example:

The server responds with a JSON object.

The 200 status code is used.

A custom header X-Custom-Header is included.

Detailed Explanation

1. Validation of Status Code: The function checks if the provided status code is valid based on the STATUS_CODES from the built-in http module.

2. Headers Normalization: All headers are converted to lowercase keys to ensure consistency. This allows for case-insensitive access to headers.

3. Content-Type Handling:

If the data is a Promise, it waits for it to resolve.

If data is a Stream, it pipes the data directly to the response object.

If data is a Buffer or object, it appropriately sets the Content-Type header to application/octet-stream or application/json.

If the data is a string, it sets the Content-Type to text/plain by default.

4. Error Handling: If an error occurs while piping a Stream, the server responds with a 500 Internal Server Error message.

5. Content-Length Calculation: The Content-Length header is automatically calculated based on the data type:

If the data is a Buffer, its length is used.

If the data is a string or JSON, the byte length of the string is used.

6. Sending the Response: The function sets the appropriate status code, headers, and sends the response data using res.writeHead() and res.end().

Supported Data Types

Buffer: The data is assumed to be binary data and the Content-Type is set to application/octet-stream.

Object: The data is automatically serialized to JSON and the Content-Type is set to application/json;charset=utf-8.

String: The data is sent as plain text with Content-Type: text/plain.

Stream: If data is a stream, it is piped directly to the response.

Error Handling

If an invalid status code is provided, an error will be thrown:

throw new Error(`Invalid status code: ${code}`);

Additionally, if there is an error while piping the Stream, the response is set to 500 Internal Server Error.

License

MIT License. See the LICENSE file for more details.