vivth 1.4.10 → 1.5.0

package/src/class/Paths.mjs

@@ -1,6 +1,6 @@
 // @ts-check
 
-import { Console } from './Console.mjs';
+import { join, normalize, sep } from 'path-unified';
 
 /**
  * @description
@@ -28,10 +28,11 @@ export class Paths {
 	 * ```
 	 * - other: you need to check your JSRuntime for the rootPath reference;
 	 * @example
-	 * import { Paths } from 'vivth';
+	 * import { Paths } from 'vivth/neutral';
 	 *
 	 * new Paths({
-	 * 	root: location.origin,
+	 * 	// root: location.origin,
+	 * 	// root: process.env.INIT_CWD ?? process.cwd(),
 	 * })
 	 */
 	constructor({ root }) {
@@ -47,52 +48,87 @@ export class Paths {
 	#root;
 	/**
 	 * @description
+	 * - MIGHT THROW AN ERROR;
+	 * >- most `vivth` modules uses this value, so you need to instantiate Paths by all means before using them;
 	 * - reference for rootPath
 	 * - `Paths` needed to be instantiated via:
 	 * >- `Paths` constructor;
 	 * >- `Setup.paths` constructor;
-	 * @type {string|undefined}
+	 * @type {string}
 	 */
 	static get root() {
-		if (Paths.#instance === undefined) {
-			Console.error({
+		if (Paths.#instance === undefined || !Paths.#instance.#root) {
+			throw {
 				error: 'Paths.instance.#root is undefined',
 				solutions: 'instantiate `Paths` or instantiate `Setup`',
-			});
-			return undefined;
+			};
 		}
 		return Paths.#instance.#root;
 	}
 	/**
 	 * @description
-	 * - normalize path separator to forward slash `/`;
-	 * @param {string} path_
+	 * - replace path separator to forward slash `/`;
+	 * - remove repeating `./`;
+	 * @param {string} path
 	 * @returns {string}
 	 * @example
-	 * import { Paths } from 'vivth';
+	 * import { Paths } from 'vivth/neutral';
 	 *
 	 * Paths.normalize('file:\\D:\\myFile.mjs'); //  "file://D://myFile.mjs"
 	 */
-	static normalize = (path_) => {
-		return path_.replace(/\\/g, '/');
+	static normalize = (path) => {
+		return normalize(path)
+			.replace(/\\/g, '/')
+			.replace(/\/\.\//g, '');
+	};
+	/**
+	 * @description
+	 * - replace path separator to `sep`;
+	 * @param {string} path
+	 * @returns {string}
+	 * @example
+	 * import { Paths } from 'vivth/neutral';
+	 *
+	 * Paths.nativeSep('path//myFile.mjs'); //  "path\myFile.mjs" OR "path/myFile.mjs" depending on sep value;
+	 */
+	static nativeSep = (path) => {
+		return Paths.normalize(path).replace(/\//g, sep);
 	};
 	/**
 	 * @description
-	 * - normalize path separator to forward slash `/`;
-	 * - then starts with forward slash `/`;
-	 * @param {string} path_
+	 * - normalized then starts with forward slash `/`;
+	 * @param {string} path
 	 * @returns {`/${string}`}
 	 * @example
-	 * import { Paths } from 'vivth';
+	 * import { Paths } from 'vivth/neutral';
 	 *
 	 * Paths.normalizesForRoot('path\\myFile.mjs'); //  "/path/myFile.mjs"
 	 */
-	static normalizesForRoot = (path_) => {
-		let normalized = Paths.normalize(path_);
-		if (normalized.startsWith('/') === false) {
+	static normalizeForRoot = (path) => {
+		let normalized = Paths.normalize(path);
+		if (!normalized.startsWith('/')) {
 			normalized = `/${normalized}`;
 		}
 		// @ts-expect-error
 		return normalized;
 	};
+	/**
+	 * @description
+	 * - convert path to diskAbsolute and normalized to be using forward slash;
+	 * - usefull for arguments for `methods` OR `functions` that needs to be absolute disk path, regardles if path is relative to project root, or already absolute path;
+	 * @param {string} path
+	 * @returns {string}
+	 * @example
+	 * import { Paths } from 'vivth/neutral';
+	 *
+	 * Paths.normalizesForRoot('\\path\\myFile.mjs'); //  "D://something/path/myFile.mjs"
+	 */
+	static diskAbsolute = (path) => {
+		path = Paths.normalize(path);
+		const rootPath = Paths.normalize(Paths.root);
+		if (!path.startsWith(rootPath)) {
+			path = Paths.normalize(join(rootPath, path));
+		}
+		return path;
+	};
 }

package/src/class/Prettivy.mjs

@@ -0,0 +1,51 @@
+// @ts-check
+
+import { resolveConfig, format } from 'prettier';
+import { QChannel } from './QChannel.mjs';
+import { LazyFactory } from '../function/LazyFactory.mjs';
+import { Console } from './Console.mjs';
+
+/**
+ * @description
+ * - `prettier` wrapper with option inference from path;
+ */
+export class Prettivy {
+	static #q = LazyFactory(() => new QChannel('JSPrettify'));
+	/**
+	 * @param {string} path
+	 */
+	constructor(path) {
+		this.path = path;
+		this.getOptions();
+	}
+	/**
+	 * @type {string}
+	 */
+	path;
+	/**
+	 * @type {import('prettier').Options|null}
+	 */
+	#options = null;
+	getOptions = async () => {
+		const [res, errorPrettifyResolveConfig] = await Prettivy.#q.callback(this, async () => {
+			if (!this.#options) {
+				this.options = await resolveConfig(this.path);
+			}
+			return this.#options;
+		});
+		if (!errorPrettifyResolveConfig) {
+			return res;
+		}
+		Console.error({ errorPrettifyResolveConfig });
+	};
+	/**
+	 * @param {string} contentBeforePrettified
+	 * @returns {Promise<string>}
+	 */
+	format = async (contentBeforePrettified) => {
+		return await format(contentBeforePrettified, {
+			...(await this.getOptions()),
+			filepath: this.path,
+		});
+	};
+}

package/src/class/QChannel.mjs

@@ -4,24 +4,38 @@ import { LazyFactory } from '../function/LazyFactory.mjs';
 import { TryAsync } from '../function/TryAsync.mjs';
 import { Console } from './Console.mjs';
 
+/**
+ * @typedef { import('../typehints/VivthCleanup.mjs').VivthCleanup } VivthCleanup
+ */
+
 /**
  * @description
  * - class for `Queue` handling;
  * @template {AnyButUndefined} DEFINEDANY
+ * @implements {VivthCleanup}
  */
 export class QChannel {
+	vivthCleanup = async () => {
+		this.close();
+	};
 	/**
 	 * @param {string} name
 	 * - only used as helper for logging, and has nothing to do with runtime behaviour;
+	 * @param {boolean} [log]
 	 */
-	constructor(name) {
+	constructor(name, log = false) {
 		this.name = name;
+		this.#log = log;
 		this.open();
 	}
 	/**
-	 * @typedef {import('../types/AnyButUndefined.mjs').AnyButUndefined} AnyButUndefined
-	 * @typedef {import('../types/QCBReturn.mjs').QCBReturn} QCBReturn
-	 * @typedef {import('../types/QCBFIFOReturn.mjs').QCBFIFOReturn} QCBFIFOReturn
+	 * @type {boolean}
+	 */
+	#log;
+	/**
+	 * @typedef {import('../typehints/AnyButUndefined.mjs').AnyButUndefined} AnyButUndefined
+	 * @typedef {import('../typehints/QCBReturn.mjs').QCBReturn} QCBReturn
+	 * @typedef {import('../typehints/QCBFIFOReturn.mjs').QCBFIFOReturn} QCBFIFOReturn
 	 */
 	/**
 	 * @description
@@ -30,7 +44,7 @@ export class QChannel {
 	 * @returns {typeof QChannel}
 	 * - usefull for Queue primitive on multiple library but single reference, like the Web by making the `Map` on `window` object;
 	 * @example
-	 * import { QChannel } from 'vivth';
+	 * import { QChannel } from 'vivth/neutral';
 	 *
 	 * const myMappedQref = (window['myMappedQref'] = new Map());
 	 * export const MyQClass = QChannel.setup(myMappedQref);
@@ -52,33 +66,28 @@ export class QChannel {
 	 */
 	static #uniqueCB = async (id, instance) => {
 		const existing = QChannel.#uniquePromiser.get(id);
-		// @ts-expect-error
-		let resolveFn;
-		const nextPromise = new Promise((resolve) => {
-			resolveFn = resolve;
-		});
+		const { promise, resolve } = Promise.withResolvers();
 		const context = {};
 		if (existing === undefined) {
-			QChannel.#uniquePromiser.set(id, [nextPromise, context]);
+			QChannel.#uniquePromiser.set(id, [promise, context]);
 			await Promise.resolve();
 		} else {
 			const [prevPromise] = existing;
 			await prevPromise;
-			QChannel.#uniquePromiser.set(id, [nextPromise, context]);
+			QChannel.#uniquePromiser.set(id, [promise, context]);
 		}
 		const resume = () => {
-			// @ts-expect-error
-			resolveFn();
+			resolve(true);
 			QChannel.#uniquePromiser.delete(id);
 		};
 		return {
 			resume,
 			isLastOnQ: () => {
-				if (QChannel.#uniquePromiser.has(id) === false) {
+				const res = QChannel.#uniquePromiser.get(id);
+				if (!res) {
 					return false;
 				}
-				// @ts-expect-error
-				const [, lastContext] = QChannel.#uniquePromiser.get(id);
+				const [, lastContext] = res;
 				return instance.#shouldRun && lastContext === context;
 			},
 		};
@@ -105,7 +114,7 @@ export class QChannel {
 					/**
 					 * uses locally declared object to make it unique from other QChannel instances;
 					 */
-					qfifo
+					qfifo,
 				);
 			},
 			/**
@@ -124,7 +133,7 @@ export class QChannel {
 				/**
 				 * @type {()=>Promise<RESULT>}
 				 */
-				asyncCallback
+				asyncCallback,
 			) => {
 				return await TryAsync(async () => {
 					const { resume } = await this.fifo.key();
@@ -148,7 +157,7 @@ export class QChannel {
 	 */
 	get #shouldRun() {
 		const shoulRun = this.#shouldRun_;
-		if (shoulRun === false) {
+		if (!shoulRun) {
 			Console.warn({ qChannel_name: this.name, message: 'is closed' });
 		}
 		return shoulRun;
@@ -157,20 +166,26 @@ export class QChannel {
 	 * @description
 	 * - disable queue;
 	 * - when `closed`, `isLastOnQ` will allways return `false`;
-	 * @returns {void}
+	 * @type {()=>void}
 	 */
 	close = () => {
 		this.#shouldRun_ = false;
+		if (!this.#log) {
+			return;
+		}
 		Console.info({ qChannel_name: this.name, message: 'closed' });
 	};
 	/**
 	 * @description
 	 * - enable queue;
 	 * - when `opened`, `isLastOnQ` will evaluate whether calls are actually the last of queue;
-	 * @returns {void}
+	 * @type {()=>void}
 	 */
 	open = () => {
 		this.#shouldRun_ = true;
+		if (!this.#log) {
+			return;
+		}
 		Console.info({ qChannel_name: this.name, message: 'opened' });
 	};
 	/**
@@ -199,14 +214,14 @@ export class QChannel {
 	key = async (keyID) => {
 		const { resume } = await QChannel.#uniqueCB(this, this);
 		const mapped = this.#mapped;
-		if (mapped.has(keyID) === false) {
+		if (!mapped.has(keyID)) {
 			mapped.set(keyID, {});
 		}
 		resume();
 		return await QChannel.#uniqueCB(
 			// @ts-expect-error
 			mapped.get(keyID),
-			this
+			this,
 		);
 	};
 	/**
@@ -228,14 +243,21 @@ export class QChannel {
 	 * 	// 	return;
 	 * 	// }
 	 * 	// code
+	 * 	// return result
 	 * })
 	 */
 	async callback(keyID, asyncCallback) {
-		return await TryAsync(async () => {
+		/**
+		 * @type {undefined|(()=>void)}
+		 */
+		let resume_;
+		const res = await TryAsync(async () => {
 			const { resume, isLastOnQ } = await this.key(keyID);
+			resume_ = resume;
 			const result = await asyncCallback({ isLastOnQ });
-			resume();
 			return result;
 		});
+		resume_?.();
+		return res;
 	}
 }

package/src/class/SafeExit.mjs

@@ -1,17 +1,20 @@
 // @ts-check
 
+import process from 'node:process';
+import { spawn } from 'node:child_process';
+
 import { TryAsync } from '../function/TryAsync.mjs';
-import { TrySync } from '../function/TrySync.mjs';
 import { WalkThrough } from './WalkThrough.mjs';
 import { Console } from './Console.mjs';
-import { Effect, mapOfEffects } from './Effect.mjs';
-import { EnvSignal } from './EnvSignal.mjs';
+import { mapOfEffects } from './Effect.mjs';
 import { setOFSignals } from './Signal.mjs';
-
-/**
- * @type {Set<()=>Promise<void>>}
- */
-export const safeCleanUpCBs = new Set();
+import { ForOfSync } from '../function/ForOfSync.mjs';
+import { QChannel } from './QChannel.mjs';
+import { Paths } from './Paths.mjs';
+import { FileSafe } from './FileSafe.mjs';
+import { UniqueFSTempName } from '../function/UniqueFSTempName.mjs';
+import { Preferrence } from '../common/Preferrence.mjs';
+import { join } from 'node:path';
 
 /**
  * @description
@@ -20,114 +23,168 @@ export const safeCleanUpCBs = new Set();
  * - most of functionality might need to access `SafeExit.instance.exiting`, if you get warning, you can instantiate `SafeExit` before running anything;
  */
 export class SafeExit {
+	/**
+	 * @type {QChannel<any>}
+	 */
+	#q = new QChannel('SafeExit');
 	/**
 	 * @description
 	 * - only accessible after instantiation;
 	 * @type {SafeExit|undefined}
 	 */
 	static instance;
+	/**
+	 * @type {Set<()=>Promise<void>>}
+	 */
+	safeCleanUpCBs = new Set();
 	/**
 	 * @description
-	 * @param {Object} options
-	 * @param {[string, ...string[]]} options.eventNames
-	 * - eventNames are blank by default, you need to manually name them all;
-	 * - 'exit' will be omited, as it might cause async callbacks failed to execute;
+	 * @param {...NodeJS.Signals} eventNames
+	 * - `beforeExit` is auto included;
 	 * - example:
 	 * ```js
-	 *  ['SIGINT', 'SIGTERM']
-	 * ```
-	 * @param {()=>void} options.terminator
-	 * - standard, process must be imported statically from 'node:process':
-	 * ```js
-	 * () => process.exit(0),
-	 * ```
-	 * @param {(eventName:string)=>void} [options.listener]
-	 * - default value
-	 * ```js
-	 * (eventName) => {
-	 * 	process.once(eventName, function () {
-	 * 		SafeExit.instance.exiting.correction(true);
-	 * 		Console.log(`safe exit via "${eventName}"`);
-	 * 	});
-	 * }
+	 *  ['SIGINT', 'SIGTERM'] // both are automatically added
 	 * ```
-	 * - if your exit callback doesn't uses `process` global object you need to input on the SafeExit instantiation
 	 * @example
 	 * import process from 'node:process';
-	 * import { SafeExit, Console } from 'vivth';
+	 * import { SafeExit } from 'vivth/node';
 	 *
-	 * new SafeExit({
-	 * 	eventNames: ['SIGINT', 'SIGTERM', ...eventNames],
-	 * 	terminator : () => process.exit(0),
-	 * 	listener : (eventName) => {
-	 * 			process.once(eventName, function () {
-	 * 				SafeExit.instance?.exiting.correction(true);
-	 * 				Console.log(`safe exit via "${eventName}"`);
-	 * 			});
-	 * 	}
-	 * });
+	 * new SafeExit('SIGINT', 'SIGTERM', ...eventNames);
 	 */
-	constructor({ eventNames, terminator, listener = undefined }) {
+	constructor(...eventNames) {
 		if (SafeExit.instance instanceof SafeExit) {
 			return SafeExit.instance;
 		}
 		SafeExit.instance = this;
-		this.#exit = terminator;
-		if (listener) {
-			this.#listener = listener;
-		}
 		this.#register(eventNames);
 	}
+
 	/**
-	 * @description
-	 * - optional exit event registration, by listening to it inside an `Effect`;
-	 * - when the value is `true`, meaning program is exitting;
-	 * @type {EnvSignal<boolean>}
+	 * @type {  undefined|import('node:child_process').ChildProcess }
+	 */
+	#childProcessHelper;
+
+	/**
+	 * @type {Parameters<QChannel<any>["callback"]>[1]}
 	 */
-	exiting = new EnvSignal(false);
+	#mitigationQ = async ({ isLastOnQ }) => {
+		if (
+			/**  */
+			!!this.#childProcessHelper ||
+			!isLastOnQ()
+		) {
+			return;
+		}
+		const tempPath = UniqueFSTempName(
+			Paths.diskAbsolute(join(Paths.root, '/vivth/src/safeExit-guard-with-bun.mjs')),
+			'.mjs',
+		);
+
+		await FileSafe.write(
+			tempPath,
+			`import process from "node:process";process.title="close this terminal to emit 'SIGTERM' to main process at '${Paths.normalize(Paths.root)}'";`,
+			{ encoding: Preferrence.encoding },
+		);
+		const proc = spawn(
+			'bun',
+			[
+				/**  */
+				'--watch',
+				tempPath,
+			],
+			{
+				cwd: Paths.root,
+				stdio: 'ignore',
+				detached: true,
+			},
+		);
+		this.#childProcessHelper = proc;
+		SafeExit.instance?.addCallback(async () => {
+			proc.kill('SIGTERM');
+		});
+		process.once('exit', () => {
+			proc.kill('SIGTERM');
+		});
+		ForOfSync(['exit', 'close'], (eventName) => {
+			proc.once(eventName, () => {
+				process.emit('SIGTERM');
+				proc.kill('SIGTERM');
+			});
+		});
+	};
+	#exitMitigation = () => {
+		this.#q.callback(this.#mitigationQ, this.#mitigationQ);
+	};
+
 	/**
-	 * @param {ConstructorParameters<typeof SafeExit>[0]["eventNames"]} eventNames
+	 * @param {...ConstructorParameters<typeof SafeExit>[0][]} eventNames
 	 * @returns {void}
 	 */
-	#register = (eventNames) => {
-		eventNames.forEach((eventName) => {
-			if (eventName.toLowerCase() === 'exit') {
-				return;
-			}
-			this.#listener(eventName);
+	#register = (eventNames = []) => {
+		eventNames.push(
+			/**
+			 * - `beforeExit` is necessary as sometimes `bun` might not listen to SIGNAL;
+			 * - and then somehow `exit` is already called;
+			 */
+			// @ts-expect-error
+			'beforeExit',
+			'SIGINT',
+			'SIGTERM',
+		);
+		const setOfEvents = new Set(eventNames);
+		setOfEvents.delete(
+			// @ts-expect-error
+			'exit',
+		);
+		ForOfSync(setOfEvents, (eventName) => {
+			this.#createListener(eventName);
 		});
 	};
+	#hasExited = false;
 	/**
 	 * @type {(eventName:string)=>void}
 	 */
-	#listener = (eventName) => {
-		if (SafeExit.instance === undefined) {
-			return;
-		}
-		SafeExit.instance.exiting.env.value;
-		process.once(eventName, function () {
-			if (SafeExit.instance === undefined) {
+	#createListener = (eventName) => {
+		process.once(eventName, async () => {
+			const [, errorCleanup] = await this.#q.callback(
+				this.#createListener,
+				async ({ isLastOnQ }) => {
+					if (!isLastOnQ() || this.#hasExited) {
+						return;
+					}
+					this.#hasExited = true;
+					await this.#cleanup(eventName);
+				},
+			);
+			if (!errorCleanup) {
 				return;
 			}
-			Console.log(`safe exit via "${eventName}"`);
-			SafeExit.instance.exiting.correction(true);
+			Console.error({ errorCleanup }, { now: true });
 		});
 	};
 	/**
 	 * @description
-	 * - optional exit event registration;
-	 * - the callbacks will be called when exiting;
-	 * @param {()=>(Promise<void>)} cb
+	 * - `SafeExit` ${eventName}.Callback registration;
+	 * - `onEventName` all callbacks are called simultanousely using `await Promise.all`;
+	 * >- for sequential event you need to put them in a single callback;
+	 * @param {()=>(Promise<void>)} safeExitCallback
+	 * @returns {{removeCallback:()=>void}}
 	 * @example
-	 * import { SafeExit } from 'vivth';
+	 * import { SafeExit } from 'vivth/node';
 	 *
-	 * const exitCallback () => {
+	 * const exitCallback = async () => {
 	 * 	// code
 	 * }
 	 * SafeExit.instance.addCallback(exitCallback);
 	 */
-	addCallback = (cb) => {
-		safeCleanUpCBs.add(cb);
+	addCallback = (safeExitCallback) => {
+		this.#exitMitigation();
+		this.safeCleanUpCBs.add(safeExitCallback);
+		return {
+			removeCallback: () => {
+				this.removeCallback(safeExitCallback);
+			},
+		};
 	};
 	/**
 	 * @description
@@ -135,7 +192,7 @@ export class SafeExit {
 	 * - the callbacks will be removed from registered via `addCallback` exiting;
 	 * @param {()=>(Promise<void>)} cb
 	 * @example
-	 * import { SafeExit } from 'vivth';
+	 * import { SafeExit } from 'vivth/node';
 	 *
 	 * const exitCallback () => {
 	 * 	// code
@@ -145,39 +202,39 @@ export class SafeExit {
 	 * SafeExit.instance.removeCallback(exitCallback);
 	 */
 	removeCallback = (cb) => {
-		safeCleanUpCBs.delete(cb);
+		this.safeCleanUpCBs.delete(cb);
+	};
+	triggerExit = async () => {
+		await this.#cleanup('vivth/node.SafeExit.instance.triggerExit');
 	};
+
 	/**
-	 * @type {()=>void}
+	 * @param {string} eventName
+	 * @returns {Promise<void>}
 	 */
-	#exit = () => {};
-	// @ts-expect-error
-	#autoCleanUp = new Effect(async ({ subscribe }) => {
-		if (
-			//
-			!subscribe(this.exiting.env).value
-		) {
-			return;
+	#cleanup = async (eventName) => {
+		Console.log({ SafeExit: `called by '${eventName}'` }, { now: true });
+		if (this.#childProcessHelper) {
+			this.#childProcessHelper.kill('SIGTERM');
+			Console.info('force closing bun terminal helper', { now: true });
 		}
+		await Promise.all(
+			ForOfSync(this.safeCleanUpCBs, async (cleanup) => {
+				const [, error] = await TryAsync(async () => {
+					await cleanup();
+				});
+				if (error === undefined) {
+					return;
+				}
+				Console.warn(error);
+			})[0],
+		);
 		WalkThrough.set(setOFSignals, (signal) => {
 			signal.remove.ref();
 		});
 		WalkThrough.map(mapOfEffects, ([effect, _]) => {
 			effect.options.removeEffect();
 		});
-		for await (const cleanup of safeCleanUpCBs) {
-			const [, error] = await TryAsync(async () => {
-				await cleanup();
-			});
-			if (error === undefined) {
-				continue;
-			}
-			Console.warn(error);
-		}
-		const [, errorExitting] = TrySync(this.#exit);
-		if (errorExitting === undefined) {
-			return;
-		}
-		Console.error(errorExitting);
-	});
+		process.exit(0);
+	};
 }