web_plsql 1.0.0 → 1.3.0

package/src/util/trace.js

@@ -1,325 +0,0 @@
-/*
- *	Trace utilities
- */
-
-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.
- *
- * @param {unknown} value - Any value.
- * @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) => {
-	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] ?? 0)).join(' | ');
-	const textSeparator = widths.map((w) => '-'.repeat(w ?? 0)).join('-+-');
-	const textRows = body.map((row) => head.map((_, i) => padCell(row[i] ?? '', widths[i] ?? 0)).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.
- *
- * @param {string} text - Text to log.
- * @returns {void}
- */
-export const logToFile = (text) => {
-	const fs = rotatingFileStream.createStream('trace.log', {
-		size: '10M', // rotate every 10 MegaBytes written
-		interval: '1d', // rotate daily
-		maxFiles: 10, // maximum number of rotated files to keep
-		compress: 'gzip', // compress rotated files
-	});
-
-	fs.write(text);
-	fs.end();
-};
-
-/**
- * Return a string representation of the request.
- *
- * @param {express.Request} req - express.Request.
- * @param {boolean} simple - Set to false to see all public properties of the request.
- * @returns {string} - The string representation.
- */
-const inspectRequest = (req, simple = true) => {
-	/** @type {Record<string, unknown>} */
-	const requestData = {};
-
-	Object.keys(req)
-		.filter((prop) =>
-			simple ? ['originalUrl', 'params', 'query', 'url', 'method', 'body', 'files', 'secret', 'cookies'].includes(prop) : !prop.startsWith('_'),
-		)
-		.forEach((prop) => {
-			requestData[prop] = req[/** @type {keyof import('express').Request} */ (prop)];
-		});
-
-	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) => `\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`;
-
-	try {
-		inspectBindParameter(output, bind);
-	} catch (err) {
-		addLine(output, `Unable to inspect bind parameter: ${errorToString(err)}`);
-	}
-
-	output.html += `<br>`;
-	output.text += `\n`;
-};
-
-/**
- *	Get a formatted message.
- *	@param {messageType} para - The req object represents the HTTP request.
- *	@returns {outputType} - The output.
- */
-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/type.js

@@ -1,6 +0,0 @@
-/**
- *	Is the given value a string or an array of strings
- *	@param {unknown} value - The value to check.
- *	@returns {value is string | string[]} - True if the value is a string or an array of strings
- */
-export const isStringOrArrayOfString = (value) => typeof value === 'string' || (Array.isArray(value) && value.every((element) => typeof element === 'string'));

package/src/util/util.js

@@ -1,66 +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(' ');
-};
-
-/**
- * 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/src/version.js

@@ -1,5 +0,0 @@
-/**
- * Returns the current library version
- * @returns {string} - Version.
- */
-export const getVersion = () => '1.0.0';

package/types/handler/handlerAdmin.d.ts

@@ -1,9 +0,0 @@
-/**
- * @typedef {import('express').Request} Request
- * @typedef {import('express').Response} Response
- * @typedef {import('express').NextFunction} NextFunction
- */
-export const handlerAdmin: import("express-serve-static-core").Router;
-export type Request = import("express").Request;
-export type Response = import("express").Response;
-export type NextFunction = import("express").NextFunction;

package/types/handler/handlerLogger.d.ts

@@ -1,2 +0,0 @@
-export function handlerLogger(filename: string): RequestHandler;
-export type RequestHandler = import("express").RequestHandler;

package/types/handler/handlerMetrics.d.ts

@@ -1,25 +0,0 @@
-export function initMetrics(): metricsType;
-export function handlerMetrics(metrics: metricsType): RequestHandler;
-export type RequestHandler = import("express").RequestHandler;
-export type metricsType = {
-    /**
-     * - When was the server started.
-     */
-    started: Date;
-    /**
-     * - Total number of requests.
-     */
-    totalRequests: number;
-    /**
-     * - Total amount of time in ms in request.
-     */
-    totalRequestDuration: number;
-    /**
-     * - Min amount of time in ms in request.
-     */
-    minRequestDuration: number;
-    /**
-     * - Max amount of time in ms in request.
-     */
-    maxRequestDuration: number;
-};

