web_plsql 0.15.1 → 0.16.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "web_plsql",
-	"version": "0.15.1",
+	"version": "0.16.1",
 	"author": "Dieter Oberkofler <dieter.oberkofler@gmail.com>",
 	"license": "MIT",
 	"description": "The Express Middleware for Oracle PL/SQL",
@@ -60,8 +60,7 @@
 		"compression": "1.8.1",
 		"cookie-parser": "1.4.7",
 		"debug": "4.4.3",
-		"escape-html": "1.0.3",
-		"express": "5.1.0",
+		"express": "5.2.1",
 		"fs-extra": "11.3.2",
 		"http-parser-js": "0.5.10",
 		"morgan": "1.10.1",
@@ -74,19 +73,18 @@
 		"@types/compression": "1.8.1",
 		"@types/cookie-parser": "1.4.10",
 		"@types/debug": "4.1.12",
-		"@types/escape-html": "1.0.4",
 		"@types/fs-extra": "11.0.4",
 		"@types/morgan": "1.9.10",
 		"@types/multer": "2.0.0",
-		"@types/node": "24.10.1",
+		"@types/node": "24.10.2",
 		"@types/oracledb": "6.10.0",
 		"@types/supertest": "6.0.3",
 		"eslint": "9.39.1",
-		"eslint-plugin-jsdoc": "61.4.1",
-		"prettier": "3.7.1",
+		"eslint-plugin-jsdoc": "61.5.0",
+		"prettier": "3.7.4",
 		"shx": "0.4.0",
 		"supertest": "7.1.4",
 		"typescript": "5.9.3",
-		"typescript-eslint": "8.48.0"
+		"typescript-eslint": "8.49.0"
 	}
 }

package/src/handler/plsql/errorPage.js

@@ -2,12 +2,11 @@
  *	Error handling
  */
 
-import util from 'node:util';
-import escape from 'escape-html';
 import {ProcedureError} from './procedureError.js';
 import {RequestError} from './requestError.js';
-import {inspectRequest, logToFile} from '../../util/trace.js';
+import {getFormattedMessage, logToFile} from '../../util/trace.js';
 import {errorToString} from '../../util/errorToString.js';
+import {getHtmlPage} from '../../util/html.js';
 
 /**
  * @typedef {import('express').Request} Request
@@ -18,86 +17,6 @@ import {errorToString} from '../../util/errorToString.js';
  * @typedef {{html: string; text: string}} outputType
  */
 
-/**
- *	Convert value to string
- *	@param {unknown} value - The value to convert.
- *	@returns {string} - The string representation of the value.
- */
-const inspect = (value) => util.inspect(value, {showHidden: false, depth: null, colors: false});
-
-/**
- *	Convert LF and/or CR to <br>
- *	@param {string} text - The text to convert.
- *	@returns {string} - The converted text.
- */
-const convertToHtml = (text) => {
-	let html = escape(text);
-
-	html = html.replace(/(?:\r\n|\r|\n)/g, '<br />');
-	html = html.replace(/\t/g, '&nbsp;&nbsp;&nbsp;');
-
-	return html;
-};
-
-/**
- *	Get html
- *	@param {string} text - The text to convert.
- *	@returns {string} - The converted text.
- */
-const getHtml = (text) => `<p>${convertToHtml(text)}</p>`;
-
-/**
- *	Get text header
- *	@param {string} text - The text to convert.
- *	@returns {string} - The converted text.
- */
-const getHeaderText = (text) => `\n${text}\n${'='.repeat(text.length)}\n`;
-
-/**
- *	Get html header
- *	@param {string} text - The text to convert.
- *	@returns {string} - The converted text.
- */
-const getHeaderHtml = (text) => `<h1>${text}</h1>`;
-
-/**
- *	Get text
- *	@param {string} text - The text to convert.
- *	@returns {string} - The converted text.
- */
-const getText = (text) => `${text}\n`;
-
-/**
- * Get evnironment
- *	@param {outputType} output - The output.
- *	@param {environmentType} environment - The environment.
- */
-const getEnvironment = (output, environment) => {
-	let html = '<table>';
-	let text = '';
-
-	try {
-		for (const key in environment) {
-			html += `<tr><td>${key}:</td><td>${environment[key]}</td></tr>`;
-			text += `${key}=${environment[key]}\n`;
-		}
-	} catch (err) {
-		/* istanbul ignore next */
-		output.html += errorToString(err);
-
-		/* istanbul ignore next */
-		output.text += errorToString(err);
-
-		/* istanbul ignore next */
-		return;
-	}
-
-	html += '</table>';
-
-	output.html += html;
-	output.text += text;
-};
-
 /**
  *	Show an error page
  *	@param {Request} req - The req object represents the HTTP request.
@@ -111,8 +30,8 @@ const getError = (req, error) => {
 	let environment = null;
 	/** @type {string | null} */
 	let sql = null;
-	/** @type {BindParameterConfig} */
-	let bind = {};
+	/** @type {BindParameterConfig | null} */
+	let bind = null;
 
 	// what type of Error did we receive
 	if (error instanceof ProcedureError) {
@@ -143,113 +62,9 @@ const getError = (req, error) => {
 		}
 	}
 
