web_plsql 0.18.0 → 1.0.0

package/src/server/server.js

@@ -2,6 +2,8 @@ import debugModule from 'debug';
 const debug = debugModule('webplsql:server');
 import http from 'node:http';
 import https from 'node:https';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
 import express from 'express';
 import cookieParser from 'cookie-parser';
 import compression from 'compression';
@@ -11,8 +13,13 @@ import {poolCreate, poolsClose} from '../util/oracle.js';
 import {handlerUpload} from '../handler/handlerUpload.js';
 import {handlerLogger} from '../handler/handlerLogger.js';
 import {handlerWebPlSql} from '../handler/plsql/handlerPlSql.js';
+import {handlerAdmin} from '../handler/handlerAdmin.js';
 import {readFileSyncUtf8, getJsonFile} from '../util/file.js';
 import {showConfig} from './config.js';
+import {Cache} from '../util/cache.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
 
 /**
  * @typedef {import('node:net').Socket} Socket
@@ -23,7 +30,34 @@ import {showConfig} from './config.js';
  * @typedef {import('oracledb').Pool} Pool
  * @typedef {import('../types.js').environmentType} environmentType
  * @typedef {import('../types.js').configType} configType
+ * @typedef {import('../handler/plsql/procedureNamed.js').argsType} argsType
+ */
+
+/**
+ * @typedef {import('express').RequestHandler & {
+ *   procedureNameCache: Cache<string>;
+ *   argumentCache: Cache<argsType>;
+ * }} ExtendedRequestHandler
+ */
+
+/**
+ * Global Admin Context
  */
+export const AdminContext = {
+	startTime: new Date(),
+	/** @type {configType | null} */
+	config: null,
+	/** @type {Pool[]} */
+	pools: [],
+	/** @type {Array<{poolName: string, procedureNameCache: Cache<string>, argumentCache: Cache<argsType>}>} */
+	caches: [],
+	paused: false,
+	metrics: {
+		requestCount: 0,
+		errorCount: 0,
+		totalDuration: 0,
+	},
+};
 
 /**
  * @typedef {object} webServer - Web server interface.
@@ -40,6 +74,42 @@ import {showConfig} from './config.js';
  * @property {string} certFilename - cert filename.
  */
 
+/**
+ * Admin basic auth middleware
+ * @param {Request} req - The request.
+ * @param {Response} res - The response.
+ * @param {NextFunction} next - The next function.
+ */
+const adminAuth = (req, res, next) => {
+	const adminRoute = AdminContext.config?.adminRoute ?? '/admin';
+
+	// Simple pause check for all PL/SQL routes (not admin)
+	if (AdminContext.paused && !req.path.startsWith(adminRoute)) {
+		res.status(503).send('Server Paused');
+		return;
+	}
+
+	// Basic Auth for Admin Route
+	if (req.path.startsWith(adminRoute)) {
+		const user = AdminContext.config?.adminUser;
+		const pass = AdminContext.config?.adminPassword;
+
+		if (user && pass) {
+			const auth = {login: user, password: pass};
+			const b64auth = (req.headers.authorization ?? '').split(' ')[1] ?? '';
+			const [login, password] = Buffer.from(b64auth, 'base64').toString().split(':');
+
+			if (login !== auth.login || password !== auth.password) {
+				res.set('WWW-Authenticate', 'Basic realm="Admin Console"');
+				res.status(401).send('Authentication required.');
+				return;
+			}
+		}
+	}
+
+	next();
+};
+
 /**
  * Create HTTPS server.
  * @param {Express} app - express application
@@ -67,17 +137,27 @@ export const startServer = async (config, ssl) => {
 	debug('startServer: BEGIN', config, ssl);
 
 	const internalConfig = /** @type {configType} */ (z$configType.parse(config));
+	AdminContext.config = internalConfig;
 
 	showConfig(internalConfig);
 
 	// Create express app
 	const app = express();
 
+	// Pause & Admin Auth middleware
+	app.use(adminAuth);
+
 	// Access log
 	if (internalConfig.loggerFilename.length > 0) {
 		app.use(handlerLogger(internalConfig.loggerFilename));
 	}
 
