@j-o-r/sh 1.1.28 → 1.1.31

package/lib/AsyncTracker.js

@@ -1,4 +1,3 @@
-
 // Copyright 2023 J.H. Duin
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
@@ -8,35 +7,53 @@
 //     https://www.apache.org/licenses/LICENSE-2.0
 //
 // Unless required by applicable law or agreed to in writing, software
+// distributed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
 // distributed under the License is distributed on an "AS IS" BASIS,
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
+
 import { writeFileSync } from 'node:fs';
 import { format } from 'node:util';
 import async_hooks from 'async_hooks';
 
 const DEBUG = false;
+
 /**
  * @typedef {Object} AsyncHookItem
- * Represents an item in the async hooks tracking.
- * 
- * @property {number} key - The unique identifier for the async operation.
- * @property {string} type - The type of the async operation, e.g., 'PROMISE'.
- * @property {number} triggerAsyncId - The async ID of the resource that triggered this operation.
- * @property {string} stack - The call stack trace when the async operation was initialized.
- * @property {SystemTypes} resource - The Promise object associated with this operation, including its state and async IDs.-
+ * @property {number} key - Unique async ID.
+ * @property {string} type - Async type (e.g., 'PROMISE').
+ * @property {number} triggerAsyncId - Triggering async ID.
+ * @property {string} stack - Call stack at init.
+ * @property {any} resource - Associated resource (e.g., Promise).
  */
+
 /**
-* @typedef  {'PROMISE'|'TIMEOUT'|'PROCESSNEXTTICK'|'TICKOBJECT' | 'SCRIPT' |'QUERYWRAP' | 'FILEHANDLE' | 'HTTP2SESSION' | 'HTTP2STREAM' | 'ZLIB' | 'UDPSENDWRAP' | 'WRITEWRAP' | 'SHUTDOWNWRAP' | 'PROMISEEXECUTOR'|'TCPCONNECTWRAP'| 'GETADDRINFOREQWRAP' | 'GETNAMEINFOREQWRAP' |'IMMEDIATE'|'TCPWRAP'|'TCPSERVERWRAP'|'UDPWRAP'|'FSREQCALLBACK'|'HTTPPARSER'|'PIPEWRAP'|'PIPECONNECTWRAP'|'STREAMWRAP'|'TTYWRAP'|'PROCESS'|'SIGNALWRAP'|'TIMERWRAP'} SystemTypes
+ * @typedef {'PROMISE'|'TIMEOUT'|'PROCESSNEXTTICK'|'TICKOBJECT' | 'SCRIPT' |'QUERYWRAP' | 'FILEHANDLE' | 'HTTP2SESSION' | 'HTTP2STREAM' | 'ZLIB' | 'UDPSENDWRAP' | 'WRITEWRAP' | 'SHUTDOWNWRAP' | 'PROMISEEXECUTOR'|'TCPCONNECTWRAP'| 'GETADDRINFOREQWRAP' | 'GETNAMEINFOREQWRAP' |'IMMEDIATE'|'TCPWRAP'|'TCPSERVERWRAP'|'UDPWRAP'|'FSREQCALLBACK'|'HTTPPARSER'|'PIPEWRAP'|'PIPECONNECTWRAP'|'STREAMWRAP'|'TTYWRAP'|'PROCESS'|'SIGNALWRAP'|'TIMERWRAP'} SystemTypes
+ * @description Node.js async resource types supported by async_hooks.
+ */
+
 /**
-* @param {any[]} args
-*/
+ * Debug logger (file output if DEBUG=true).
+ *
+ * @param {...any[]} args - Log args.
+ */
 function debug(...args) {
 	if (!DEBUG) return;
-	// Use a function like this one when debugging inside an AsyncHook callback
 	writeFileSync('debug.out', `${format(...args)}\n`, { flag: 'a' });
 }
