web_plsql 0.5.1 → 0.6.0

package/src/trace.js

@@ -0,0 +1,74 @@
+/*
+ *	Trace utilities
+ */
+
+import * as rotatingFileStream from 'rotating-file-stream';
+import express from 'express';
+import util from 'node:util';
+
+/**
+ * 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) => util.inspect(value, {showHidden: false, depth, colors: false});
+
+/**
+ * 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.
+ */
+export 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);
+};
+
+/**
+ *	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);
+
+	return `\n${SEPARATOR}${title.toUpperCase()}${SEPARATOR}\n${body}`;
+};
+
+/**
+ *	Get a timestamp
+ *	@returns {string} - The timestamp.
+ */
+export const getTimestamp = () => new Date().toISOString();

package/src/tty.js

@@ -0,0 +1,48 @@
+/**
+ * Write to stdout.
+ * @param {string} text - text to write.
+ * @returns {void}
+ */
+export const write = (text) => {
+	if (process.stdout.isTTY) {
+		process.stdout.write(text);
+	}
+};
+
+/**
+ * Write to stdout with new line.
+ * @param {string} text - text to write.
+ * @returns {void}
+ */
+export const writeNewLine = (text = '') => {
+	if (process.stdout.isTTY) {
+		process.stdout.write(`${text}\n`);
+	}
+};
+
+/**
+ * Write to stdout after erasing line.
+ * @param {string} text - text to write.
+ * @returns {void}
+ */
+export const writeAfterEraseLine = (text) => {
+	if (process.stdout.isTTY) {
+		process.stdout.clearLine(0);
+		process.stdout.cursorTo(0);
+		process.stdout.write(text);
+	}
+};
+
+/**
+ * Write to stdout starting a column.
+ * @param {string} text - text to write.
+ * @param {number} column - column.
+ * @returns {void}
+ */
+export const writeStartingOnColumn = (text, column) => {
+	if (process.stdout.isTTY) {
+		process.stdout.cursorTo(column);
+		process.stdout.clearLine(1);
+		process.stdout.write(text);
+	}
+};

package/src/types.js

