tiny-essentials 1.0.0

package/dist/legacy/http/HTTP-1.0.cjs

@@ -0,0 +1,151 @@
+'use strict';
+
+/**
+ * @module http_base
+ *
+ * HTTP status utility for sending standardized HTTP responses using Express.
+ * Includes a comprehensive list of HTTP status codes and helper methods for sending responses.
+ */
+
+const http_base = {
+  /**
+   * A list of standard HTTP status codes and their default messages.
+   * Follows the format { [statusCode]: message }.
+   *
+   * @readonly
+   * @type {Object<number, string>}
+   */
+  list: {
+    // Informational
+    100: 'Continue',
+    101: 'Switching Protocols',
+
+    // Successful
+    200: 'OK',
+    201: 'Created',
+    202: 'Accepted',
+    203: 'Non-Authoritative Information',
+    204: 'No Content',
+    205: 'Reset Content',
+    206: 'Partial Content',
+
+    // Redirection
+    300: 'Multiple Choices',
+    301: 'Moved Permanently',
+    302: 'Found',
+    303: 'See Other',
+    304: 'Not Modified',
+    305: 'Use Proxy',
+    306: 'Unused',
+    307: 'Temporary Redirect',
+
+    // Client Error
+    400: 'Bad Request',
+    401: 'Unauthorized',
+    402: 'Payment Required',
+    403: 'Forbidden',
+    404: 'Not Found',
+    405: 'Method Not Allowed',
+    406: 'Not Acceptable',
+    407: 'Proxy Authentication Required',
+    408: 'Request Timeout',
+    409: 'Conflict',
+    410: 'Gone',
+    411: 'Length Required',
+    412: 'Precondition Failed',
+    413: 'Request Entity Too Large',
+    414: 'Request-URI Too Long',
+    415: 'Unsupported Media Type',
+    416: 'Requested Range Not Satisfiable',
+    417: 'Expectation Failed',
+
+    // Server Error
+    500: 'Internal Server Error',
+    501: 'Not Implemented',
+    502: 'Bad Gateway',
+    503: 'Service Unavailable',
+    504: 'Gateway Timeout',
+    505: 'HTTP Version Not Supported',
+  },
+
+  /**
+   * Sends an HTTP response with the given status code.
+   * If a callback is provided, it will be called instead of sending an empty response.
+   *
+   * @function send
+   * @param {import('express').Response} res - Express response object.
+   * @param {number} http_code - HTTP status code to send.
+   * @param {function(number): void} [callback] - Optional callback to handle response body manually.
+   *
+   * @returns {*} The result of `res.send()` or the callback function.
+   *
+   * @example
+   * http_base.send(res, 404); // Sends 404 Not Found with empty body
+   */
+  send: function (res, http_code, callback) {
+    // Exist Error Code?
+    if (typeof http_code === 'number' && typeof http_base.list[http_code] === 'string') {
+      // Set HTTP Code
+      res.status(http_code);
+      res.header(`HTTP/1.0 ${http_code} ${http_base.list[http_code]}`);
+
+      // Send Page
+      if (typeof callback !== 'function') {
+        return res.send('');
+      }
+
+      // Nope
+      else {
+        return callback(http_code);
+      }
+    }
+
+    // Nope
+    else {
+      return res.send('');
+    }
+  },
+
+  /**
+   * Asynchronously sends an HTTP response with the given status code.
+   * Awaits the provided callback before completing.
+   *
+   * @function sendAsync
+   * @param {import('express').Response} res - Express response object.
+   * @param {number} http_code - HTTP status code to send.
+   * @param {function(number): Promise<any>} [callback] - Optional async callback to handle response.
+   *
+   * @returns {Promise<any>} The result of the async callback or the empty response.
+   *
+   * @example
+   * await http_base.sendAsync(res, 500, async (code) => {
+   *   res.send('Server error occurred.');
+   * });
+   */
+  sendAsync: async function (res, http_code, callback) {
+    // Exist Error Code?
+    if (typeof http_code === 'number' && typeof http_base.list[http_code] === 'string') {
+      // Set HTTP Code
+      res.status(http_code);
+      res.header(`HTTP/1.0 ${http_code} ${http_base.list[http_code]}`);
+
+      // Send Page
+      if (typeof callback !== 'function') {
+        return res.send('');
+      }
+
+      // Nope
+      else {
+        const result = await callback(http_code);
+        return result;
+      }
+    }
+
+    // Nope
+    else {
+      return res.send('');
+    }
+  },
+};
+
+module.exports = http_base;