+
+/**
+ * Human-readable descriptions for {@link SystemTypes}.
+ *
+ * @type {Record<SystemTypes, string>}
+ */
 const TYPES = {
 	TIMERWRAP: 'setTimeout(), setInterval()',
 	PROMISE: 'Promise',
@@ -66,139 +83,132 @@ const TYPES = {
 	WRITEWRAP: 'Used by process.stdout and process.stderr',
 	SHUTDOWNWRAP: 'Used by socket.end()',
 };
-/*
---- resourceTypes ---
-	'Promise',
-	'Timeout',
-	'Immediate',
-	'TCPWrap',
-	'TCPSERVERWRAP',
-	'UDPWrap',
-	'FSReqCallback',
-	'HTTPParser',
-	'PipeWrap',
-	'PipeConnectWrap',
-	'StreamWrap',
-	'TtyWrap',
-	'Process',
-	'SignalWrap',
-	'TimerWrap'
-*/
+
 /**
-* @param {SystemTypes} type
-*/
+ * Gets description for a {@link SystemTypes} value.
+ *
+ * @param {SystemTypes} type - Async type.
+ * @returns {string} Description.
+ * @throws {Error} Unknown type.
+ */
 const getTypeDescription = (type) => {
-	if (TYPES[type]) return TYPES[type];
-	const err = `Unknown type: ${type}`;
-	throw new Error(err);
-}
+	const upper = type.toUpperCase();
+	if (TYPES[upper]) return TYPES[upper];
+	throw new Error(`Unknown type: ${type}`);
+};
 
+/**
+ * Tracks unresolved async operations using Node's async_hooks.
+ *
+ * Detects leaks like hanging Promises, Timers. Used by {@link Test}.
+ *
+ * @example
+ * const tracker = new AsyncTracker();
+ * tracker.enable('PROMISE');
+ * // Run code...
+ * console.log(tracker.report(true)); // Unresolved count + details
+ */
 class AsyncTracker {
 	#enabled = false;
 	#filter = '';
 	#storage = new Map();
-	/** @type {import('async_hooks').AsyncHook} */
-	#hook;
-	constructor() {
-	}
-	/** 
-	* 'arm' the registration of async methods
-	*/
+	/** @type {import('async_hooks').AsyncHook | null} */
+	#hook = null;
+
+	/**
+	 * Arms the async hook (clears storage, sets filter).
+	 *
+	 * @private
+	 */
 	#arm() {
 		if (this.#hook) {
 			this.#hook.disable();
 		}
 		this.#storage.clear();
 		const storage = this.#storage;
-		const filter = this.#filter
-		// CreateHook triggers a Promise itself
+		const filter = this.#filter;
 		this.#hook = async_hooks.createHook({
-			/**
-			* @param {number} asyncId
-			* @param {string} type
-			* @param {number} triggerAsyncId
-			* @param {object} resource
-			*/
 			init(asyncId, type, triggerAsyncId, resource) {
 				type = type.toUpperCase();
 				if (filter === '' || filter === type) {
 					const stackString = new Error().stack;
 					const stackLines = stackString.split("\n");
 					const stack = stackLines.slice(6, 20).join("\n").trim();
-					// Only add a type where we can trace back to a file
 					const hasFile = stack.includes('file:///');
 					if (hasFile) {
 						debug({ action: 'set', asyncId, type, hasFile });
-						// debug({ action: 'set', asyncId, type})
 						storage.set(asyncId, { type, triggerAsyncId, stack, resource });
 					}
 				}
 			},
-			/**
-			* @param {number} asyncId
-			*/
 			after(asyncId) {
-				// // after() is called just after the resource's callback has finished.
 				if (storage.has(asyncId)) {
-					debug({ type: 'after', asyncId })
+					debug({ type: 'after', asyncId });
 					storage.delete(asyncId);
 				}
 			},
-			/**
-			* @param {number} asyncId
-			*/
 			destroy(asyncId) {
-				// `destroy` is called by the garbage collector once resolved/runned
 				if (storage.has(asyncId)) {
-					debug({ type: 'destroy', asyncId })
+					debug({ type: 'destroy', asyncId });
 					storage.delete(asyncId);
 				}
 			},
-
-			/**
-			* @param {number} asyncId
-			*/
 			promiseResolve(asyncId) {
 				if (storage.has(asyncId)) {
-					debug({ type: 'resolve', asyncId })
+					debug({ type: 'resolve', asyncId });
 					storage.delete(asyncId);
 				}
 			}
 		});
 	}
 