@@ -0,0 +1,146 @@
+import z from 'zod';
+
+/**
+ * @typedef {import('oracledb').BindParameter} BindParameter
+ */
+
+/**
+ * @typedef {'basic' | 'debug'} errorStyleType
+ */
+export const z$errorStyleType = z.enum(['basic', 'debug']);
+
+/**
+ * @typedef {object} configStaticType
+ * @property {string} route - The Static route path.
+ * @property {string} directoryPath - The Static directory.
+ */
+export const z$configStaticType = z
+	.object({
+		route: z.string(),
+		directoryPath: z.string(),
+	})
+	.strict();
+
+/**
+ * @typedef {object} configPlSqlHandlerType
+ * @property {string} defaultPage - The default page.
+ * @property {string} [pathAlias] - The path alias.
+ * @property {string} [pathAliasProcedure] - The path alias.
+ * @property {string} documentTable - The document table.
+ * @property {string[]} [exclusionList] - The exclusion list.
+ * @property {string} [requestValidationFunction] - The request validation function.
+ * @property {Record<string, string>} [cgi] - The additional CGI.
+ * @property {errorStyleType} errorStyle - The error style.
+ */
+export const z$configPlSqlHandlerType = z
+	.object({
+		defaultPage: z.string(),
+		pathAlias: z.string().optional(),
+		pathAliasProcedure: z.string().optional(),
+		documentTable: z.string(),
+		exclusionList: z.array(z.string()).optional(),
+		requestValidationFunction: z.string().optional(),
+		errorStyle: z$errorStyleType,
+	})
+	.strict();
+
+/**
+ * @typedef {object} configPlSqlConfigType
+ * @property {string} route - The PL/SQL route path.
+ * @property {string} user - The Oracle username.
+ * @property {string} password - The Oracle password.
+ * @property {string} connectString - The Oracle connect string.
+ */
+export const z$configPlSqlConfigType = z
+	.object({
+		route: z.string(),
+		user: z.string(),
+		password: z.string(),
+		connectString: z.string(),
+	})
+	.strict();
+
+/**
+ * @typedef {configPlSqlHandlerType & configPlSqlConfigType} configPlSqlType
+ */
+export const z$configPlSqlType = z$configPlSqlHandlerType.merge(z$configPlSqlConfigType);
+
+/**
+ * @typedef {object} configType
+ * @property {number} port - The server port number.
+ * @property {configStaticType[]} routeStatic - The static routes.
+ * @property {configPlSqlType[]} routePlSql - The PL/SQL routes.
+ * @property {string} loggerFilename - name of the request logger filename or '' if not required.
+ * @property {boolean} monitorConsole - Enable console status monitor.
+ */
+export const z$configType = z
+	.object({
+		port: z.number(),
+		routeStatic: z.array(z$configStaticType),
+		routePlSql: z.array(z$configPlSqlType),
+		loggerFilename: z.string(),
+		monitorConsole: z.boolean(),
+	})
+	.strict();
+
+/**
+ * Environment variables as string key-value pairs
+ * @typedef {Record<string, string>} environmentType
+ */
+
+/**
+ * Oracle database bind parameter configuration
+ * @typedef {Record<string, BindParameter>} BindParameterConfig
+ */
+
+/**
+ * Arguments object with string or string array values
+ * @typedef {Record<string, string | string[]>} argObjType
+ */
+
+/**
+ * File upload metadata
+ * @typedef {object} fileUploadType
+ * @property {string} fieldname - The field value.
+ * @property {string} originalname - The filename.
+ * @property {string} encoding - The encoding.
+ * @property {string} mimetype - The mimetype.
+ * @property {string} filename - The filename.
+ * @property {string} path - The path.
+ * @property {number} size - The size.
+ */
+
+/**
+ * @typedef {object} cookieType
+ * @property {string} name - The name of the cookie.
+ * @property {string} value - The value of the cookie.
+ * @property {string} [path] - The path of the cookie.
+ * @property {string} [domain] - The domain of the cookie.
+ * @property {string} [secure] - The secure flag.
+ * @property {Date} [expires] - The expiration date.
+ * @property {boolean} [httpOnly] - The httpOnly flag.
+ */
+
+/**
+ * @typedef {object} pageType - The page.
+ * @property {string} body - The body of the page.
+ * @property {object} head - The head of the page.
+ * @property {cookieType[]} head.cookies - The cookies.
+ * @property {string} [head.contentType] - The content type.
+ * @property {number} [head.contentLength] - The content length.
+ * @property {number} [head.statusCode] - The status code.
+ * @property {string} [head.statusDescription] - The status description.
+ * @property {string} [head.redirectLocation] - The redirect location.
+ * @property {Record<string, string>} head.otherHeaders - The other headers.
+ * @property {string} [head.server] - The server.
+ * @property {object} file - The file.
+ * @property {string | null} file.fileType - The file type.
+ * @property {number | null} file.fileSize - The file size.
+ * @property {Buffer | null} file.fileBlob - The file blob.
+ */
+
+/**
+ * @typedef {object} metricsType - The metrics.
+ * @property {number} totalRequests - The total number of requests.
+ * @property {number} requestsInLastInterval - The number of requests in the last second.
+ */

package/src/upload.js