package/dist/legacy/http/HTTP-1.0.d.mts

@@ -0,0 +1,8 @@
+export default http_base;
+declare namespace http_base {
+    let list: {
+        [x: number]: string;
+    };
+    function send(res: import("express").Response, http_code: number, callback?: (arg0: number) => void): any;
+    function sendAsync(res: import("express").Response, http_code: number, callback?: (arg0: number) => Promise<any>): Promise<any>;
+}

package/dist/legacy/http/HTTP-1.0.mjs

@@ -0,0 +1,136 @@
+/**
+ * @module http_base
+ *
+ * HTTP status utility for sending standardized HTTP responses using Express.
+ * Includes a comprehensive list of HTTP status codes and helper methods for sending responses.
+ */
+const http_base = {
+    /**
+     * A list of standard HTTP status codes and their default messages.
+     * Follows the format { [statusCode]: message }.
+     *
+     * @readonly
+     * @type {Object<number, string>}
+     */
+    list: {
+        // Informational
+        100: 'Continue',
+        101: 'Switching Protocols',
+        // Successful
+        200: 'OK',
+        201: 'Created',
+        202: 'Accepted',
+        203: 'Non-Authoritative Information',
+        204: 'No Content',
+        205: 'Reset Content',
+        206: 'Partial Content',
+        // Redirection
+        300: 'Multiple Choices',
+        301: 'Moved Permanently',
+        302: 'Found',
+        303: 'See Other',
+        304: 'Not Modified',
+        305: 'Use Proxy',
+        306: 'Unused',
+        307: 'Temporary Redirect',
+        // Client Error
+        400: 'Bad Request',
+        401: 'Unauthorized',
+        402: 'Payment Required',
+        403: 'Forbidden',
+        404: 'Not Found',
+        405: 'Method Not Allowed',
+        406: 'Not Acceptable',
+        407: 'Proxy Authentication Required',
+        408: 'Request Timeout',
+        409: 'Conflict',
+        410: 'Gone',
+        411: 'Length Required',
+        412: 'Precondition Failed',
+        413: 'Request Entity Too Large',
+        414: 'Request-URI Too Long',
+        415: 'Unsupported Media Type',
+        416: 'Requested Range Not Satisfiable',
+        417: 'Expectation Failed',
+        // Server Error
+        500: 'Internal Server Error',
+        501: 'Not Implemented',
+        502: 'Bad Gateway',
+        503: 'Service Unavailable',
+        504: 'Gateway Timeout',
+        505: 'HTTP Version Not Supported',
+    },
+    /**
+     * Sends an HTTP response with the given status code.
+     * If a callback is provided, it will be called instead of sending an empty response.
+     *
+     * @function send
+     * @param {import('express').Response} res - Express response object.
+     * @param {number} http_code - HTTP status code to send.
+     * @param {function(number): void} [callback] - Optional callback to handle response body manually.
+     *
+     * @returns {*} The result of `res.send()` or the callback function.
+     *
+     * @example
+     * http_base.send(res, 404); // Sends 404 Not Found with empty body
+     */
+    send: function (res, http_code, callback) {
+        // Exist Error Code?
+        if (typeof http_code === 'number' && typeof http_base.list[http_code] === 'string') {
+            // Set HTTP Code
+            res.status(http_code);
+            res.header(`HTTP/1.0 ${http_code} ${http_base.list[http_code]}`);
+            // Send Page
+            if (typeof callback !== 'function') {
+                return res.send('');
+            }
+            // Nope
+            else {
+                return callback(http_code);
+            }
+        }
+        // Nope
+        else {
+            return res.send('');
+        }
+    },
+    /**
+     * Asynchronously sends an HTTP response with the given status code.
+     * Awaits the provided callback before completing.
+     *
+     * @function sendAsync
+     * @param {import('express').Response} res - Express response object.
+     * @param {number} http_code - HTTP status code to send.
+     * @param {function(number): Promise<any>} [callback] - Optional async callback to handle response.
+     *
+     * @returns {Promise<any>} The result of the async callback or the empty response.
+     *
+     * @example
+     * await http_base.sendAsync(res, 500, async (code) => {
+     *   res.send('Server error occurred.');
+     * });
+     */
+    sendAsync: async function (res, http_code, callback) {
+        // Exist Error Code?
+        if (typeof http_code === 'number' && typeof http_base.list[http_code] === 'string') {
+            // Set HTTP Code
+            res.status(http_code);
+            res.header(`HTTP/1.0 ${http_code} ${http_base.list[http_code]}`);
+            // Send Page
+            if (typeof callback !== 'function') {
+                return res.send('');
+            }
+            // Nope
+            else {
+                const result = await callback(http_code);
+                return result;
+            }
+        }
+        // Nope
+        else {
+            return res.send('');
+        }
+    },
+};
+// Module
+export default http_base;