-	/** 
-	* Enables tracking of asynchronous methods. Optionally, only methods of a specified type can be tracked.	
-	* @param {SystemTypes} [type] - optional only register async methods for a specific type 
-	*/
+	/**
+	 * Enables tracking (optionally filter by type).
+	 *
+	 * @param {SystemTypes} [type] - Filter to specific type (e.g., 'PROMISE').
+	 * @throws {Error} Unknown type.
+	 * @example
+	 * tracker.enable('PROMISE');
+	 */
 	enable(type) {
 		if (type && !TYPES[type.toUpperCase()]) {
-			const err = `Unknown type: ${type}`;
-			throw new Error(err);
+			throw new Error(`Unknown type: ${type}`);
 		}
 		this.#filter = type ? type.toUpperCase() : '';
 		this.#arm();
 		this.#enabled = true;
-		this.#hook.enable()
+		this.#hook.enable();
 	}
+
 	/**
-	* Disables the tracking of asynchronous methods. 
-	*/
+	 * Disables tracking.
+	 *
+	 * @example
+	 * tracker.disable();
+	 */
 	disable() {
 		if (this.#hook) this.#hook.disable();
 		this.#enabled = false;
 	}
-	/** 
-	* Clears all tracked asynchronous methods.	
-	*/
+
+	/**
+	 * Clears tracked items.
+	 *
+	 * @example
+	 * tracker.reset();
+	 */
 	reset() {
 		this.#storage.clear();
 	}
-	/*
-	* Prints an overview of active asynchronous calls.
-	* @param {boolean} [verbose] - default false, print an overview of active async calls
-	* @returns {number} Number of active, unresolved async calls
-	*/
+
+	/**
+	 * Reports unresolved count (+ verbose details).
+	 *
+	 * @param {boolean} [verbose=false] - Print stack/resource per item.
+	 * @returns {number} Unresolved count.
+	 * @example
+	 * if (tracker.report(true) > 0) console.error('Leaks!');
+	 */
 	report(verbose = false) {
 		const size = this.#storage.size;
 		if (verbose) {
@@ -213,46 +223,55 @@ class AsyncTracker {
 		}
 		return size;
 	}
+
 	/**
-	* Returns an array of unresolved asynchronous methods, optionally filtered by type	
-	* @param {SystemTypes} [type] - The type of async methods to filter by
-	* @returns {AsyncHookItem[]}
-	*/
+	 * Gets unresolved items (filtered).
+	 *
+	 * Temporarily disables hook during query.
+	 *
+	 * @param {SystemTypes} [type] - Filter type.
+	 * @returns {AsyncHookItem[]} Array of items.
+	 * @example
+	 * const leaks = tracker.getUnresolved('PROMISE');
+	 */
 	getUnresolved(type) {
 		if (this.#enabled) {
 			this.#hook.disable();
 		}
-		// @ts-ignore
-		if (type) type = type.toUpperCase();
+		const upperType = type ? type.toUpperCase() : undefined;
 		let items = Array.from(this.#storage, ([key, value]) => ({ key, ...value }));
-		if (type) {
-			items = items.filter(item => item.type === type);
+		if (upperType) {
+			items = items.filter(item => item.type === upperType);
 		}
 		if (this.#enabled) {
 			this.#hook.enable();
 		}
 		return items;
 	}
+
 	/**
-	* Returns a description of the specified asynchronous method type	
-	* @param {SystemTypes} type - The type of asynchronous method.
-	* @returns {string}
-	*/
+	 * Gets description for type.
+	 *
+	 * @param {SystemTypes} type - Type.
+	 * @returns {string} Description.
+	 * @throws {Error} Unknown.
+	 * @example
+	 * tracker.getTypeDescription('PROMISE'); // 'Promise'
+	 */
 	getTypeDescription(type) {
-		// @ts-ignore
-		type = type.toUpperCase();
-		return getTypeDescription(type)
+		return getTypeDescription(type);
 	}
 
 	/**
-	* Adds or overwrites a custom type for asynchronous methods.	
-	* @param {string} type - The type of asynchronous method.
-	* @param {string} description - the description
-	* @returns {void}
-	*/
+	 * Registers custom type description.
+	 *
+	 * @param {string} type - Type key (uppercased).
+	 * @param {string} description - Description.
+	 * @example
+	 * tracker.addCustomType('MYTYPE', 'My async op');
+	 */
 	addCustomType(type, description) {
-		type = type.toUpperCase();
-		TYPES[type] = description;
+		TYPES[type.toUpperCase()] = description;
 	}
 }