@@ -0,0 +1,92 @@
+/*
+ *	Process file uploads
+ */
+
+// eslint-disable @typescript-eslint/no-unused-vars
+
+import debugModule from 'debug';
+const debug = debugModule('webplsql:fileUpload');
+
+import {readFile, removeFile} from './file.js';
+import oracledb from 'oracledb';
+import z from 'zod';
+
+/**
+ * @typedef {import('express').Request} Request
+ * @typedef {import('oracledb').Connection} Connection
+ * @typedef {import('./types.js').fileUploadType} fileUploadType
+ */
+
+/**
+ * Get the files
+ *
+ * @param {Request} req - The req object represents the HTTP request.
+ * @returns {fileUploadType[]} - Promise that resolves with an array of files to be uploaded.
+ */
+export const getFiles = (req) => {
+	/** @type {fileUploadType[]} */
+	const files = [];
+
+	if (!('files' in req)) {
+		return files;
+	}
+
+	if (typeof req.files === 'object' && req.files !== null && Object.keys(req.files).length === 0) {
+		return files;
+	}
+
+	debug('req.files=', req.files);
+
+	// validate
+	const reqFiles = z
+		.object({
+			fieldname: z.string(),
+			originalname: z.string(),
+			encoding: z.string(),
+			mimetype: z.string(),
+			destination: z.string(),
+			filename: z.string(),
+			path: z.string(),
+			size: z.number(),
+		})
+		.array()
+		.parse(req.files);
+
+	return reqFiles;
+};
+
+/**
+ * Upload the given file and return a promise.
+ *
+ * @param {fileUploadType} file - The file to upload.
+ * @param {string} doctable - The file to upload.
+ * @param {Connection} databaseConnection - The file to upload.
+ * @returns {Promise<void>} - Promise that resolves when uploaded.
+ */
+export const uploadFile = async (file, doctable, databaseConnection) => {
+	/* istanbul ignore next */
+	if (typeof doctable !== 'string' || doctable.length === 0) {
+		throw new Error(`Unable to upload file "${file.filename}" because the option ""doctable" has not been defined`);
+	}
+
+	const blobContent = await readFile(file.path);
+	const sql = `INSERT INTO ${doctable} (name, mime_type, doc_size, dad_charset, last_updated, content_type, blob_content) VALUES (:name, :mime_type, :doc_size, 'ascii', SYSDATE, 'BLOB', :blob_content)`;
+	const bind = {
+		name: file.filename,
+		mime_type: file.mimetype,
+		doc_size: file.size,
+		blob_content: {
+			val: blobContent,
+			type: oracledb.BUFFER,
+		},
+	};
+
+	try {
+		await databaseConnection.execute(sql, bind, {autoCommit: true});
+	} catch (err) {
+		throw new Error(`Unable to insert file "${file.filename}"}`);
+	}
+
+	// remove the file
+	await removeFile(file.path);
+};

package/src/version.js

@@ -0,0 +1,23 @@
+import {fileURLToPath} from 'node:url';
+import {dirname, join} from 'node:path';
+import {getJsonFile} from './file.js';
+
+/**
+ * @typedef {object} PackageJSON
+ * @property {string} [version] - The package version.
+ */
+
+/**
+ * Retrieves the version from package.json.
+ *
+ * @returns {string} The version number of the package.
+ */
+export const getPackageVersion = () => {
+	const __filename = fileURLToPath(import.meta.url);
+	const __dirname = dirname(__filename);
+	const packageJsonPath = join(__dirname, '../package.json');
+
+	const pkg = /** @type {PackageJSON} */ (getJsonFile(packageJsonPath));
+
+	return typeof pkg.version === 'string' ? pkg.version : '';
+};

package/types/cgi.d.ts

@@ -0,0 +1,4 @@
+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/error.d.ts

@@ -0,0 +1 @@
+export function errorToString(error: unknown): string;

package/types/errorPage.d.ts

@@ -0,0 +1,10 @@
+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;
+};

package/types/file.d.ts

@@ -0,0 +1,5 @@
+export function readFile(filePath: string): Promise<Buffer>;
+export function removeFile(filePath: string): Promise<void>;
+export function getJsonFile(filePath: string): unknown;
+export function isDirectory(directoryPath: unknown): Promise<boolean>;
+export function isFile(filePath: unknown): Promise<boolean>;

package/types/handlerLogger.d.ts

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

package/types/handlerMetrics.d.ts

@@ -0,0 +1,4 @@
+export function initMetrics(): metricsType;
+export function handlerMetrics(metrics: metricsType): RequestHandler;
+export type RequestHandler = import("express").RequestHandler;
+export type metricsType = import("./types.js").metricsType;