package/types/handler/handlerUpload.d.ts

@@ -1,7 +0,0 @@
-export function handlerUpload(uploadFileSizeLimit?: number): RequestHandler;
-export type RequestHandler = import("express").RequestHandler;
-export type Response = import("express").Response;
-export type NextFunction = import("express").NextFunction;
-export type Pool = import("oracledb").Pool;
-export type environmentType = import("../types.js").environmentType;
-export type configType = import("../types.js").configType;

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

@@ -1,4 +0,0 @@
-export function getCGI(req: Request, doctable: string, cgi: environmentType): environmentType;
-export type Request = import("express").Request;
-export type environmentType = import("../../types.js").environmentType;
-export type configPlSqlType = import("../../types.js").configPlSqlType;

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

@@ -1,11 +0,0 @@
-export function errorPage(req: Request, res: Response, options: configPlSqlHandlerType, error: unknown): void;
-export type Request = import("express").Request;
-export type Response = import("express").Response;
-export type BindParameterConfig = import("../../types.js").BindParameterConfig;
-export type environmentType = import("../../types.js").environmentType;
-export type configPlSqlHandlerType = import("../../types.js").configPlSqlHandlerType;
-export type outputType = {
-    html: string;
-    text: string;
-};
-export type messageType = import("../../util/trace.js").messageType;

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

@@ -1,13 +0,0 @@
-export function handlerWebPlSql(connectionPool: Pool, config: configPlSqlHandlerType): WebPlSqlRequestHandler;
-export type RequestHandler = import("express").RequestHandler;
-export type Request = import("express").Request;
-export type Response = import("express").Response;
-export type NextFunction = import("express").NextFunction;
-export type Pool = import("oracledb").Pool;
-export type environmentType = import("../../types.js").environmentType;
-export type configPlSqlHandlerType = import("../../types.js").configPlSqlHandlerType;
-export type WebPlSqlRequestHandler = import("express").RequestHandler & {
-    procedureNameCache: Cache<string>;
-    argumentCache: Cache<import("./procedureNamed.js").argsType>;
-};
-import { Cache } from '../../util/cache.js';

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

@@ -1,3 +0,0 @@
-export function parsePage(text: string): pageType;
-export type pageType = import("../../types.js").pageType;
-export type cookieType = import("../../types.js").cookieType;

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

@@ -1,12 +0,0 @@
-export function invokeProcedure(req: Request, res: Response, argObj: argObjType, cgiObj: environmentType, filesToUpload: fileUploadType[], options: configPlSqlHandlerType, databaseConnection: Connection, procedureNameCache: ProcedureNameCache, argumentCache: ArgumentCache): Promise<void>;
-export type Request = import("express").Request;
-export type Response = import("express").Response;
-export type Connection = import("oracledb").Connection;
-export type Result = import("oracledb").Result<unknown>;
-export type argObjType = import("../../types.js").argObjType;
-export type fileUploadType = import("../../types.js").fileUploadType;
-export type environmentType = import("../../types.js").environmentType;
-export type configPlSqlHandlerType = import("../../types.js").configPlSqlHandlerType;
-export type BindParameterConfig = import("../../types.js").BindParameterConfig;
-export type ProcedureNameCache = import("../../util/cache.js").Cache<string>;
-export type ArgumentCache = import("../../util/cache.js").Cache<import("./procedureNamed.js").argsType>;

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