-	/** @type {outputType} */
-	const output = {
-		html: '',
-		text: '',
-	};
-
-	// timestamp
-	let header = 'TIMESTAMP';
-	output.html += getHeaderHtml(header);
-	output.html += getHtml(timestamp.toUTCString());
-
-	// error
-	header = 'ERROR';
-	output.html += getHeaderHtml(header);
-	output.html += getHtml(message);
-	output.text += getHeaderText(header);
-	output.text += getText(message);
-
-	// request
-	header = 'REQUEST';
-	output.text += getHeaderText(header);
-	output.text += getText(inspectRequest(req));
-
-	// parameters
-	if (typeof sql === 'string' && bind) {
-		header = 'PROCEDURE';
-		output.html += getHeaderHtml(header);
-		output.text += getHeaderText(header);
-		getProcedure(output, sql, bind);
-	}
-
-	// environment
-	if (environment) {
-		header = 'ENVIRONMENT';
-		output.html += getHeaderHtml(header);
-		output.text += getHeaderText(header);
-		getEnvironment(output, environment);
-	}
-
-	return output;
+	return getFormattedMessage({type: 'error', timestamp, message, req, environment, sql, bind});
 };
 
-/**
- *	Get procedure
- *	@param {outputType} output - The output.
- *	@param {string} sql - The SQL to execute.
- *	@param {BindParameterConfig} bind - The bind parameters.
- */
-const getProcedure = (output, sql, bind) => {
-	let html = '<table>';
-	let text = '';
-
-	text += `PROCEDURE: ${sql}\n`;
-	html += `<tr><td>PROCEDURE:</td><td>${sql}</td></tr>`;
-
-	try {
-		/* istanbul ignore else */
-		for (const key in bind) {
-			const value = inspect(bind[key].val);
-
-			html += `<tr><td>${key}:</td><td>${value}</td></tr>`;
-			text += `${key}: ${value}\n`;
-		}
-	} catch (err) {
-		/* istanbul ignore next */
-		output.html += err instanceof Error ? err.toString() : 'ERROR';
-
-		/* istanbul ignore next */
-		output.text += err instanceof Error ? err.toString() : 'ERROR';
-		/* istanbul ignore next */
-		return;
-	}
-
-	html += '</table>';
-
-	output.html += html;
-	output.text += text;
-};
-
-/**
- *	getHtmlPage
- *	@param {string} body - The body.
- *	@returns {string} - The html page.
- */
-const getHtmlPage = (body) => `<!DOCTYPE html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<title>web_plsql error page</title>
-<style type="text/css">
-html {
-	font-family: monospace, sans-serif;
-	font-size: 12px;
-}
-h1 {
-	font-size: 16px;
-	padding: 2px;
-	background-color: #cc0000;
-}
-</style>
-</head>
-<body>
-${body}
-</body>
-</html>
-`;
-
 /**
  * Show an error page
  *
@@ -259,38 +74,19 @@ ${body}
  * @param {unknown} error - The error.
  */
 export const errorPage = (req, res, options, error) => {
-	let output = {
-		html: '',
-		text: '',
-	};
-
-	// get the error description
-	try {
-		output = getError(req, error);
-	} catch (err) {
-		/* istanbul ignore next */
-		const header = 'ERROR';
-
-		/* istanbul ignore next */
-		const message = errorToString(err);
-
-		/* istanbul ignore next */
-		output.html += getHeaderHtml(header) + getHtml(message);
-
-		/* istanbul ignore next */
-		output.text += getHeaderHtml(header) + getHtml(message);
-	}
+	// get error message
+	const {html, text} = getError(req, error);
 
 	// trace to file
-	logToFile(output.text);
+	logToFile(text);
 
 	// console
-	console.error(output.text);
+	console.error(text);
 
 	// show page
 	if (options.errorStyle === 'basic') {
 		res.status(404).send('Page not found');
 	} else {
-		res.status(404).send(getHtmlPage(output.html));
+		res.status(404).send(getHtmlPage(html));
 	}
 };

package/src/handler/plsql/handlerPlSql.js

@@ -37,7 +37,6 @@ const requestHandler = async (req, res, next, connectionPool, options) => {
 				debug(`Redirect to the url "${newUrl}"`);
 				res.redirect(newUrl);
 			} else {
-				/* istanbul ignore next */
 				errorPage(req, res, options, new RequestError('No procedure name given and no default page has been specified'));
 			}
 		} else {
@@ -45,7 +44,6 @@ const requestHandler = async (req, res, next, connectionPool, options) => {
 			await processRequest(req, res, options, connectionPool);
 		}
 	} catch (err) {
-		/* istanbul ignore next */
 		errorPage(req, res, options, err);
 	}
 };

package/src/handler/plsql/procedure.js

@@ -18,6 +18,7 @@ import {sendResponse} from './sendResponse.js';
 import {ProcedureError} from './procedureError.js';
 import {inspect, getBlock} from '../../util/trace.js';
 import {errorToString} from '../../util/errorToString.js';
+import {sanitizeProcName} from './procedureSanitize.js';
 
 /**
  * @typedef {import('express').Request} Request
@@ -75,13 +76,15 @@ END;
 
 /**
  *	Get the procedure and arguments to execute
+ *	@param {Request} req - The req object represents the HTTP request. (only used for debugging)
  *	@param {string} procName - The procedure to execute
  *	@param {argObjType} argObj - The arguments to pass to the procedure
  *	@param {configPlSqlHandlerType} options - The options for the middleware
  *	@param {Connection} databaseConnection - The database connection
  *	@returns {Promise<{sql: string; bind: BindParameterConfig}>} - The SQL statement and bindings for the procedure to execute
  */
