web_plsql 0.16.1 → 0.17.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "web_plsql",
-	"version": "0.16.1",
+	"version": "0.17.1",
 	"author": "Dieter Oberkofler <dieter.oberkofler@gmail.com>",
 	"license": "MIT",
 	"description": "The Express Middleware for Oracle PL/SQL",
@@ -47,7 +47,8 @@
 		"test": "node --test --test-concurrency=1 \"./tests/**/*.test.js\"",
 		"types": "rm -rf types && tsc  --noEmit false --declaration true --declarationDir types --emitDeclarationOnly true --allowJs true --target es2020 --module es2020 --moduleResolution node --allowSyntheticDefaultImports true src/*.js",
 		"clean": "shx rm -f *.tgz && shx rm -f *.log",
-		"ci": "npm run clean && npm run lint && npm run test && npm run types",
+		"ci": "npm run clean && npm run version && npm run lint && npm run test && npm run types",
+		"version": "node update-version.js",
 		"create-package": "shx rm -f *.tgz && npm pack",
 		"image-build": "docker build --no-cache --progress=plain --tag=web_plsql .",
 		"image-save": "docker save web_plsql | gzip > web_plsql.tar.gz"
@@ -56,35 +57,32 @@
 		"oracledb": "6.10.0"
 	},
 	"dependencies": {
-		"basic-auth": "2.0.1",
 		"compression": "1.8.1",
 		"cookie-parser": "1.4.7",
 		"debug": "4.4.3",
 		"express": "5.2.1",
-		"fs-extra": "11.3.2",
 		"http-parser-js": "0.5.10",
 		"morgan": "1.10.1",
 		"multer": "2.0.2",
-		"rotating-file-stream": "3.2.7",
-		"zod": "4.1.13"
+		"rotating-file-stream": "3.2.8",
+		"zod": "4.3.6"
 	},
 	"devDependencies": {
-		"@types/basic-auth": "1.1.8",
 		"@types/compression": "1.8.1",
 		"@types/cookie-parser": "1.4.10",
 		"@types/debug": "4.1.12",
-		"@types/fs-extra": "11.0.4",
 		"@types/morgan": "1.9.10",
 		"@types/multer": "2.0.0",
-		"@types/node": "24.10.2",
-		"@types/oracledb": "6.10.0",
+		"@types/node": "25.2.0",
+		"@types/oracledb": "6.10.1",
 		"@types/supertest": "6.0.3",
-		"eslint": "9.39.1",
-		"eslint-plugin-jsdoc": "61.5.0",
-		"prettier": "3.7.4",
+		"eslint": "9.39.2",
+		"eslint-plugin-jsdoc": "62.5.1",
+		"oracledb": "6.10.0",
+		"prettier": "3.8.1",
 		"shx": "0.4.0",
-		"supertest": "7.1.4",
+		"supertest": "7.2.2",
 		"typescript": "5.9.3",
-		"typescript-eslint": "8.49.0"
+		"typescript-eslint": "8.54.0"
 	}
 }

package/src/handler/plsql/cgi.js