@@ -1,23 +0,0 @@
-/**
- * @typedef {import('../../types.js').environmentType} environmentType
- * @typedef {import('../../types.js').BindParameterConfig} BindParameterConfig
- */
-export class ProcedureError extends Error {
-    /**
-     * @param {string} message - The error message.
-     * @param {environmentType} environment - The environment.
-     * @param {string} sql - The SQL to execute.
-     * @param {BindParameterConfig} bind - The bind parameters.
-     */
-    constructor(message: string, environment: environmentType, sql: string, bind: BindParameterConfig);
-    /** @type {Date} */
-    timestamp: Date;
-    /** @type {environmentType} */
-    environment: environmentType;
-    /** @type {string} */
-    sql: string;
-    /** @type {BindParameterConfig} */
-    bind: BindParameterConfig;
-}
-export type environmentType = import("../../types.js").environmentType;
-export type BindParameterConfig = import("../../types.js").BindParameterConfig;

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

@@ -1,14 +0,0 @@
-export function getBinding(argName: string, argValue: unknown, argType: string): BindParameter;
-export function getProcedureNamed(req: Request, procName: string, argObj: argObjType, databaseConnection: Connection, argumentCache: ArgumentCache): Promise<{
-    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;
-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 ArgumentCache = import("../../util/cache.js").Cache<argsType>;

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

@@ -1,11 +0,0 @@
-export function sanitizeProcName(procName: string, databaseConnection: Connection, options: configPlSqlHandlerType, procedureNameCache: ProcedureNameCache): Promise<string>;
-export type Request = import("express").Request;
-export type Response = import("express").Response;
-export type Connection = import("oracledb").Connection;
-export type Result = import("oracledb").Result<unknown>;
-export type argObjType = import("../../types.js").argObjType;
-export type fileUploadType = import("../../types.js").fileUploadType;
-export type environmentType = import("../../types.js").environmentType;
-export type configPlSqlHandlerType = import("../../types.js").configPlSqlHandlerType;
-export type BindParameterConfig = import("../../types.js").BindParameterConfig;
-export type ProcedureNameCache = import("../../util/cache.js").Cache<string>;

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

@@ -1,10 +0,0 @@
-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;
-export type argObjType = import("../../types.js").argObjType;
-export type BindParameterConfig = import("../../types.js").BindParameterConfig;

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

@@ -1,9 +0,0 @@
-export function processRequest(req: Request, res: Response, options: configPlSqlHandlerType, connectionPool: Pool, procedureNameCache: ProcedureNameCache, argumentCache: ArgumentCache): Promise<void>;
-export type Request = import("express").Request;
-export type Response = import("express").Response;
-export type Pool = import("oracledb").Pool;
-export type Connection = import("oracledb").Connection;
-export type argObjType = import("../../types.js").argObjType;
-export type configPlSqlHandlerType = import("../../types.js").configPlSqlHandlerType;
-export type ProcedureNameCache = import("../../util/cache.js").Cache<string>;
-export type ArgumentCache = import("../../util/cache.js").Cache<import("./procedureNamed.js").argsType>;

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

@@ -1,8 +0,0 @@
-export class RequestError extends Error {
-    /**
-     * @param {string} message - The error message.
-     */
-    constructor(message: string);
-    /** @type {Date} */
-    timestamp: Date;
-}

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

@@ -1,6 +0,0 @@
-export function sendResponse(_req: Request, res: Response, page: pageType): Promise<void>;
-export type Request = import("express").Request;
-export type Response = import("express").Response;
-export type CookieOptions = import("express").CookieOptions;
-export type pageType = import("../../types.js").pageType;
-export type cookieType = import("../../types.js").cookieType;

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

@@ -1,5 +0,0 @@
-export function getFiles(req: Request): fileUploadType[];
-export function uploadFile(file: fileUploadType, doctable: string, databaseConnection: Connection): Promise<void>;
-export type Request = import("express").Request;
-export type Connection = import("oracledb").Connection;
-export type fileUploadType = import("../../types.js").fileUploadType;

package/types/index.d.ts

@@ -1,11 +0,0 @@
-export { oracledb };
-export { getVersion } from "./version.js";
-export * from "./util/shutdown.js";
-export * from "./util/oracle.js";
-export * from "./util/file.js";
-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";

package/types/server/config.d.ts

@@ -1,2 +0,0 @@
-export function showConfig(config: configType): void;
-export type configType = import("../types.js").configType;