+	// Admin console
+	const adminRoute = internalConfig.adminRoute ?? '/admin';
+	const adminDirectory = path.resolve(__dirname, '../admin');
+	app.use(adminRoute, handlerAdmin);
+	app.use(adminRoute, express.static(adminDirectory));
+
 	// Serving static files
 	for (const i of internalConfig.routeStatic) {
 		app.use(i.route, express.static(i.directoryPath));
@@ -92,6 +172,8 @@ export const startServer = async (config, ssl) => {
 
 	/** @type {Pool[]} */
 	const connectionPools = [];
+	AdminContext.pools = connectionPools;
+	AdminContext.caches = [];
 
 	// Oracle pl/sql express middleware
 	for (const i of internalConfig.routePlSql) {
@@ -99,7 +181,25 @@ export const startServer = async (config, ssl) => {
 		const pool = await poolCreate(i.user, i.password, i.connectString);
 		connectionPools.push(pool);
 
-		app.use([`${i.route}/:name`, i.route], handlerWebPlSql(pool, i));
+		const handler = handlerWebPlSql(pool, i);
+
+		// Capture caches for admin console
+		AdminContext.caches.push({
+			poolName: i.route,
+			procedureNameCache: handler.procedureNameCache,
+			argumentCache: handler.argumentCache,
+		});
+
+		app.use([`${i.route}/:name`, i.route], (req, res, next) => {
+			AdminContext.metrics.requestCount++;
+			const start = process.hrtime();
+			res.on('finish', () => {
+				const diff = process.hrtime(start);
+				const duration = diff[0] * 1000 + diff[1] / 1_000_000;
+				AdminContext.metrics.totalDuration += duration;
+			});
+			handler(req, res, next);
+		});
 	}
 
 	// create server
@@ -150,7 +250,13 @@ export const startServer = async (config, ssl) => {
 					resolve();
 				})
 				.on('error', (err) => {
-					console.error(err);
+					if ('code' in err) {
+						if (err.code === 'EADDRINUSE') {
+							err.message = `Port ${internalConfig.port} is already in use`;
+						} else if (err.code === 'EACCES') {
+							err.message = `Port ${internalConfig.port} requires elevated privileges`;
+						}
+					}
 					reject(err);
 				});
 		})

package/src/types.js