package/types/handlerPlSql.d.ts

@@ -0,0 +1,8 @@
+export function handlerWebPlSql(connectionPool: Pool, config: configPlSqlHandlerType): RequestHandler;
+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;

package/types/handlerUpload.d.ts

@@ -0,0 +1,7 @@
+export function handlerUpload(): 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/index.d.ts

@@ -0,0 +1,10 @@
+export { startServer } from "./server.js";
+export * from "./shutdown.js";
+export * from "./oracle.js";
+export * from "./file.js";
+export * from "./tty.js";
+export * from "./version.js";
+export { handlerWebPlSql } from "./handlerPlSql.js";
+export { handlerLogger } from "./handlerLogger.js";
+export { handlerUpload } from "./handlerUpload.js";
+export { initMetrics, handlerMetrics } from "./handlerMetrics.js";

package/types/oracle.d.ts

@@ -0,0 +1,5 @@
+export function connectionValid(connectionPool: Pool): Promise<boolean>;
+export function poolCreate(user: string, password: string, connectString: string, poolMin?: number, poolMax?: number): Promise<Pool>;
+export function poolClose(pool: Pool): Promise<void>;
+export function poolsClose(pools: Pool[]): Promise<void>;
+export type Pool = import("oracledb").Pool;

package/types/parsePage.d.ts

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

package/types/procedure.d.ts

@@ -0,0 +1,10 @@
+export function invokeProcedure(req: Request, res: Response, argObj: argObjType, cgiObj: environmentType, filesToUpload: fileUploadType[], options: configPlSqlHandlerType, databaseConnection: Connection): 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;

package/types/procedureError.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @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/procedureNamed.d.ts

@@ -0,0 +1,14 @@
+export function getProcedureNamed(procName: string, argObj: argObjType, databaseConnection: Connection, options: configPlSqlHandlerType): Promise<{
+    sql: string;
+    bind: BindParameterConfig;
+}>;
+export type argsType = Record<string, string>;
+export type cacheEntryType = {
+    hitCount: number;
+    args: argsType;
+};
+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/procedureSanitize.d.ts

@@ -0,0 +1,14 @@
+export function sanitizeProcName(procName: string, databaseConnection: Connection, options: configPlSqlHandlerType): 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 cacheEntryType = {
+    hitCount: number;
+    valid: boolean;
+};

package/types/procedureVariable.d.ts

@@ -0,0 +1,9 @@
+export function getProcedureVariable(procName: string, argObj: argObjType, databaseConnection: Connection, options: configPlSqlHandlerType): Promise<{
+    sql: string;
+    bind: BindParameterConfig;
+}>;
+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/request.d.ts

@@ -0,0 +1,7 @@
+export function processRequest(req: Request, res: Response, options: configPlSqlHandlerType, connectionPool: Pool): 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;

package/types/requestError.d.ts

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

package/types/sendResponse.d.ts

@@ -0,0 +1,4 @@
+export function sendResponse(req: Request, res: Response, page: pageType): void;
+export type Request = import("express").Request;
+export type Response = import("express").Response;
+export type pageType = import("./types.js").pageType;

package/types/server.d.ts

@@ -0,0 +1,7 @@
+export function startServer(config: configType): Promise<void>;
+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 configType = import("./types.js").configType;

package/types/shutdown.d.ts

@@ -0,0 +1,2 @@
+export function installShutdown(handler: () => Promise<void>): void;
+export function forceShutdown(): void;

package/types/stream.d.ts

@@ -0,0 +1 @@
+export function streamToBuffer(readable: stream.Readable): Promise<Buffer>;

package/types/trace.d.ts

@@ -0,0 +1,5 @@
+export function inspect(value: unknown, depth?: number | null): string;
+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;

package/types/tty.d.ts

@@ -0,0 +1,4 @@
+export function write(text: string): void;
+export function writeNewLine(text?: string): void;
+export function writeAfterEraseLine(text: string): void;
+export function writeStartingOnColumn(text: string, column: number): void;