-const getProcedure = async (procName, argObj, options, databaseConnection) => {
+const getProcedure = async (req, procName, argObj, options, databaseConnection) => {
+	// path alias
 	if (options.pathAlias && options.pathAlias.toLowerCase() === procName.toLowerCase()) {
 		debug(`getProcedure: path alias "${options.pathAlias}" redirects to "${options.pathAliasProcedure}"`);
 		return {
@@ -90,11 +93,20 @@ const getProcedure = async (procName, argObj, options, databaseConnection) => {
 				p_path: {dir: oracledb.BIND_IN, type: oracledb.STRING, val: procName},
 			},
 		};
-	} else if (procName.startsWith('!')) {
-		return await getProcedureVariable(procName.substring(1), argObj, databaseConnection, options);
 	}
 
-	return await getProcedureNamed(procName, argObj, databaseConnection, options);
+	// check if we use variable arguments
+	const useVariableArguments = procName.startsWith('!');
+
+	// sanitize procedure name
+	const sanitizedProcName = await sanitizeProcName(useVariableArguments ? procName.substring(1) : procName, databaseConnection, options);
+
+	// run procedure
+	if (useVariableArguments) {
+		return getProcedureVariable(req, sanitizedProcName, argObj);
+	} else {
+		return await getProcedureNamed(req, sanitizedProcName, argObj, databaseConnection);
+	}
 };
 
 /**
@@ -133,7 +145,7 @@ export const invokeProcedure = async (req, res, argObj, cgiObj, filesToUpload, o
 	// 2) GET SQL STATEMENT AND ARGUMENTS
 	//
 
-	const para = await getProcedure(procName, argObj, options, databaseConnection);
+	const para = await getProcedure(req, procName, argObj, options, databaseConnection);
 
 	//
 	//	3) EXECUTE PROCEDURE

package/src/handler/plsql/procedureNamed.js

@@ -7,21 +7,21 @@ const debug = debugModule('webplsql:procedureNamed');
 
 import oracledb from 'oracledb';
 import z from 'zod';
-import {sanitizeProcName} from './procedureSanitize.js';
 import {RequestError} from './requestError.js';
 import {errorToString} from '../../util/errorToString.js';
+import {stringToNumber} from '../../util/util.js';
+import {toTable, warningMessage} from '../../util/trace.js';
 
 /**
- * @typedef {Record<string, string>} argsType
- * @typedef {{hitCount: number, args: argsType}} cacheEntryType
- */
-
-/**
+ * @typedef {import('express').Request} Request
  * @typedef {import('oracledb').Connection} Connection
  * @typedef {import('oracledb').Result<unknown>} Result
  * @typedef {import('../../types.js').configPlSqlHandlerType} configPlSqlHandlerType
  * @typedef {import('../../types.js').argObjType} argObjType
  * @typedef {import('../../types.js').BindParameterConfig} BindParameterConfig
+ * @typedef {import('../../types.js').BindParameter} BindParameter
+ * @typedef {Record<string, string>} argsType
+ * @typedef {{hitCount: number, args: argsType}} cacheEntryType
  */
 
 const SQL_GET_ARGUMENT = [
@@ -42,6 +42,24 @@ const SQL_GET_ARGUMENT = [
 	'END;',
 ].join('\n');
 
+const DATA_TYPES = Object.freeze({
+	VARCHAR2: 'VARCHAR2',
+	CHAR: 'CHAR',
+	BINARY_INTEGER: 'BINARY_INTEGER',
+	NUMBER: 'NUMBER',
+	DATE: 'DATE',
+	CLOB: 'CLOB',
+	PL_SQL_TABLE: 'PL/SQL TABLE',
+	//	PL/SQL BOOLEAN
+	//	PL/SQL RECORD
+	//	OBJECT
+	//	TABLE
+	//	BLOB
+	//	RAW
+	//	VARRAY
+	//	REF CURSOR
+});
+
 // NOTE: Consider using a separate cache for each database pool to avoid possible conflicts.
 /** @type {Map<string, cacheEntryType>} */
 const ARGS_CACHE = new Map();
@@ -137,8 +155,6 @@ const removeLowestHitCountEntries = (count) => {
  *	@returns {Promise<argsType>} - The argument types
  */
 const findArguments = async (procedure, databaseConnection) => {
-	// calculate the key
-	//const key = `${databaseConnection.connectString}_${databaseConnection.user}_${procedure.toUpperCase()}`;
 	const key = procedure.toUpperCase();
 
 	// lookup in the cache
@@ -174,60 +190,113 @@ const findArguments = async (procedure, databaseConnection) => {
 };
 
 /**
- * Get the sql statement and bindings for the procedure to execute for a fixed number of arguments
- * @param {string} procName - The procedure to execute
- * @param {argObjType} argObj - The arguments to pass to the procedure
- * @param {Connection} databaseConnection - The database connection
- * @param {configPlSqlHandlerType} options - the options for the middleware.
- * @returns {Promise<{sql: string; bind: BindParameterConfig}>} - The SQL statement and bindings for the procedure to execute
+ *	Get the bindling for an argument.
+ *	@param {string} argName - The argument name.
+ *	@param {unknown} argValue - The argument value.
+ *	@param {string} argType - The argument type.
+ *	@returns {BindParameter} - The binding.
  */
-export const getProcedureNamed = async (procName, argObj, databaseConnection, options) => {
-	if (debug.enabled) {
-		debug(`getProcedureNamed: ${procName} arguments=`, argObj);
+export const getBinding = (argName, argValue, argType) => {
+	if (argType === DATA_TYPES.VARCHAR2 || argType === DATA_TYPES.CHAR) {
+		return {dir: oracledb.BIND_IN, type: oracledb.DB_TYPE_VARCHAR, val: argValue};
 	}
 
-	/** @type {BindParameterConfig} */
-	const bind = {};
-	let index = 0;
+	if (argType === DATA_TYPES.CLOB) {
+		return {dir: oracledb.BIND_IN, type: oracledb.DB_TYPE_CLOB, val: argValue};
+	}
 
-	const sanitizedProcName = await sanitizeProcName(procName, databaseConnection, options);
-	const argTypes = await findArguments(sanitizedProcName, databaseConnection);
+	if (argType === DATA_TYPES.NUMBER || argType === DATA_TYPES.BINARY_INTEGER) {
+		const value = stringToNumber(argValue);
+		if (value === null) {
+			throw new Error(`Error in named parameter "${argName}": invalid value "${argValue}" for type "${argType}"`);
+		}
+
+		return {dir: oracledb.BIND_IN, type: oracledb.DB_TYPE_NUMBER, val: value};
+	}
+
+	if (argType === DATA_TYPES.DATE) {
+		if (typeof argValue !== 'string') {
+			throw new Error(`Error in named parameter "${argName}": invalid value "${argValue}" for type "${argType}"`);
+		}
+		const value = new Date(argValue);
+		if (Number.isNaN(value.getTime())) {
+			throw new Error(`Error in named parameter "${argName}": invalid value "${argValue}" for type "${argType}"`);
+		}
+
+		return {dir: oracledb.BIND_IN, type: oracledb.DB_TYPE_VARCHAR, val: value};
+	}
+
+	if (argType === DATA_TYPES.PL_SQL_TABLE || Array.isArray(argValue)) {
+		const value = typeof argValue === 'string' ? [argValue] : argValue;
+
+		return {dir: oracledb.BIND_IN, type: oracledb.DB_TYPE_DATE, val: value};
+	}
+
+	throw new Error(`Error in named parameter "${argName}": invalid binding type "${argType}"`);
+};
+
+/**
+ *	Get binding table for tracing.
+ *	@param {argObjType} argObj - The arguments to pass to the procedure
+ *	@param {argsType} argTypes - The argument types.
+ *	@returns {string} - The text.
+ */
+const inspectBindings = (argObj, argTypes) => {
+	const rows = Object.entries(argObj).map(([key, value]) => {
+		return [key, value.toString(), typeof value, argTypes[key.toLowerCase()]];
+	});
+
+	const {text} = toTable(['id', 'value', 'value type', 'argument type'], rows);
+
+	return text;
+};
+
+/**
+ *	Get the sql statement and bindings for the procedure to execute for a fixed number of arguments
+ *	@param {Request} req - The req object represents the HTTP request. (only used for debugging)
+ *	@param {string} procName - The procedure to execute
+ *	@param {argObjType} argObj - The arguments to pass to the procedure
+ *	@param {Connection} databaseConnection - The database connection
+ *	@returns {Promise<{sql: string; bind: BindParameterConfig}>} - The SQL statement and bindings for the procedure to execute
+ */
+export const getProcedureNamed = async (req, procName, argObj, databaseConnection) => {
+	debug(`getProcedureNamed: ${procName} arguments=`, argObj);
+
+	// get the types of the arguments
+	const argTypes = await findArguments(procName, databaseConnection);
+
+	/** @type {string[]} */
+	const sqlParameter = [];
+
+	/** @type {BindParameterConfig} */
+	const bindings = {};
 
 	// bindings for the statement
-	let sql = `${sanitizedProcName}(`;
 	for (const key in argObj) {
-		const value = argObj[key];
 		const parameterName = `p_${key}`;
-
-		// prepend the separator, if this is not the first argument
-		if (index > 0) {
-			sql += ',';
-		}
-		index++;
-
-		// add the argument
-		sql += `${key}=>:${parameterName}`;
-
-		// add the binding
-		bind[parameterName] = {dir: oracledb.BIND_IN, type: oracledb.STRING};
-
-		// set the value or array of values
-		if (Array.isArray(value) || argTypes[key] === 'PL/SQL TABLE') {
-			/** @type {string[]} */
-			const val = [];
-			if (typeof value === 'string') {
-				val.push(value);
-			} else {
-				value.forEach((element) => {
-					val.push(element);
-				});
-			}
-			bind[parameterName].val = val;
-		} else if (typeof value === 'string') {
-			bind[parameterName].val = value;
+		const argValue = argObj[key];
+		const argType = argTypes[key.toLowerCase()];
+		/** @type {BindParameter} */
+		let bind = {dir: oracledb.BIND_IN, type: oracledb.DB_TYPE_VARCHAR, val: argValue};
+
+		if (argType) {
+			bind = getBinding(key, argValue, argType);
+		} else {
+			const text = inspectBindings(argObj, argTypes);
+			warningMessage({type: 'warning', message: `Error in named parameter "${key}": invalid binding type "${argType}"\n\n${text}`, req});
 		}
+
+		sqlParameter.push(`${key}=>:${parameterName}`);
+		bindings[parameterName] = bind;
+	}
+
+	// select statement
+	const sql = `${procName}(${sqlParameter.join(', ')});`;
+
+	if (debug.enabled) {
+		debug(sql);
+		debug(inspectBindings(argObj, argTypes));
 	}
-	sql += ');';
 
-	return {sql, bind};
+	return {sql, bind: bindings};
 };

package/src/handler/plsql/procedureVariable.js

@@ -6,9 +6,9 @@ import debugModule from 'debug';
 const debug = debugModule('webplsql:procedureVariable');
 
 import oracledb from 'oracledb';
-import {sanitizeProcName} from './procedureSanitize.js';
 
 /**
+ * @typedef {import('express').Request} Request
  * @typedef {import('oracledb').Connection} Connection
  * @typedef {import('oracledb').Result<unknown>} Result
  * @typedef {import('../../types.js').configPlSqlHandlerType} configPlSqlHandlerType
@@ -17,14 +17,13 @@ import {sanitizeProcName} from './procedureSanitize.js';
  */
 
 /**
- * Get the sql statement and bindings for the procedure to execute for a variable number of arguments
- * @param {string} procName - The procedure to execute
- * @param {argObjType} argObj - The arguments to pass to the procedure
- * @param {Connection} databaseConnection - The database connection
- * @param {configPlSqlHandlerType} options - the options for the middleware.
- * @returns {Promise<{sql: string; bind: BindParameterConfig}>} - The SQL statement and bindings for the procedure to execute
+ *	Get the sql statement and bindings for the procedure to execute for a variable number of arguments
+ *	@param {Request} req - The req object represents the HTTP request. (only used for debugging)
+ *	@param {string} procName - The procedure to execute
+ *	@param {argObjType} argObj - The arguments to pass to the procedure
+ *	@returns {{sql: string; bind: BindParameterConfig}} - The SQL statement and bindings for the procedure to execute
  */
-export const getProcedureVariable = async (procName, argObj, databaseConnection, options) => {
+export const getProcedureVariable = (req, procName, argObj) => {
 	if (debug.enabled) {
 		debug(`getProcedureVariable: ${procName} arguments=`, argObj);
 	}
@@ -45,10 +44,8 @@ export const getProcedureVariable = async (procName, argObj, databaseConnection,
 		}
 	}
 
-	const sanitizedProcName = await sanitizeProcName(procName, databaseConnection, options);
-
 	return {
-		sql: `${sanitizedProcName}(:argnames, :argvalues);`,
+		sql: `${procName}(:argnames, :argvalues);`,
 		bind: {
 			argnames: {dir: oracledb.BIND_IN, type: oracledb.STRING, val: names},
 			argvalues: {dir: oracledb.BIND_IN, type: oracledb.STRING, val: values},

package/src/server/version.js

@@ -2,4 +2,4 @@
  * Returns the current library version
  * @returns {string} - Version.
  */
-export const getVersion = () => '0.15.1';
+export const getVersion = () => '0.16.1';

package/src/util/html.js

@@ -0,0 +1,53 @@
+/*
+ *	Html utilities
+ */
+
+/**
+ * Escape html string.
+ *
+ * @param {string} value - The value.
+ * @returns {string} - The escaped value.
+ */
+export const escapeHtml = (value) => value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&#39;');
+
+/**
+ *	Convert LF and/or CR to <br>
+ *	@param {string} text - The text to convert.
+ *	@returns {string} - The converted text.
+ */
+export const convertAsciiToHtml = (text) => {
+	let html = escapeHtml(text);
+
+	html = html.replace(/(?:\r\n|\r|\n)/g, '<br />');
+	html = html.replace(/\t/g, '&nbsp;&nbsp;&nbsp;');
+
+	return html;
+};
+
+/**
+ *	get a minimal html page.
+ *	@param {string} body - The body.
+ *	@returns {string} - The html page.
+ */
+export const getHtmlPage = (body) => `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>web_plsql error page</title>
+<style type="text/css">
+html {
+	font-family: monospace, sans-serif;
+	font-size: 12px;
+}
+h1 {
+	font-size: 16px;
+	padding: 2px;
+	background-color: #cc0000;
+}
+</style>
+</head>
+<body>
+${body}
+</body>
+</html>
+`;

package/src/util/trace.js

@@ -5,6 +5,20 @@
 import * as rotatingFileStream from 'rotating-file-stream';
 import express from 'express';
 import util from 'node:util';
+import oracledb from 'oracledb';
+import {escapeHtml, convertAsciiToHtml} from './html.js';
+import {errorToString} from './errorToString.js';
+
+/**
+ * @typedef {import('express').Request} Request
+ * @typedef {import('../types.js').BindParameterConfig} BindParameterConfig
+ * @typedef {import('../types.js').environmentType} environmentType
+ * @typedef {{html: string; text: string}} outputType
+ * @typedef {{type: 'error' | 'warning' | 'trace'; message: string; timestamp?: Date | null; req?: Request | null; environment?: environmentType | null, sql?: string | null; bind?: BindParameterConfig | null}} messageType
+ */
+
+const SEPARATOR_H1 = '='.repeat(100);
+const SEPARATOR_H2 = '-'.repeat(30);
 
 /**
  * Return a string representation of the value.
@@ -13,7 +27,58 @@ import util from 'node:util';
  * @param {number | null} depth - Specifies the number of times to recurse while formatting object.
  * @returns {string} - The string representation.
  */
-export const inspect = (value, depth = null) => util.inspect(value, {showHidden: false, depth, colors: false});
+export const inspect = (value, depth = null) => {
+	try {
+		return util.inspect(value, {showHidden: false, depth, colors: false});
+	} catch (err) {
+		/* empty */
+	}
+
+	try {
+		return JSON.stringify(value);
+	} catch (err) {
+		/* empty */
+	}
+
+	return 'Unable to convert value to string';
+};
+
+/**
+ * Return a tabular representation of the values.
+ *
+ * @param {string[]} head - The header values.
+ * @param {string[][]} body - The row values.
+ * @returns {outputType} - The output.
+ */
+export const toTable = (head, body) => {
+	if (head.length === 0) {
+		throw new Error('head cannot be empty');
+	}
+
+	// Calculate column widths
+	const widths = head.map((h, i) => {
+		const bodyMax = Math.max(0, ...body.map((row) => (row[i] || '').length));
+		return Math.max(h.length, bodyMax);
+	});
+
+	// Build text representation
+	/**
+	 *	@param {string} cell - The string
+	 *	@param {number} width - The width
+	 *	@returns {string} - The result
+	 */
+	const padCell = (cell, width) => cell.padEnd(width, ' ');
+	const textHeader = head.map((h, i) => padCell(h, widths[i])).join(' | ');
+	const textSeparator = widths.map((w) => '-'.repeat(w)).join('-+-');
+	const textRows = body.map((row) => head.map((_, i) => padCell(row[i] || '', widths[i])).join(' | '));
+	const text = [textHeader, textSeparator, ...textRows].join('\n');
+
+	const htmlHead = head.map((h) => `<th>${escapeHtml(h)}</th>`).join('');
+	const htmlBody = body.map((row) => `<tr>${head.map((_, i) => `<td>${escapeHtml(row[i] || '')}</td>`).join('')}</tr>`).join('');
+	const html = `<table><thead><tr>${htmlHead}</tr></thead><tbody>${htmlBody}</tbody></table>`;
+
+	return {text, html};
+};
 
 /**
  * Log text to the console and to a file.
@@ -40,7 +105,7 @@ export const logToFile = (text) => {
  * @param {boolean} simple - Set to false to see all public properties of the request.
  * @returns {string} - The string representation.
  */
-export const inspectRequest = (req, simple = true) => {
+const inspectRequest = (req, simple = true) => {
 	/** @type {Record<string, unknown>} */
 	const requestData = {};
 
@@ -55,20 +120,206 @@ export const inspectRequest = (req, simple = true) => {
 	return inspect(requestData);
 };
 
+/**
+ *	Return a string representation of the bind parameter.
+ *	@param {number | undefined} dir - The direction.
+ *	@returns {string} The string.
+ */
+const dirToString = (dir) => {
+	switch (dir) {
+		case oracledb.BIND_IN:
+			return 'IN';
+		case oracledb.BIND_OUT:
+			return 'OUT';
+		case oracledb.BIND_INOUT:
+			return 'INOUT';
+		default:
+			return '';
+	}
+};
+
+/**
+ *	Return a string representation of the bind type.
+ *	@param {oracledb.DbType | string | number | undefined} type - The type.
+ *	@returns {string} The string.
+ */
+const bindTypeToString = (type) => {
+	if (typeof type === 'object' && 'name' in type) {
+		return type.name;
+	}
+
+	if (typeof type === 'string') {
+		return type;
+	}
+
+	if (typeof type === 'number') {
+		return type.toString();
+	}
+
+	return '';
+};
+
+/**
+ *	Return a string representation of the bind parameter.
+ *	@param {outputType} output - The output.
+ *	@param {BindParameterConfig} bind - The bind parameters.
+ *	@returns {undefined}
+ */
+const inspectBindParameter = (output, bind) => {
+	const rows = Object.entries(bind);
+
+	if (rows.length === 0) {
+		return;
+	}
+
+	const body = rows.map(([id, row]) => {
+		const dir = dirToString(row.dir);
+		const maxArraySize = row.maxArraySize ? row.maxArraySize.toString() : '';
+		const maxSize = row.maxSize ? row.maxSize.toString() : '';
+		const bindType = bindTypeToString(row.type);
+		const value = inspect(row.val);
+		const valueType = typeof row.val;
+
+		return [id, dir, maxArraySize, maxSize, bindType, value, valueType];
+	});
+
+	const {html, text} = toTable(['id', 'dir', 'maxArraySize', 'maxSize', 'bind type', 'value', 'value type'], body);
+
+	output.html += html;
+	output.text += text;
+};
+
+/**
+ * Add environment
+ *	@param {outputType} output - The output.
+ *	@param {environmentType} environment - The environment.
+ */
+const inspectEnvironment = (output, environment) => {
+	const rows = Object.entries(environment);
+
+	if (rows.length === 0) {
+		return;
+	}
+
+	const {html, text} = toTable(['key', 'value'], rows);
+
+	output.html += html;
+	output.text += text;
+};
+
 /**
  *	Get a block.
  *	@param {string} title - The name.
  *	@param {string} body - The name.
  *	@returns {string} - The text.
  */
-export const getBlock = (title, body) => {
-	const SEPARATOR = '-'.repeat(30);
+export const getBlock = (title, body) => `\n${SEPARATOR_H2}${title.toUpperCase()}${SEPARATOR_H2}\n${body}`;
+
+/**
+ *	Get line html
+ *	@param {string} text - The text.
+ *	@returns {string} - The line.
+ */
+const getLineHtml = (text) => `<p>${convertAsciiToHtml(text)}</p>`;
+
+/**
+ *	Get line text
+ *	@param {string} text - The text.
+ *	@returns {string} - The line.
+ */
+const getLineText = (text) => `${text}\n`;
+
+/**
+ *	Add line
+ *	@param {outputType} output - The output.
+ *	@param {string} text - The text to convert.
+ */
+const addLine = (output, text) => {
+	output.html += getLineHtml(text);
+	output.text += getLineText(text);
+};
+
+/**
+ *	Add header
+ *	@param {outputType} output - The output.
+ *	@param {string} text - The text to convert.
+ */
+const addHeader = (output, text) => {
+	output.html += `<h2>${text}</h2>`;
+	output.text += `\n${text}\n${'-'.repeat(text.length)}\n`;
+};
+
+/**
+ *	Add procedure
+ *	@param {outputType} output - The output.
+ *	@param {string} sql - The SQL to execute.
+ *	@param {BindParameterConfig} bind - The bind parameters.
+ */
+const addProcedure = (output, sql, bind) => {
+	output.html += `${sql}<br><br>`;
+	output.text += `${sql}\n\n`;
 
-	return `\n${SEPARATOR}${title.toUpperCase()}${SEPARATOR}\n${body}`;
+	try {
+		inspectBindParameter(output, bind);
+	} catch (err) {
+		addLine(output, `Unable to inspect bind parameter: ${errorToString(err)}`);
+	}
+
+	output.html += `<br>`;
+	output.text += `\n`;
 };
 
 /**
- *	Get a timestamp
- *	@returns {string} - The timestamp.
+ *	Get a formatted message.
+ *	@param {messageType} para - The req object represents the HTTP request.
+ *	@returns {outputType} - The output.
  */
-export const getTimestamp = () => new Date().toISOString();
+export const getFormattedMessage = (para) => {
+	const timestamp = para.timestamp ?? new Date();
+
+	// header
+	const url = typeof para.req?.originalUrl === 'string' && para.req.originalUrl.length > 0 ? ` on ${para.req.originalUrl}` : '';
+	const header = `${para.type.toUpperCase()} at ${timestamp.toUTCString()}${url}`;
+	const output = {
+		html: `<h1>${header}</h1>`,
+		text: `\n\n${SEPARATOR_H1}\n== ${header}\n${SEPARATOR_H1}\n`,
+	};
+
+	// error
+	addHeader(output, 'ERROR');
+	addLine(output, para.message);
+
+	// request
+	if (para.req) {
+		addHeader(output, 'REQUEST');
+		addLine(output, inspectRequest(para.req));
+	}
+
+	// parameters
+	if (para.sql && para.bind) {
+		addHeader(output, 'PROCEDURE');
+		addProcedure(output, para.sql, para.bind);
+	}
+
+	// environment
+	if (para.environment) {
+		addHeader(output, 'ENVIRONMENT');
+		inspectEnvironment(output, para.environment);
+	}
+
+	return output;
+};
+
+/**
+ *	Log a warning message.
+ *	@param {messageType} para - The req object represents the HTTP request.
+ */
+export const warningMessage = (para) => {
+	const {text} = getFormattedMessage(para);
+
+	// trace to file
+	logToFile(text);
+
+	// console
+	console.warn(text);
+};

package/src/util/util.js

@@ -0,0 +1,66 @@
+/**
+ * Get duration as human readable string.
+ * @param {number} duration - Milliseconds.
+ * @returns {string} String.
+ */
+export const humanDuration = (duration) => {
+	if (!Number.isFinite(duration)) return 'invalid';
+
+	const ms = Math.floor(duration % 1000);
+	const s = Math.floor((duration / 1000) % 60);
+	const m = Math.floor((duration / (1000 * 60)) % 60);
+	const h = Math.floor((duration / (1000 * 60 * 60)) % 24);
+	const d = Math.floor(duration / (1000 * 60 * 60 * 24));
+
+	const parts = [];
+	if (d) parts.push(`${d}d`);
+	if (h) parts.push(`${h}h`);
+	if (m) parts.push(`${m}m`);
+	if (s) parts.push(`${s}s`);
+	if (ms || !parts.length) parts.push(`${ms}ms`);
+
+	return parts.join(' ');
+};
+
+/**
+ * Convert a string to a number
+ *
+ * @param {unknown} value - The string to convert
+ * @returns {number | null} The number or null if the string could not be converted
+ */
+export const stringToNumber = (value) => {
+	// is the value already of type number?
+	if (typeof value === 'number') {
+		return !Number.isNaN(value) && Number.isFinite(value) ? value : null;
+	}
+
+	// Test for invalid characters
+	if (typeof value !== 'string' || !/^[+-]?(?:\d+(?:\.\d+)?|\.\d+)(?:E[+-]?\d+)?$/i.test(value)) {
+		return null;
+	}
+
+	// Convert value to a number
+	const num = Number(value);
+	return Number.isNaN(num) ? null : num;
+};
+
+/**
+ * Convert a string to a integer
+ *
+ * @param {unknown} value - The value to convert
+ * @returns {number | null} The integer or null if the string could not be converted
+ */
+export const stringToInteger = (value) => {
+	// is the value already a "real" integer, we just return the value
+	if (typeof value === 'number' && Number.isInteger(value)) {
+		return value;
+	}
+
+	// try to convert value to a number
+	const num = stringToNumber(value);
+	if (num === null || !Number.isInteger(num)) {
+		return null;
+	}
+
+	return num;
+};

package/types/handler/plsql/procedureNamed.d.ts

@@ -1,14 +1,17 @@
-export function getProcedureNamed(procName: string, argObj: argObjType, databaseConnection: Connection, options: configPlSqlHandlerType): Promise<{
+export function getBinding(argName: string, argValue: unknown, argType: string): BindParameter;
+export function getProcedureNamed(req: Request, procName: string, argObj: argObjType, databaseConnection: Connection): Promise<{
     sql: string;
     bind: BindParameterConfig;
 }>;
-export type argsType = Record<string, string>;
-export type cacheEntryType = {
-    hitCount: number;
-    args: argsType;
-};
+export type Request = import("express").Request;
 export type Connection = import("oracledb").Connection;
 export type Result = import("oracledb").Result<unknown>;
 export type configPlSqlHandlerType = import("../../types.js").configPlSqlHandlerType;
 export type argObjType = import("../../types.js").argObjType;
 export type BindParameterConfig = import("../../types.js").BindParameterConfig;
+export type BindParameter = import("../../types.js").BindParameter;
+export type argsType = Record<string, string>;
+export type cacheEntryType = {
+    hitCount: number;
+    args: argsType;
+};

package/types/handler/plsql/procedureVariable.d.ts

@@ -1,7 +1,8 @@
-export function getProcedureVariable(procName: string, argObj: argObjType, databaseConnection: Connection, options: configPlSqlHandlerType): Promise<{
+export function getProcedureVariable(req: Request, procName: string, argObj: argObjType): {
     sql: string;
     bind: BindParameterConfig;
-}>;
+};
+export type Request = import("express").Request;
 export type Connection = import("oracledb").Connection;
 export type Result = import("oracledb").Result<unknown>;
 export type configPlSqlHandlerType = import("../../types.js").configPlSqlHandlerType;

package/types/util/html.d.ts

@@ -0,0 +1,3 @@
+export function escapeHtml(value: string): string;
+export function convertAsciiToHtml(text: string): string;
+export function getHtmlPage(body: string): string;

package/types/util/trace.d.ts

@@ -1,6 +1,22 @@
 export function inspect(value: unknown, depth?: number | null): string;
+export function toTable(head: string[], body: string[][]): outputType;
 export function logToFile(text: string): void;
-export function inspectRequest(req: express.Request, simple?: boolean): string;
 export function getBlock(title: string, body: string): string;
-export function getTimestamp(): string;
-import express from 'express';
+export function getFormattedMessage(para: messageType): outputType;
+export function warningMessage(para: messageType): void;
+export type Request = import("express").Request;
+export type BindParameterConfig = import("../types.js").BindParameterConfig;
+export type environmentType = import("../types.js").environmentType;
+export type outputType = {
+    html: string;
+    text: string;
+};
+export type messageType = {
+    type: "error" | "warning" | "trace";
+    message: string;
+    timestamp?: Date | null;
+    req?: Request | null;
+    environment?: environmentType | null;
+    sql?: string | null;
+    bind?: BindParameterConfig | null;
+};

package/types/util/util.d.ts

@@ -0,0 +1,3 @@
+export function humanDuration(duration: number): string;
+export function stringToNumber(value: unknown): number | null;
+export function stringToInteger(value: unknown): number | null;

package/src/util/date.js

@@ -1,23 +0,0 @@
-/**
- * Get duration as human readable string.
- * @param {number} duration - Milliseconds.
- * @returns {string} String.
- */
-export const humanDuration = (duration) => {
-	if (!Number.isFinite(duration)) return 'invalid';
-
-	const ms = Math.floor(duration % 1000);
-	const s = Math.floor((duration / 1000) % 60);
-	const m = Math.floor((duration / (1000 * 60)) % 60);
-	const h = Math.floor((duration / (1000 * 60 * 60)) % 24);
-	const d = Math.floor(duration / (1000 * 60 * 60 * 24));
-
-	const parts = [];
-	if (d) parts.push(`${d}d`);
-	if (h) parts.push(`${h}h`);
-	if (m) parts.push(`${m}m`);
-	if (s) parts.push(`${s}s`);
-	if (ms || !parts.length) parts.push(`${ms}ms`);
-
-	return parts.join(' ');
-};