@@ -82,6 +82,9 @@ export const z$configPlSqlType = z.strictObject({
  * @property {configPlSqlType[]} routePlSql - The PL/SQL routes.
  * @property {number} [uploadFileSizeLimit] - Maximum size of each uploaded file in bytes or no limit if omitted.
  * @property {string} loggerFilename - name of the request logger filename or '' if not required.
+ * @property {string} [adminRoute] - Optional route for the admin console (defaults to /admin).
+ * @property {string} [adminUser] - Optional username for admin console basic auth.
+ * @property {string} [adminPassword] - Optional password for admin console basic auth.
  */
 export const z$configType = z.strictObject({
 	port: z.number(),
@@ -89,6 +92,9 @@ export const z$configType = z.strictObject({
 	routePlSql: z.array(z$configPlSqlType),
 	uploadFileSizeLimit: z.number().optional(),
 	loggerFilename: z.string(),
+	adminRoute: z.string().optional(),
+	adminUser: z.string().optional(),
+	adminPassword: z.string().optional(),
 });
 
 /**

package/src/util/cache.js

@@ -0,0 +1,123 @@
+/**
+ * @template T
+ * @typedef {{hitCount: number, value: T}} cacheEntryType
+ */
+
+/**
+ * Generic Cache class with LFU (Least Frequently Used) eviction policy.
+ * @template T
+ */
+export class Cache {
+	/**
+	 * @param {number} maxSize - Maximum number of entries in the cache.
+	 */
+	constructor(maxSize = 10000) {
+		/** @type {Map<string, cacheEntryType<T>>} */
+		this.cache = new Map();
+		this.maxSize = maxSize;
+		this.hits = 0;
+		this.misses = 0;
+	}
+
+	/**
+	 * Get an entry from the cache.
+	 * @param {string} key - The key.
+	 * @returns {T | undefined} - The value or undefined if not found.
+	 */
+	get(key) {
+		const entry = this.cache.get(key);
+		if (entry) {
+			entry.hitCount++;
+			this.hits++;
+			return entry.value;
+		}
+		this.misses++;
+		return undefined;
+	}
+
+	/**
+	 * Set an entry in the cache.
+	 * @param {string} key - The key.
+	 * @param {T} value - The value.
+	 */
+	set(key, value) {
+		// If updating an existing key, preserve its hitCount?
+		// Typically LFU implies resetting or keeping.
+		// For simplicity and avoiding complex aging, if we set it again, we reset hitCount or keep it?
+		// The requirement is "cache invalidation" (delete) or "cache loading" (set).
+		// If we overwrite, it's usually a new value. Let's reset hitCount to 0 for a fresh start or 1.
+
+		// Ensure we have space
+		if (this.cache.size >= this.maxSize && !this.cache.has(key)) {
+			this.prune();
+		}
+
+		this.cache.set(key, {hitCount: 0, value});
+	}
+
+	/**
+	 * Delete an entry from the cache.
+	 * @param {string} key - The key.
+	 */
+	delete(key) {
+		this.cache.delete(key);
+	}
+
+	/**
+	 * Clear the cache.
+	 */
+	clear() {
+		this.cache.clear();
+		this.hits = 0;
+		this.misses = 0;
+	}
+
+	/**
+	 * Prune the cache by removing the least frequently used entries.
+	 * Removes 10% of the cache size.
+	 */
+	prune() {
+		// Convert cache entries to an array
+		const entries = Array.from(this.cache.entries());
+
+		// Sort entries by hitCount in ascending order
+		entries.sort((a, b) => a[1].hitCount - b[1].hitCount);
+
+		// Remove the bottom 10%
+		const removeCount = Math.max(1, Math.floor(this.maxSize * 0.1));
+		const keysToRemove = entries.slice(0, removeCount).map(([key]) => key);
+
+		for (const key of keysToRemove) {
+			this.cache.delete(key);
+		}
+	}
+
+	/**
+	 * Get the size of the cache.
+	 * @returns {number} - The size.
+	 */
+	get size() {
+		return this.cache.size;
+	}
+
+	/**
+	 * Get all keys in the cache.
+	 * @returns {string[]} - The keys.
+	 */
+	keys() {
+		return Array.from(this.cache.keys());
+	}
+
+	/**
+	 * Get cache statistics.
+	 * @returns {{size: number, maxSize: number, hits: number, misses: number}} - The statistics.
+	 */
+	getStats() {
+		return {
+			size: this.cache.size,
+			maxSize: this.maxSize,
+			hits: this.hits,
+			misses: this.misses,
+		};
+	}
+}

package/src/util/jsonLogger.js

@@ -0,0 +1,47 @@
+import * as rotatingFileStream from 'rotating-file-stream';
+
+/**
+ * @typedef {object} LogEntry
+ * @property {string} timestamp - ISO string
+ * @property {'error'|'info'|'warning'} type - Log level
+ * @property {string} message - Error message
+ * @property {object} [req] - Request details
+ * @property {object} [details] - Additional details (stack, sql, etc)
+ */
+
+export class JsonLogger {
+	constructor(filename = 'error.json.log') {
+		this.stream = rotatingFileStream.createStream(filename, {
+			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
+		});
+	}
+
+	/**
+	 * Log an entry as NDJSON.
+	 * @param {LogEntry} entry - The entry to log.
+	 */
+	log(entry) {
+		try {
+			// Ensure timestamp exists
+			if (!entry.timestamp) {
+				entry.timestamp = new Date().toISOString();
+			}
+			const line = JSON.stringify(entry);
+			this.stream.write(line + '\n');
+		} catch (err) {
+			console.error('JsonLogger: Failed to write log', err);
+		}
+	}
+
+	/**
+	 * Close the stream.
+	 */
+	close() {
+		this.stream.end();
+	}
+}
+
+export const jsonLogger = new JsonLogger();

package/src/util/shutdown.js

@@ -12,8 +12,12 @@ export const installShutdown = (handler) => {
 	/*
 	 *	The 'unhandledRejection' event is emitted whenever a Promise is rejected and no error handler is attached to the promise within a turn of the event loop.
 	 */
-	process.on('unhandledRejection', (reason, p) => {
-		console.log('\nUnhandled promise rejection. Graceful shutdown...', reason, p);
+	process.on('unhandledRejection', (reason) => {
+		if (reason instanceof Error) {
+			console.error(`\n${reason.message}. Graceful shutdown...`);
+		} else {
+			console.error('\nUnhandled promise rejection. Graceful shutdown...', reason);
+		}
 		void handler();
 	});
 

package/src/util/trace.js

@@ -57,7 +57,7 @@ export const toTable = (head, body) => {
 
 	// Calculate column widths
 	const widths = head.map((h, i) => {
-		const bodyMax = Math.max(0, ...body.map((row) => (row[i] || '').length));
+		const bodyMax = Math.max(0, ...body.map((row) => (row[i] ?? '').length));
 		return Math.max(h.length, bodyMax);
 	});
 
@@ -68,13 +68,13 @@ export const toTable = (head, body) => {
 	 *	@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 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 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};

package/src/version.js

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

package/types/handler/handlerAdmin.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @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/plsql/errorPage.d.ts

@@ -8,3 +8,4 @@ export type outputType = {
     html: string;
     text: string;
 };
+export type messageType = import("../../util/trace.js").messageType;

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

@@ -1,4 +1,4 @@
-export function handlerWebPlSql(connectionPool: Pool, config: configPlSqlHandlerType): RequestHandler;
+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;
@@ -6,3 +6,8 @@ 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/procedure.d.ts

@@ -1,4 +1,4 @@
-export function invokeProcedure(req: Request, res: Response, argObj: argObjType, cgiObj: environmentType, filesToUpload: fileUploadType[], options: configPlSqlHandlerType, databaseConnection: Connection): Promise<void>;
+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;
@@ -8,3 +8,5 @@ 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/procedureNamed.d.ts

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

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

@@ -1,4 +1,4 @@
-export function sanitizeProcName(procName: string, databaseConnection: Connection, options: configPlSqlHandlerType): Promise<string>;
+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;
@@ -8,7 +8,4 @@ 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;
-};
+export type ProcedureNameCache = import("../../util/cache.js").Cache<string>;

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

@@ -1,4 +1,4 @@
-export function getProcedureVariable(req: Request, procName: string, argObj: argObjType): {
+export function getProcedureVariable(_req: Request, procName: string, argObj: argObjType): {
     sql: string;
     bind: BindParameterConfig;
 };

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

@@ -1,7 +1,9 @@
-export function processRequest(req: Request, res: Response, options: configPlSqlHandlerType, connectionPool: Pool): Promise<void>;
+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/sendResponse.d.ts

@@ -1,4 +1,4 @@
-export function sendResponse(req: Request, res: Response, page: pageType): Promise<void>;
+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;

package/types/server/server.d.ts

@@ -1,3 +1,19 @@
+export namespace AdminContext {
+    let startTime: Date;
+    let config: configType | null;
+    let pools: Pool[];
+    let caches: Array<{
+        poolName: string;
+        procedureNameCache: Cache<string>;
+        argumentCache: Cache<argsType>;
+    }>;
+    let paused: boolean;
+    namespace metrics {
+        let requestCount: number;
+        let errorCount: number;
+        let totalDuration: number;
+    }
+}
 export function createServer(app: Express, ssl?: sslConfig): http.Server | https.Server;
 export function startServer(config: configType, ssl?: sslConfig): Promise<webServer>;
 export function loadConfig(filename?: string): configType;
@@ -10,6 +26,11 @@ 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;
+export type argsType = import("../handler/plsql/procedureNamed.js").argsType;
+export type ExtendedRequestHandler = import("express").RequestHandler & {
+    procedureNameCache: Cache<string>;
+    argumentCache: Cache<argsType>;
+};
 /**
  * - Web server interface.
  */
@@ -48,5 +69,6 @@ export type sslConfig = {
      */
     certFilename: string;
 };
+import { Cache } from '../util/cache.js';
 import http from 'node:http';
 import https from 'node:https';

package/types/types.d.ts

@@ -92,6 +92,9 @@ export const z$configPlSqlType: z.ZodObject<{
  * @property {configPlSqlType[]} routePlSql - The PL/SQL routes.
  * @property {number} [uploadFileSizeLimit] - Maximum size of each uploaded file in bytes or no limit if omitted.
  * @property {string} loggerFilename - name of the request logger filename or '' if not required.
+ * @property {string} [adminRoute] - Optional route for the admin console (defaults to /admin).
+ * @property {string} [adminUser] - Optional username for admin console basic auth.
+ * @property {string} [adminPassword] - Optional password for admin console basic auth.
  */
 export const z$configType: z.ZodObject<{
     port: z.ZodNumber;
@@ -118,6 +121,9 @@ export const z$configType: z.ZodObject<{
     }, z.core.$strict>>;
     uploadFileSizeLimit: z.ZodOptional<z.ZodNumber>;
     loggerFilename: z.ZodString;
+    adminRoute: z.ZodOptional<z.ZodString>;
+    adminUser: z.ZodOptional<z.ZodString>;
+    adminPassword: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 export type BindParameter = import("oracledb").BindParameter;
 export type Connection = import("oracledb").Connection;
@@ -217,6 +223,18 @@ export type configType = {
      * - name of the request logger filename or '' if not required.
      */
     loggerFilename: string;
+    /**
+     * - Optional route for the admin console (defaults to /admin).
+     */
+    adminRoute?: string;
+    /**
+     * - Optional username for admin console basic auth.
+     */
+    adminUser?: string;
+    /**
+     * - Optional password for admin console basic auth.
+     */
+    adminPassword?: string;
 };
 /**
  * Environment variables as string key-value pairs

package/types/util/cache.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @template T
+ * @typedef {{hitCount: number, value: T}} cacheEntryType
+ */
+/**
+ * Generic Cache class with LFU (Least Frequently Used) eviction policy.
+ * @template T
+ */
+export class Cache<T> {
+    /**
+     * @param {number} maxSize - Maximum number of entries in the cache.
+     */
+    constructor(maxSize?: number);
+    /** @type {Map<string, cacheEntryType<T>>} */
+    cache: Map<string, cacheEntryType<T>>;
+    maxSize: number;
+    hits: number;
+    misses: number;
+    /**
+     * Get an entry from the cache.
+     * @param {string} key - The key.
+     * @returns {T | undefined} - The value or undefined if not found.
+     */
+    get(key: string): T | undefined;
+    /**
+     * Set an entry in the cache.
+     * @param {string} key - The key.
+     * @param {T} value - The value.
+     */
+    set(key: string, value: T): void;
+    /**
+     * Delete an entry from the cache.
+     * @param {string} key - The key.
+     */
+    delete(key: string): void;
+    /**
+     * Clear the cache.
+     */
+    clear(): void;
+    /**
+     * Prune the cache by removing the least frequently used entries.
+     * Removes 10% of the cache size.
+     */
+    prune(): void;
+    /**
+     * Get the size of the cache.
+     * @returns {number} - The size.
+     */
+    get size(): number;
+    /**
+     * Get all keys in the cache.
+     * @returns {string[]} - The keys.
+     */
+    keys(): string[];
+    /**
+     * Get cache statistics.
+     * @returns {{size: number, maxSize: number, hits: number, misses: number}} - The statistics.
+     */
+    getStats(): {
+        size: number;
+        maxSize: number;
+        hits: number;
+        misses: number;
+    };
+}
+export type cacheEntryType<T> = {
+    hitCount: number;
+    value: T;
+};