package/dist/legacy/http/auth.cjs

@@ -0,0 +1,70 @@
+'use strict';
+
+/**
+ * Creates an Express middleware for Basic HTTP Authentication.
+ *
+ * This middleware checks for an `Authorization` header and validates
+ * the username and password using base64-decoded credentials.
+ *
+ * If the credentials match, `next()` is called to proceed to the next middleware.
+ * If the credentials are invalid or missing, a 401 Unauthorized response is sent.
+ *
+ * @function auth
+ * @param {Object} data - Configuration object.
+ * @param {string} data.login - The expected username.
+ * @param {string} data.password - The expected password.
+ * @param {Function} [data.customError] - Optional function `(req, res) => {}` called on auth failure.
+ * @param {Function} [callback] - Optional fallback function `(req, res, next) => {}` executed after customError.
+ *
+ * @returns {Function} Express middleware function.
+ *
+ * @example
+ * import express from 'express';
+ * import auth from './auth.mjs';
+ *
+ * const app = express();
+ *
+ * app.use(auth({
+ *   login: 'admin',
+ *   password: '1234',
+ *   customError: (req, res) => {
+ *     res.send('Custom unauthorized message');
+ *   }
+ * }));
+ *
+ * app.get('/', (req, res) => {
+ *   res.send('Hello, authenticated user!');
+ * });
+ */
+function auth(data, callback) {
+  // Simple Basic Auth with vanilla JavaScript (ES6)
+  // https://stackoverflow.com/questions/23616371/basic-http-authentication-with-node-and-express-4
+  return async (req, res, next) => {
+    // -----------------------------------------------------------------------
+    // authentication middleware
+
+    const auth = { login: data.login, password: data.password };
+
+    // Parse credentials from Authorization header
+    const b64auth = (req.headers.authorization || '').split(' ')[1] || '';
+    const [login, password] = Buffer.from(b64auth, 'base64').toString().split(':');
+
+    // Check credentials
+    if (login && password && login === auth.login && password === auth.password) {
+      return next(); // Access granted
+    }
+
+    // Access denied
+    res.set('WWW-Authenticate', 'Basic realm="401"');
+    res.status(401);
+    if (typeof data.customError === 'function') await data.customError(req, res);
+
+    // Optional fallback
+    if (typeof callback === 'function') return callback(req, res, next);
+    else res.send('');
+
+    // -----------------------------------------------------------------------
+  };
+}
+
+module.exports = auth;

package/dist/legacy/http/auth.d.mts

@@ -0,0 +1,41 @@
+/**
+ * Creates an Express middleware for Basic HTTP Authentication.
+ *
+ * This middleware checks for an `Authorization` header and validates
+ * the username and password using base64-decoded credentials.
+ *
+ * If the credentials match, `next()` is called to proceed to the next middleware.
+ * If the credentials are invalid or missing, a 401 Unauthorized response is sent.
+ *
+ * @function auth
+ * @param {Object} data - Configuration object.
+ * @param {string} data.login - The expected username.
+ * @param {string} data.password - The expected password.
+ * @param {Function} [data.customError] - Optional function `(req, res) => {}` called on auth failure.
+ * @param {Function} [callback] - Optional fallback function `(req, res, next) => {}` executed after customError.
+ *
+ * @returns {Function} Express middleware function.
+ *
+ * @example
+ * import express from 'express';
+ * import auth from './auth.mjs';
+ *
+ * const app = express();
+ *
+ * app.use(auth({
+ *   login: 'admin',
+ *   password: '1234',
+ *   customError: (req, res) => {
+ *     res.send('Custom unauthorized message');
+ *   }
+ * }));
+ *
+ * app.get('/', (req, res) => {
+ *   res.send('Hello, authenticated user!');
+ * });
+ */
+export default function auth(data: {
+    login: string;
+    password: string;
+    customError?: Function | undefined;
+}, callback?: Function): Function;