@@ -109,7 +109,7 @@ export const getCGI = (req, doctable, cgi) => {
 	const CGI = {
 		SERVER_PORT: typeof req.socket.localPort === 'number' ? req.socket.localPort.toString() : '',
 		REQUEST_METHOD: req.method,
-		PATH_INFO: req.params.name,
+		PATH_INFO: Array.isArray(req.params.name) ? req.params.name[0] : req.params.name,
 		SCRIPT_NAME: PATH.script,
 		REMOTE_ADDR: (req.ip ?? '').replace('::ffff:', ''),
 		SERVER_PROTOCOL: `${PROTOCOL}/${req.httpVersion}`,

package/src/handler/plsql/procedure.js

@@ -32,48 +32,6 @@ import {sanitizeProcName} from './procedureSanitize.js';
  * @typedef {import('../../types.js').BindParameterConfig} BindParameterConfig
  */
 
-/**
- * Get the SQL statement to execute when a new procedure is invoked
- *
- * NOTE:
- * 	1) dbms_session.modify_package_state(dbms_session.reinitialize) is used to ensure a stateless environment by resetting package state (dbms_session.reset_package)
- *
- * @param {string} procedure - The procedure
- * @returns {string} - The SQL statement to execute
- */
-const getProcedureSQL = (procedure) => `
-DECLARE
-	l_file_type		VARCHAR2(32767);
-	l_file_size		INTEGER;
-	l_file_exists	INTEGER := 0;
-BEGIN
-	dbms_session.modify_package_state(dbms_session.reinitialize);
-	owa.init_cgi_env(:cgicount, :cginames, :cgivalues);
-	htp.init;
-	htp.HTBUF_LEN := :htbuflen;
-
-	BEGIN
-		${procedure}
-	EXCEPTION WHEN OTHERS THEN
-		raise_application_error(-20000, 'Error executing "${procedure}"', TRUE);
-	END;
-
-	IF (wpg_docload.is_file_download()) THEN
-		wpg_docload.get_download_file(l_file_type);
-		IF (l_file_type = 'B') THEN
-			l_file_exists := 1;
-			wpg_docload.get_download_blob(:fileBlob);
-			l_file_size := dbms_lob.getlength(:fileBlob);
-		END IF;
-	END IF;
-	:fileExist := l_file_exists;
-	:fileType := l_file_type;
-	:fileSize := l_file_size;
-
-	owa.get_page(thepage=>:lines, irows=>:irows);
-END;
-`;
-
 /**
  *	Get the procedure and arguments to execute
  *	@param {Request} req - The req object represents the HTTP request. (only used for debugging)
@@ -85,10 +43,10 @@ END;
  */
 const getProcedure = async (req, procName, argObj, options, databaseConnection) => {
 	// path alias
-	if (options.pathAlias && options.pathAlias.toLowerCase() === procName.toLowerCase()) {
+	if (options.pathAlias?.toLowerCase() === procName.toLowerCase()) {
 		debug(`getProcedure: path alias "${options.pathAlias}" redirects to "${options.pathAliasProcedure}"`);
 		return {
-			sql: `${options.pathAliasProcedure}(p_path=>:p_path);`,
+			sql: `${options.pathAliasProcedure}(p_path=>:p_path)`,
 			bind: {
 				p_path: {dir: oracledb.BIND_IN, type: oracledb.STRING, val: procName},
 			},
@@ -110,154 +68,241 @@ const getProcedure = async (req, procName, argObj, options, databaseConnection)
 };
 
 /**
- * Invoke the Oracle procedure and return the page content
+ * Prepare procedure
+ *
+ * NOTE:
+ * 	1) dbms_session.modify_package_state(dbms_session.reinitialize) is used to ensure a stateless environment by resetting package state (dbms_session.reset_package)
  *
- * @param {Request} req - The req object represents the HTTP request.
- * @param {Response} res - The res object represents the HTTP response that an Express app sends when it gets an HTTP request.
- * @param {argObjType} argObj - - The arguments of the procedure to invoke.
  * @param {environmentType} cgiObj - The cgi of the procedure to invoke.
- * @param {fileUploadType[]} filesToUpload - Array of files to be uploaded
- * @param {configPlSqlHandlerType} options - the options for the middleware.
  * @param {Connection} databaseConnection - Database connection.
- * @returns {Promise<void>} Promise resolving to the page content generated by the executed procedure
+ * @returns {Promise<void>} Promise resolving to void.
  */
-export const invokeProcedure = async (req, res, argObj, cgiObj, filesToUpload, options, databaseConnection) => {
-	debug('invokeProcedure: ENTER');
-
-	const procName = req.params.name;
+const procedurePrepare = async (cgiObj, databaseConnection) => {
+	let sqlStatement = 'BEGIN dbms_session.modify_package_state(dbms_session.reinitialize); END;';
+	try {
+		await databaseConnection.execute(sqlStatement);
+	} catch (err) {
+		throw new ProcedureError(`procedurePrepare: error when preparing procedure\n${errorToString(err)}`, cgiObj, sqlStatement, {});
+	}
 
-	//
-	// 1) UPLOAD FILES
-	//
+	// htbuf_len: reduce this limit based on your worst-case character size.
+	// For most character sets, this will be 2 bytes per character, so the limit would be 127.
+	// For UTF8 Unicode, it's 3 bytes per character, meaning the limit should be 85.
+	// For the newer AL32UTF8 Unicode, it's 4 bytes per character, and the limit should be 63.
+	sqlStatement = 'BEGIN owa.init_cgi_env(:cgicount, :cginames, :cgivalues); htp.init; htp.htbuf_len := 63; END;';
+	/** @type {BindParameterConfig} */
+	const bindParameter = {
+		cgicount: {dir: oracledb.BIND_IN, type: oracledb.NUMBER, val: Object.keys(cgiObj).length},
+		cginames: {dir: oracledb.BIND_IN, type: oracledb.STRING, val: Object.keys(cgiObj)},
+		cgivalues: {dir: oracledb.BIND_IN, type: oracledb.STRING, val: Object.values(cgiObj)},
+	};
+	try {
+		await databaseConnection.execute(sqlStatement, bindParameter);
+	} catch (err) {
+		throw new ProcedureError(`procedurePrepare: error when preparing procedure\n${errorToString(err)}`, cgiObj, sqlStatement, bindParameter);
+	}
+};
 
-	debug(`invokeProcedure: upload "${filesToUpload.length}" files`);
-	if (filesToUpload.length > 0) {
-		if (typeof options.documentTable === 'string' && options.documentTable.length > 0) {
-			const {documentTable} = options;
+/**
+ * Execute procedure
+ *
+ * @param {{sql: string; bind: BindParameterConfig}} para - The statement and binding to use when executing the procedure.
+ * @param {Connection} databaseConnection - Database connection.
+ * @returns {Promise<void>} Promise resolving to void.
+ */
+const procedureExecute = async (para, databaseConnection) => {
+	const sqlStatement = `BEGIN ${para.sql}; END;`;
 
-			await Promise.all(filesToUpload.map((file) => uploadFile(file, documentTable, databaseConnection)));
-		} else {
-			console.warn(`Unable to upload "${filesToUpload.length}" files because the option ""doctable" has not been defined`);
-		}
+	try {
+		await databaseConnection.execute(sqlStatement, para.bind);
+	} catch (err) {
+		throw new ProcedureError(`procedureExecute: error when executing procedure:\n${sqlStatement}\n${errorToString(err)}`, {}, para.sql, para.bind);
 	}
+};
 
-	//
-	// 2) GET SQL STATEMENT AND ARGUMENTS
-	//
+/**
+ * Get page from procedure
+ *
+ * @param {boolean} test - Test.
+ * @param {Connection} databaseConnection - Database connection.
+ * @returns {Promise<string>} Promise resolving to the returned page content.
+ */
+const procedureGetPage = async (test, databaseConnection) => {
+	const MAX_IROWS = 100000;
 
-	const para = await getProcedure(req, procName, argObj, options, databaseConnection);
+	/** @type {BindParameterConfig} */
+	const bindParameter = {
+		lines: {dir: oracledb.BIND_OUT, type: oracledb.STRING, maxArraySize: MAX_IROWS},
+		irows: {dir: oracledb.BIND_INOUT, type: oracledb.NUMBER, val: MAX_IROWS},
+	};
 
-	//
-	//	3) EXECUTE PROCEDURE
-	//
+	const sqlStatement = 'BEGIN owa.get_page(thepage=>:lines, irows=>:irows); END;';
 
-	const HTBUF_LEN = 63;
-	const MAX_IROWS = 100000;
+	/** @type {Result} */
+	let result = {};
+	try {
+		result = await databaseConnection.execute(sqlStatement, bindParameter);
+	} catch (err) {
+		if (debug.enabled) {
+			debug(getBlock('procedureGetPage: results', inspect(result)));
+		}
 
-	const cgi = {
-		keys: Object.keys(cgiObj),
-		values: Object.values(cgiObj),
-	};
+		throw new ProcedureError(`procedureGetPage: error when getting page returned by procedure\n${errorToString(err)}`, {}, sqlStatement, bindParameter);
+	}
 
-	const fileBlob = await databaseConnection.createLob(oracledb.BLOB);
+	const {lines, irows} = z.object({irows: z.number(), lines: z.array(z.string())}).parse(result.outBinds);
+
+	// Make sure that we have retrieved all the rows
+	if (irows > MAX_IROWS) {
+		/* istanbul ignore next */
+		throw new ProcedureError(`procedureGetPage: error when retrieving rows. irows="${irows}"`, {}, sqlStatement, bindParameter);
+	}
+
+	return lines.join('');
+};
 
+/**
+ * Download files from procedure
+ *
+ * @param {oracledb.Lob} fileBlob - The blob eventually containing the file.
+ * @param {Connection} databaseConnection - Database connection.
+ * @returns {Promise<{fileType: string, fileSize: number, fileBlob: stream.Readable | null}>} Promise resolving to the result.
+ */
+const procedureDownloadFiles = async (fileBlob, databaseConnection) => {
 	/** @type {BindParameterConfig} */
-	const bind = {
-		cgicount: {dir: oracledb.BIND_IN, type: oracledb.NUMBER, val: cgi.keys.length},
-		cginames: {dir: oracledb.BIND_IN, type: oracledb.STRING, val: cgi.keys},
-		cgivalues: {dir: oracledb.BIND_IN, type: oracledb.STRING, val: cgi.values},
-		htbuflen: {dir: oracledb.BIND_IN, type: oracledb.NUMBER, val: HTBUF_LEN},
-		fileExist: {dir: oracledb.BIND_OUT, type: oracledb.NUMBER},
+	const bindParameter = {
 		fileType: {dir: oracledb.BIND_OUT, type: oracledb.STRING},
 		fileSize: {dir: oracledb.BIND_OUT, type: oracledb.NUMBER},
 		fileBlob: {dir: oracledb.BIND_INOUT, type: oracledb.BLOB, val: fileBlob},
-		lines: {dir: oracledb.BIND_OUT, type: oracledb.STRING, maxSize: HTBUF_LEN * 2, maxArraySize: MAX_IROWS},
-		irows: {dir: oracledb.BIND_INOUT, type: oracledb.NUMBER, val: MAX_IROWS},
 	};
 
-	// execute procedure and retrieve page
-	const sqlStatement = getProcedureSQL(para.sql);
+	const sqlStatement = `
+DECLARE
+	l_file_type		VARCHAR2(32767)	:= '';
+	l_file_size		INTEGER			:= 0;
+BEGIN
+	IF (wpg_docload.is_file_download()) THEN
+		wpg_docload.get_download_file(l_file_type);
+		IF (l_file_type = 'B') THEN
+			wpg_docload.get_download_blob(:fileBlob);
+			l_file_size := dbms_lob.getlength(:fileBlob);
+		END IF;
+	END IF;
+	:fileType := l_file_type;
+	:fileSize := l_file_size;
+END;
+`;
+
 	/** @type {Result | null} */
 	let result = null;
-	const bindParams = Object.assign({}, bind, para.bind);
 	try {
-		if (debug.enabled) {
-			if (debug.enabled) {
-				debug(getBlock('execute', sqlStatement));
-				// NOTE: Because inspecting a BLOB value generates a craxy amount of text, we somply remove it.
-				const temp = Object.assign({}, bindParams);
-				delete temp.fileBlob.val;
-				debug(getBlock('bindParams', inspect(temp)));
-			}
-		}
-		result = await databaseConnection.execute(sqlStatement, bindParams);
+		result = await databaseConnection.execute(sqlStatement, bindParameter);
 	} catch (err) {
 		if (debug.enabled) {
-			debug(getBlock('results', inspect(result)));
+			debug(getBlock('procedureDownloadFiles: results', inspect(result)));
 		}
 
-		throw new ProcedureError(`Error when executing procedure\n${sqlStatement}\n${errorToString(err)}`, cgiObj, para.sql, para.bind);
+		throw new ProcedureError(`procedureDownloadFiles: error when downloading files\n${errorToString(err)}`, {}, sqlStatement, bindParameter);
 	}
 
-	//
-	//	4) PROCESS RESULTS
-	//
-
-	// validate results
-	const data = z
+	return z
 		.object({
-			irows: z.number(),
-			lines: z.array(z.string()),
-			fileExist: z.number(),
-			fileType: z.string().nullable(),
-			fileSize: z.number().nullable(),
+			fileType: z
+				.string()
+				.nullable()
+				.transform((val) => val ?? ''),
+			fileSize: z
+				.number()
+				.nullable()
+				.transform((val) => val ?? 0),
 			fileBlob: z.instanceof(stream.Readable).nullable(),
 		})
 		.parse(result.outBinds);
+};
 
-	if (debug.enabled) {
-		debug(getBlock('data', inspect(data)));
+/**
+ * Invoke the Oracle procedure and return the page content
+ *
+ * @param {Request} req - The req object represents the HTTP request.
+ * @param {Response} res - The res object represents the HTTP response that an Express app sends when it gets an HTTP request.
+ * @param {argObjType} argObj - - The arguments of the procedure to invoke.
+ * @param {environmentType} cgiObj - The cgi of the procedure to invoke.
+ * @param {fileUploadType[]} filesToUpload - Array of files to be uploaded
+ * @param {configPlSqlHandlerType} options - the options for the middleware.
+ * @param {Connection} databaseConnection - Database connection.
+ * @returns {Promise<void>} Promise resolving to the page content generated by the executed procedure
+ */
+export const invokeProcedure = async (req, res, argObj, cgiObj, filesToUpload, options, databaseConnection) => {
+	debug('invokeProcedure: begin');
+
+	// 1) upload files
+	debug(`invokeProcedure: upload "${filesToUpload.length}" files`);
+	if (filesToUpload.length > 0) {
+		if (typeof options.documentTable === 'string' && options.documentTable.length > 0) {
+			const {documentTable} = options;
+
+			await Promise.all(filesToUpload.map((file) => uploadFile(file, documentTable, databaseConnection)));
+		} else {
+			console.warn(`Unable to upload "${filesToUpload.length}" files because the option ""doctable" has not been defined`);
+		}
 	}
 
-	// Make sure that we have retrieved all the rows
-	if (data.irows > MAX_IROWS) {
-		/* istanbul ignore next */
-		throw new ProcedureError(`Error when retrieving rows. irows="${data.irows}"`, cgiObj, para.sql, para.bind);
+	// 2) get procedure to execute and the arguments
+
+	debug('invokeProcedure: get procedure to execute and the arguments');
+	const para = await getProcedure(req, Array.isArray(req.params.name) ? req.params.name[0] : req.params.name, argObj, options, databaseConnection);
+
+	// 3) prepare the session
+
+	debug('invokeProcedure: prepare the session');
+	await procedurePrepare(cgiObj, databaseConnection);
+
+	// 4) execute the procedure
+
+	debug('invokeProcedure: execute the session');
+	await procedureExecute(para, databaseConnection);
+
+	// 5) get the page returned from the procedure
+
+	debug('invokeProcedure: get the page returned from the procedure');
+	const lines = await procedureGetPage(true, databaseConnection);
+	if (debug.enabled) {
+		debug(getBlock('data', lines));
 	}
 
-	// combine page
-	const pageContent = data.lines.join('');
+	// 6) download files
+
+	debug('invokeProcedure: download files');
+	const fileBlob = await databaseConnection.createLob(oracledb.BLOB);
+	const fileDownload = await procedureDownloadFiles(fileBlob, databaseConnection);
+	if (debug.enabled) {
+		debug(getBlock('fileDownload', inspect({fileType: fileDownload.fileType, fileSize: fileDownload.fileSize})));
+	}
 
-	//
-	//	6) PARSE PAGE
-	//
+	// 7) parse the page
 
-	// parse what we received from PL/SQL
-	const pageComponents = parsePage(pageContent);
+	debug('invokeProcedure: parse the page');
+	const pageComponents = parsePage(lines);
 
 	// add "Server" header
 	pageComponents.head.server = cgiObj.SERVER_SOFTWARE;
 
 	// add file download information
-	if (data.fileExist === 1) {
-		pageComponents.file.fileType = data.fileType;
-		pageComponents.file.fileSize = data.fileSize;
-		if (data.fileBlob) {
-			pageComponents.file.fileBlob = await streamToBuffer(data.fileBlob);
-		}
+	if (fileDownload.fileType !== '' && fileDownload.fileSize > 0 && fileDownload.fileBlob !== null) {
+		pageComponents.file.fileType = fileDownload.fileType;
+		pageComponents.file.fileSize = fileDownload.fileSize;
+		pageComponents.file.fileBlob = await streamToBuffer(fileDownload.fileBlob);
 	}
 
-	//
-	//	5) SEND THE RESPONSE
-	//
+	// 8) send the page to browser
 
+	debug('invokeProcedure: send the page to browser');
 	sendResponse(req, res, pageComponents);
 
-	//
-	//	6) CLEANUP
-	//
+	// 9) cleanup
 
+	debug('invokeProcedure: cleanup');
 	fileBlob.destroy();
 
-	debug('invokeProcedure: EXIT');
+	debug('invokeProcedure: end');
 };

package/src/handler/plsql/procedureNamed.js

@@ -291,7 +291,7 @@ export const getProcedureNamed = async (req, procName, argObj, databaseConnectio
 	}
 
 	// select statement
-	const sql = `${procName}(${sqlParameter.join(', ')});`;
+	const sql = `${procName}(${sqlParameter.join(', ')})`;
 
 	if (debug.enabled) {
 		debug(sql);

package/src/handler/plsql/procedureVariable.js

@@ -45,7 +45,7 @@ export const getProcedureVariable = (req, procName, argObj) => {
 	}
 
 	return {
-		sql: `${procName}(: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/handler/plsql/request.js

@@ -33,6 +33,11 @@ import {isStringOrArrayOfString} from '../../util/type.js';
 export const processRequest = async (req, res, options, connectionPool) => {
 	debug('processRequest: ENTER');
 
+	//
+	if (Array.isArray(req.params.name)) {
+		console.warn(`processRequest: WARNING: the req.params.name is not a string but an array of string: ${req.params.name.join(',')}`);
+	}
+
 	// open database connection
 	const connection = await connectionPool.getConnection();
 
@@ -68,7 +73,7 @@ export const processRequest = async (req, res, options, connectionPool) => {
 		await connection.rollback();
 	} else if (typeof options.transactionMode === 'function') {
 		debug('transactionMode: callback');
-		const result = options.transactionMode(connection, req.params.name);
+		const result = options.transactionMode(connection, Array.isArray(req.params.name) ? req.params.name[0] : req.params.name);
 		debug('transactionMode: callback restult', result);
 		if (result && typeof result.then === 'function') {
 			await result;

package/src/index.js

@@ -1,5 +1,9 @@
+// libraries
+import oracledb from 'oracledb';
+export {oracledb};
+
 // server
-export {getVersion} from './server/version.js';
+export {getVersion} from './version.js';
 export {createServer, startServer, loadConfig, startServerConfig} from './server/server.js';
 export * from './util/shutdown.js';
 

package/src/server/config.js

@@ -1,4 +1,4 @@
-import {getVersion} from './version.js';
+import {getVersion} from '../version.js';
 
 /**
  * @typedef {import('../types.js').configType} configType

package/src/{server/version.js → version.js}

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

package/types/index.d.ts

@@ -1,4 +1,5 @@
-export { getVersion } from "./server/version.js";
+export { oracledb };
+export { getVersion } from "./version.js";
 export * from "./util/shutdown.js";
 export * from "./util/oracle.js";
 export * from "./util/file.js";
@@ -6,4 +7,5 @@ export { handlerWebPlSql } from "./handler/plsql/handlerPlSql.js";
 export { handlerLogger } from "./handler/handlerLogger.js";
 export { handlerUpload } from "./handler/handlerUpload.js";
 export { handlerMetrics } from "./handler/handlerMetrics.js";
+import oracledb from 'oracledb';
 export { createServer, startServer, loadConfig, startServerConfig } from "./server/server.js";