package/dist/legacy/http/auth.mjs

@@ -0,0 +1,63 @@
+/**
+ * Creates an Express middleware for Basic HTTP Authentication.
+ *
+ * This middleware checks for an `Authorization` header and validates
+ * the username and password using base64-decoded credentials.
+ *
+ * If the credentials match, `next()` is called to proceed to the next middleware.
+ * If the credentials are invalid or missing, a 401 Unauthorized response is sent.
+ *
+ * @function auth
+ * @param {Object} data - Configuration object.
+ * @param {string} data.login - The expected username.
+ * @param {string} data.password - The expected password.
+ * @param {Function} [data.customError] - Optional function `(req, res) => {}` called on auth failure.
+ * @param {Function} [callback] - Optional fallback function `(req, res, next) => {}` executed after customError.
+ *
+ * @returns {Function} Express middleware function.
+ *
+ * @example
+ * import express from 'express';
+ * import auth from './auth.mjs';
+ *
+ * const app = express();
+ *
+ * app.use(auth({
+ *   login: 'admin',
+ *   password: '1234',
+ *   customError: (req, res) => {
+ *     res.send('Custom unauthorized message');
+ *   }
+ * }));
+ *
+ * app.get('/', (req, res) => {
+ *   res.send('Hello, authenticated user!');
+ * });
+ */
+export default function auth(data, callback) {
+    // Simple Basic Auth with vanilla JavaScript (ES6)
+    // https://stackoverflow.com/questions/23616371/basic-http-authentication-with-node-and-express-4
+    return async (req, res, next) => {
+        // -----------------------------------------------------------------------
+        // authentication middleware
+        const auth = { login: data.login, password: data.password };
+        // Parse credentials from Authorization header
+        const b64auth = (req.headers.authorization || '').split(' ')[1] || '';
+        const [login, password] = Buffer.from(b64auth, 'base64').toString().split(':');
+        // Check credentials
+        if (login && password && login === auth.login && password === auth.password) {
+            return next(); // Access granted
+        }
+        // Access denied
+        res.set('WWW-Authenticate', 'Basic realm="401"');
+        res.status(401);
+        if (typeof data.customError === 'function')
+            await data.customError(req, res);
+        // Optional fallback
+        if (typeof callback === 'function')
+            return callback(req, res, next);
+        else
+            res.send('');
+        // -----------------------------------------------------------------------
+    };
+}

package/dist/legacy/http/check_domain.cjs

@@ -0,0 +1,84 @@
+'use strict';
+
+/**
+ * @module check_domain
+ *
+ * Utility module to validate or retrieve the domain from a request object.
+ * It supports multiple methods to check the domain, including:
+ * - `x-forwarded-host`
+ * - `req.hostname`
+ * - `req.headers.host`
+ *
+ * Can be used to check if the incoming request matches a specific domain or to
+ * simply retrieve the current domain of the request.
+ */
+const check_domain = {
+  /**
+   * A list of domain validators using different request properties.
+   *
+   * Each validator includes a `type` and a `callback` function that checks or returns the domain.
+   * If a domain (`the_domain`) is passed, the function returns a boolean.
+   * If not, it returns the found domain string or `null`.
+   *
+   * @type {Array<{type: string, callback: function(req: Object, the_domain?: string): (boolean|string|null)}>}
+   */
+  validators: [
+    {
+      type: 'x-forwarded-host',
+      callback: function (req, the_domain) {
+        const isString = typeof req.headers['x-forwarded-host'] === 'string';
+        if (the_domain) return isString && req.headers['x-forwarded-host'] === the_domain;
+
+        return isString ? req.headers['x-forwarded-host'] : null;
+      },
+    },
+    {
+      type: 'hostname',
+      callback: function (req, the_domain) {
+        const isString = typeof req.hostname === 'string';
+        if (the_domain) return isString && req.hostname === the_domain;
+
+        return isString ? req.hostname : null;
+      },
+    },
+    {
+      type: 'hostname',
+      callback: function (req, the_domain) {
+        const isString = typeof req.headers.host === 'string';
+        if (the_domain) return isString && req.headers.host === the_domain;
+        return isString ? req.headers.host : null;
+      },
+    },
+  ],
+
+  /**
+   * Validates the request against a given domain using all available validators.
+   *
+   * @function
+   * @param {Object} req - The request object from Express.
+   * @param {string} the_domain - The domain to validate against.
+   * @returns {boolean} True if any validator matches the domain.
+   */
+  validator: function (req, the_domain) {
+    for (const item in check_domain.validators)
+      if (check_domain.validators[item].callback(req, the_domain)) return true;
+    return false;
+  },
+
+  /**
+   * Returns the domain found from the first valid source in the request object.
+   *
+   * @function
+   * @param {Object} req - The request object from Express.
+   * @returns {string|null} The found domain string or `null` if none matched.
+   */
+  get: function (req) {
+    for (const item in check_domain.validators) {
+      const result = check_domain.validators[item].callback(req);
+      if (result) return result;
+    }
+    return null;
+  },
+};
+
+module.exports = check_domain;

package/dist/legacy/http/check_domain.d.mts

@@ -0,0 +1,10 @@
+export default check_domain;
+declare namespace check_domain {
+    let validators: Array<{
+        type: string;
+        callback: (arg0: req) => Object;
+        the_domain?: string;
+    }>;
+    function validator(req: Object, the_domain: string): boolean;
+    function get(req: Object): string | null;
+}

package/dist/legacy/http/check_domain.mjs

@@ -0,0 +1,82 @@
+/**
+ * @module check_domain
+ *
+ * Utility module to validate or retrieve the domain from a request object.
+ * It supports multiple methods to check the domain, including:
+ * - `x-forwarded-host`
+ * - `req.hostname`
+ * - `req.headers.host`
+ *
+ * Can be used to check if the incoming request matches a specific domain or to
+ * simply retrieve the current domain of the request.
+ */
+const check_domain = {
+    /**
+     * A list of domain validators using different request properties.
+     *
+     * Each validator includes a `type` and a `callback` function that checks or returns the domain.
+     * If a domain (`the_domain`) is passed, the function returns a boolean.
+     * If not, it returns the found domain string or `null`.
+     *
+     * @type {Array<{type: string, callback: function(req: Object, the_domain?: string): (boolean|string|null)}>}
+     */
+    validators: [
+        {
+            type: 'x-forwarded-host',
+            callback: function (req, the_domain) {
+                const isString = typeof req.headers['x-forwarded-host'] === 'string';
+                if (the_domain)
+                    return isString && req.headers['x-forwarded-host'] === the_domain;
+                return isString ? req.headers['x-forwarded-host'] : null;
+            },
+        },
+        {
+            type: 'hostname',
+            callback: function (req, the_domain) {
+                const isString = typeof req.hostname === 'string';
+                if (the_domain)
+                    return isString && req.hostname === the_domain;
+                return isString ? req.hostname : null;
+            },
+        },
+        {
+            type: 'hostname',
+            callback: function (req, the_domain) {
+                const isString = typeof req.headers.host === 'string';
+                if (the_domain)
+                    return isString && req.headers.host === the_domain;
+                return isString ? req.headers.host : null;
+            },
+        },
+    ],
+    /**
+     * Validates the request against a given domain using all available validators.
+     *
+     * @function
+     * @param {Object} req - The request object from Express.
+     * @param {string} the_domain - The domain to validate against.
+     * @returns {boolean} True if any validator matches the domain.
+     */
+    validator: function (req, the_domain) {
+        for (const item in check_domain.validators)
+            if (check_domain.validators[item].callback(req, the_domain))
+                return true;
+        return false;
+    },
+    /**
+     * Returns the domain found from the first valid source in the request object.
+     *
+     * @function
+     * @param {Object} req - The request object from Express.
+     * @returns {string|null} The found domain string or `null` if none matched.
+     */
+    get: function (req) {
+        for (const item in check_domain.validators) {
+            const result = check_domain.validators[item].callback(req);
+            if (result)
+                return result;
+        }
+        return null;
+    },
+};
+export default check_domain;