vivth 1.3.1 → 1.3.3

package/src/class/QChannel.mjs

@@ -2,7 +2,6 @@
 
 import { LazyFactory } from '../function/LazyFactory.mjs';
 import { TryAsync } from '../function/TryAsync.mjs';
-import { TrySync } from '../function/TrySync.mjs';
 import { Console } from './Console.mjs';
 
 /**
@@ -34,9 +33,9 @@ export class QChannel {
 	 * import { QChannel } from 'vivth';
 	 *
 	 * const myMappedQref = (window['myMappedQref'] = new Map());
-	 * export const MyQClass = QChannel.makeQClass(myMappedQref);
+	 * export const MyQClass = QChannel.setup(myMappedQref);
 	 */
-	static makeQClass = (uniqueMap) => {
+	static setup = (uniqueMap) => {
 		QChannel.#uniquePromiser = uniqueMap;
 		return QChannel;
 	};
@@ -215,7 +214,7 @@ export class QChannel {
 	 * - `callbackBlock` with error as value:
 	 * - caveat:
 	 * >- no need to manually call resume();
-	 * >- slightly less performant than `callback`;
+	 * >- slightly less performant than `key`;
 	 * @template RESULT
 	 * @param {DEFINEDANY} keyID
 	 * @param {(options:Omit<QCBReturn,
@@ -224,7 +223,7 @@ export class QChannel {
 	 * @returns {ReturnType<typeof TryAsync<RESULT>>}
 	 * @example
 	 * const q = new QChannel('channel name');
-	 * const [result, error] = await q.callback(keyID, async ({ isLastOnQ }) = > {
+	 * const [result, error] = await q.callback(keyID, async ({ isLastOnQ }) => {
 	 * 	// if (!isLastOnQ()) { // imperative debounce if needed
 	 * 	// 	return;
 	 * 	// }

package/src/class/SafeExit.mjs

@@ -52,7 +52,7 @@ export class SafeExit {
 	 * 		SafeExit.instance.exiting.correction(true);
 	 * 		Console.log(`safe exit via "${eventName}"`);
 	 * 	});
-	 * };
+	 * }
 	 * ```
 	 * - example Deno:
 	 * ```js
@@ -75,11 +75,11 @@ export class SafeExit {
 	 * 	// optional deno example
 	 * 	listener : (eventName) => {
 	 * 		const sig = Deno.signal(eventName);
-	 * 			for await (const _ of sig) {
-	 * 				exiting.correction(true);
-	 * 				sig.dispose();
-	 * 				Console.log(`safe exit via "${eventName}"`);
-	 * 			}
+	 * 		for await (const _ of sig) {
+	 * 			exiting.correction(true);
+	 * 			sig.dispose();
+	 * 			Console.log(`safe exit via "${eventName}"`);
+	 * 		}
 	 * 	}
 	 * });
 	 */
@@ -137,13 +137,32 @@ export class SafeExit {
 	 * @example
 	 * import { SafeExit } from 'vivth';
 	 *
-	 * SafeExit.instance.addCallback(()=>{
+	 * const exitCallback () => {
 	 * 	// code
-	 * })
+	 * }
+	 * SafeExit.instance.addCallback(exitCallback);
 	 */
 	addCallback = (cb) => {
 		safeCleanUpCBs.add(cb);
 	};
+	/**
+	 * @description
+	 * - optional exit event removal;
+	 * - the callbacks will be removed from registered via `addCallback` exiting;
+	 * @param {()=>(Promise<void>)} cb
+	 * @example
+	 * import { SafeExit } from 'vivth';
+	 *
+	 * const exitCallback () => {
+	 * 	// code
+	 * }
+	 * SafeExit.instance.addCallback(exitCallback);
+	 * // somewhere else
+	 * SafeExit.instance.removeCallback(exitCallback);
+	 */
+	removeCallback = (cb) => {
+		safeCleanUpCBs.delete(cb);
+	};
 	/**
 	 * @type {()=>void}
 	 */

package/src/class/Signal.mjs

@@ -114,7 +114,10 @@ export class Signal {
 		 * @returns {void}
 		 */
 		subscriber: (effectInstance) => {
-			effectInstance.options.removeEffect();
+			/**
+			 * this part is not needed, as the effect might need to react to other signals
+			// effectInstance.options.removeEffect();
+			 */
 			this.subscribers.setOf.delete(effectInstance);
 		},
 		/**

package/src/common/Base64URL.mjs

@@ -4,21 +4,23 @@
  * @description
  * - create inline base64 url;
  * - usage:
- * >- can be extremely usefull to display file on desktop app webview, without exposing http server;
+ * >- can be extremely usefull to display file on desktop app `webview` or any bundled browser, without exposing http server;
  * @param {string} fileString
  * @param {string} mimeType
  * @param {(string:string)=>string} btoaFunction
  * - check your js runtime `btoa`;
  * - node compatible:
  * ```js
- * (str, prevBufferEncoding) =>
- * 	Buffer.from(str, prevBufferEncoding).toString('base64')
+ * (str, prevBufferEncoding) => {
+ * 	return Buffer.from(str, prevBufferEncoding).toString('base64');
+ * }
  * ```
  * @returns {string}
  * @example
  * import { Base64URL } from 'vivth'
  * import fileString from './fileString.mjs';
  *
+ * // example for browser;
  * Base64URL(fileString, 'application/javascript', btoa);
  */
 export function Base64URL(fileString, mimeType, btoaFunction) {
@@ -28,4 +30,4 @@ export function Base64URL(fileString, mimeType, btoaFunction) {
 		binary += String.fromCharCode(byte);
 	}
 	return `data:${mimeType.toString()};base64,${btoaFunction(binary)}`;
-};
+}

package/src/common/Dev.mjs

@@ -0,0 +1,134 @@
+// @ts-check
+
+import { Console } from '../class/Console.mjs';
+import { Effect } from '../class/Effect.mjs';
+import { Signal } from '../class/Signal.mjs';
+import { LazyFactory } from '../function/LazyFactory.mjs';
+import { TryAsync } from '../function/TryAsync.mjs';
+import { Trace } from './Trace.mjs';
+
+/**
+ * @typedef {import("../types/VivthDevCodeBlockStringType.mjs").VivthDevCodeBlockStringType} VivthDevCodeBlockStringType
+ * @typedef {import('../types/DevTestCB.mjs').DevTestCB} DevTestCB
+ */
+
+/**
+ * @description
+ * - class helper for `devTime` only code block;
+ */
+export class Dev {
+	/**
+	 * @description
+	 * - persistent variable(during `devTime` and `bundled`);
+	 * - can be used as `condition` for checking whether it is in `devTime` or `bundled`;
+	 * @type {boolean}
+	 * @example
+	 * import { Dev } from 'vivth';
+	 *
+	 * if (Dev.isDev) {
+	 * 	// this code block will presist even on `bundled`;
+	 * }
+	 */
+	static isDev = true;
+	/**
+	 * @type {Signal<Map<string,Awaited<ReturnType<typeof TryAsync<boolean>>>>>}
+	 */
+	static #notifications = LazyFactory(() => new Signal(new Map()));
+	/**
+	 * @type {DevTestCB}
+	 */
+	static #test = async (testName, testCallback) => {
+		testName = `${testName}:'${Trace(4)}'`;
+		Dev.#notifications.subscribers.notify(async ({ signalInstance }) => {
+			signalInstance.value.set(
+				testName,
+				await TryAsync(async () => {
+					return await testCallback();
+				})
+			);
+		});
+		Dev.#effectForCheck['vivth:unwrapLazy;']();
+		return {
+			removeId: () => {
+				Dev.#notifications.subscribers.notify(async ({ signalInstance }) => {
+					signalInstance.value.delete(testName);
+				});
+			},
+		};
+	};
+	static #effectForCheck = LazyFactory(
+		() =>
+			new Effect(async ({ isLastCalled, subscribe }) => {
+				const notifications = subscribe(Dev.#notifications).value;
+				if (!(await isLastCalled(100)) || !notifications.size) {
+					return;
+				}
+				/**
+				 * @type {string[]}
+				 */
+				const succeedTest = [];
+				/**
+				 * @type {string[]}
+				 */
+				const failedTest = [];
+				for (const [notificationID, [isCorrect, error]] of notifications) {
+					if (error || !isCorrect) {
+						failedTest.push(notificationID);
+						continue;
+					}
+					succeedTest.push(notificationID);
+				}
+				const size = notifications.size;
+				/**
+				 * @type {{
+				 * testCount:number,
+				 * succeed?: {count:string, testID:string[]},
+				 * failed?: {count:string, testID:string[]},
+				 * }}
+				 */
+				let warn = { testCount: size };
+				if (succeedTest.length) {
+					warn.succeed = {
+						count: `${succeedTest.length} of ${size}`,
+						testID: succeedTest,
+					};
+				}
+				if (failedTest.length) {
+					warn.failed = {
+						count: `${failedTest.length} of ${size}`,
+						testID: failedTest,
+					};
+				}
+				Console.warn(warn);
+			})
+	);
+	/**
+	 * @description
+	 * - to wrap `devTime` only code block;
+	 * - when bundled uses `EsBundler` or esbuild with `ToBundledJSPlugin` plugin, the code block will be removed on the bundled version;
+	 * @param {(options:{test:DevTestCB})=>Promise<void>} callback
+	 * - also provide `test` method for inline testing:
+	 * >- which is wrapped in `TryAsync`, throwed errors will automatically return `false`;
+	 * @param {VivthDevCodeBlockStringType} _closing
+	 * - it is needed to detect the code block closing;
+	 * - should use single or double quote and not back tick;
+	 * @returns {Promise<void>}
+	 * @example
+	 * import { Dev, Signal } from 'vivth';
+	 *
+	 * Dev.vivthDevCodeBlock(async function () {
+	 * 	// this code block will be removed on `bundled` version;
+	 * }, 'vivthDevCodeBlock');
+	 *
+	 * const numberSignal = new Signal(0);
+	 * Dev.vivthDevCodeBlock(async ({ test }) => {
+	 * 	// this code block will be removed on `bundled` version;
+	 * 	const [{ removeId: removeTest }] = await Promise.all([
+	 * 		test(async () => numberSignal.value === 0)
+	 * 	])
+	 * }, 'vivthDevCodeBlock');
+	 */
+	static vivthDevCodeBlock = async (callback, _closing) => {
+		await callback({ test: Dev.#test });
+	};
+}

package/src/common/DevBundled.mjs

@@ -0,0 +1,5 @@
+// @ts-check
+
+export class Dev {
+	static isDev = false;
+}

package/src/common/Trace.mjs

@@ -0,0 +1,24 @@
+// @ts-check
+
+import { Paths } from '../class/Paths.mjs';
+
+/**
+ * @description
+ * - returns position of stack trace as string, formatted as `fileName:lineNumber:columnNumber`;
+ * - extremely usefull for:
+ * >- jumping positions to code line;
+ * >- creating dynamic string id;
+ * @param {number} traceIndex
+ * @returns {string}
+ * @example
+ * import { Trace, Console } from 'vivth';
+ *
+ * Console.log(Trace(3)); // "D://test.mjs:3:13"
+ */
+export function Trace(traceIndex) {
+	const err = new Error();
+	const stack = err.stack?.split('\n');
+	const callerLine = stack?.[Math.round(traceIndex)] ?? 'unknown';
+	const match = callerLine.match(/([A-Z]:[^ ]*[0-9]|\/[^ )]+:\d+:\d+)/m);
+	return Paths.normalize(match?.[1] ?? callerLine.trim());
+}

package/src/doc/JSautoDOC.mjs

@@ -3,6 +3,7 @@
 import { extname, join } from 'node:path';
 import { readFile } from 'node:fs/promises';
 
+import prettier from 'prettier';
 import chokidar from 'chokidar';
 import { EventSignal } from '../class/EventSignal.mjs';
 import { parsedFile } from './parsedFile.mjs';
@@ -36,21 +37,22 @@ const acceptableExt = new Set(['.mjs', '.mts', '.ts']);
  * - this autodocumenter uses [chokidar](https://npmjs.com/package/chokidar) under the hood;
  * - this class also is used to generate this `README.md`;
  * - behaviours:
+ * >- auto export must follows the following rules;
  * >1) add `"at"noautodoc` on self closing jsdoc comment to opt out from generating documentation on said file;
- * >>- auto export must follows the following rules, and there's no way to override;
- * >2) export all named exported 'const'|'function'|'async function'|'class', alphanumeric name, started with Capital letter, same name with fileName on `options.pahts.file`;
- * >3) declare typedef of existing typedef with alphanumeric name, started with Capital letter, same name with fileName, and have no valid export like on point <sup>1</sup> on `options.pahts.file`;
- * >4) create `README.md` based on, `options.paths.dir` and `README.src.md`;
+ * >2) will (generate) export all named exported 'const'|'function'|'async function'|'class', alphanumeric name, started with Capital letter, same name with fileName on `options.paths.file`;
+ * >3) will (generate) declare typedef of existing typedef with alphanumeric name, started with Capital letter, same name with fileName, and have no valid export like on point <sup>1</sup> on `options.paths.file`;
+ * >4) will (generate) create `README.md` based on, `options.paths.dir` and `README.src.md`;
  * >5) extract `"at"description` jsdoc:
  * >>- on static/prop that have depths, all of children should have `"at"static`/`"at"instance` `nameOfImmediateParent`, same block but before `"at"description` comment line;
  * >>- `"at"description` are treated as plain `markdown`;
  * >>- first `"at"${string}` after `"at"description` until `"at"example` will be treated as `javascript` comment block on the `markdown`;
  * >>- `"at"example` are treated as `javascript` block on the `markdown` file, and should be placed last on the same comment block;
  * >>- you can always look at `vivth/src` files to check how the source, and the `README.md` and `index.mjs` documentation/generation results;
- * >6) this types of arrow functions will be converted to regullar function, for concise type emition:
+ * >6) this types of arrow functions will be converted to regullar function, for concise type emition, includes:
  * >>- validly exported function;
- * >>- static/instance method(s) with generic template;
- * >7) transpile `.ts` and `.mts` to `.mjs` same name and directory;
+ * >>- static/instance method with generic template;
+ * >7) transpile `.ts` and `.mts` to `.mjs` with same name and directory;
+ * >>- use `"at"preserve` to preserve tsdoc comment section;
  */
 export class JSautoDOC {
 	/**
@@ -201,7 +203,9 @@ export class JSautoDOC {
 		const readmePath = join(rootPath, this.#paths.readMe);
 		const mjsFilePath = join(rootPath, this.#paths.file);
 		const [[, errorWriteReadme], [, errorWriteMjsFile]] = await Promise.all([
-			FileSafe.write(readmePath, readme, { encoding }),
+			FileSafe.write(readmePath, await prettier.format(readme, { parser: 'markdown' }), {
+				encoding,
+			}),
 			FileSafe.write(mjsFilePath, mjsFile, { encoding }),
 		]);
 		if (errorWriteReadme === undefined) {
@@ -244,7 +248,8 @@ export class JSautoDOC {
 		const apiDocuments = [];
 		const mjsMain = ['// @ts-check', this.#generateJSDOCFromstring(this.#copyright)];
 		const mjsTypes = [];
-		for await (const path_ of filepaths) {
+		const sortedFilepaths = [...filepaths].sort((a, b) => a.localeCompare(b));
+		for await (const path_ of sortedFilepaths) {
 			const {
 				documented,
 				content,
@@ -256,7 +261,6 @@ export class JSautoDOC {
 			if (trueContent === undefined) {
 				return;
 			}
-
 			const hasNoAutoDoc = /\/\*\*[\s\*]*?@noautodoc[\s\*]*?\*\//.test(trueContent);
 			if (hasValidExportObject) {
 				mjsMain.push(
@@ -398,7 +402,7 @@ export class JSautoDOC {
 			this.#filePaths.subscribers.notify(async ({ signalInstance }) => {
 				Console.warn({ [eventName]: path__ });
 				signalInstance.value.delete(path__);
-				this.#parsedFilesRef.unRef(path__);
+				await this.#parsedFilesRef.unRef(path__);
 			});
 		});
 	};

package/src/doc/parsedFile.mjs

@@ -322,7 +322,7 @@ export class parsedFile {
 		const fullDescTrue_0 = fullDescTrue[0] ?? '';
 		const description = fullDescTrue_0
 			.replace('*', '')
-			.replace(/(?<!\\)\*\s/g, '\n')
+			.replace(/\s*(?<!\\)\*\s/g, '\n')
 			.trim();
 		fullDescTrue.shift();
 		let example;

package/src/function/GetNamedImportAlias.mjs

@@ -0,0 +1,37 @@
+// @ts-check
+
+import { Console } from '../class/Console.mjs';
+
+/**
+ * @description
+ * - regex helper for:
+ * >- get named import; OR
+ * >- alias of named import;
+ * @param {string} content
+ * @param {string} moduleName
+ * @param {string} packageName
+ * @returns {string|undefined}
+ * @example
+ * import { GetNamedImportAlias } from 'vivth';
+ *
+ * const checkNoAlias = `
+ * import { something } from 'packageName';
+ * `
+ * const checkAlias = `
+ * import { something as somethingElse } from 'packageName';
+ * `
+ * GetNamedImportAlias(checkNoAlias, 'something', 'packageName'); // 'something'
+ * GetNamedImportAlias(checkAlias, 'something', 'packageName'); // 'somethingElse'
+ */
+export function GetNamedImportAlias(content, moduleName, packageName) {
+	const checkIfImportingFromVivthRegex = new RegExp(
+		`(import\\s+{\\s*[\\s\\S]*(?<imported>${moduleName})\\s+as\\s+(?<alias>[a-zA-Z0-9]+)[\\s\\S]*\\s*}\\s+from\\s+['"]${packageName}['"])|(import\\s+{\\s*[\\s\\S]*(?<imported>${moduleName})[\\s\\S]*\\s*}\\s+from\\s+['"]${packageName}['"])`,
+		'g'
+	);
+	const matched = checkIfImportingFromVivthRegex.exec(content);
+	if (!matched || !matched.groups) {
+		return;
+	}
+	const { imported, alias } = matched.groups;
+	return alias ?? imported;
+}

package/src/function/LazyFactory.mjs

@@ -33,7 +33,7 @@ import { unwrapLazy } from '../common/lazie.mjs';
  * const a = myInstance; // not yet initiated;
  * const b = a.myProp // imediately initiated;
  * // OR
- * myInstance["vivth:unwrapLazy;"]() // forcefully call the callback;
+ * myInstance["vivth:unwrapLazy;"]() // forcefully call factory generator;
  */
 export function LazyFactory(factory) {
 	/**

package/src/function/TsToMjs.mjs

@@ -12,9 +12,9 @@ import { FileSafe } from '../class/FileSafe.mjs';
 
 /**
  * @description
- * - turn `.mts`||`.ts` file into `.mjs`, no bundling, just translation;
+ * - turn `.mts`||`.ts` file into `.mjs`, no bundling, just traspilation;
  * - on certain circumstance where `.mjs` result needed to be typed, you need to manually add `jsdoc`;
- * >- uses `"at"preserve` to register `jsdoc` inline;
+ * >- uses `"at"preserve` to register `jsdoc`;
  * @param {string} path_
  * - path from `Paths.root`;
  * @param {Object} [options]
@@ -27,7 +27,7 @@ import { FileSafe } from '../class/FileSafe.mjs';
  * @example
  * import { TsToMjs } from 'vivth';
  *
- * TsToMjs('./myFile.mts', { encoding: 'utf-8', overrideDir: './other/dir' });
+ * await TsToMjs('./myFile.mts', { encoding: 'utf-8', overrideDir: './other/dir' });
  */
 export async function TsToMjs(path_, { overrideDir = undefined, encoding = 'utf-8' } = {}) {
 	if (Paths.root === undefined) {

package/src/types/DevTestCB.mjs

@@ -0,0 +1,11 @@
+// @ts-check
+
+/**
+ * @callback DevTestCB
+ * @param {string} testName
+ * @param {()=>Promise<boolean>} testCallback
+ * - already wrapped with `TryAsync`:
+ * >- if throws error will automatically return false;
+ * @returns {Promise<{removeId:()=>void}>}
+ * - calling `removeId` will remove the this test from reports;
+ */

package/src/types/Runtime.mjs

@@ -1,7 +1,6 @@
 // @ts-check
 
 /**
- * @description
  * - for popular runtimes check;
  * @typedef {'node' | 'bun' | 'deno' | 'browser' | 'unknown'} Runtime
  */

package/src/types/VivthDevCodeBlockStringType.mjs

@@ -0,0 +1,6 @@
+// @ts-check
+
+/**
+ * - closing helper for `Dev.vivthDevCodeBlock`;
+ * @typedef {'vivthDevCodeBlock'} VivthDevCodeBlockStringType
+ */

package/tsconfig.json

@@ -32,5 +32,10 @@
 		"noUnusedParameters": false,
 		"noPropertyAccessFromIndexSignature": false
 	},
-	"include": ["./index.mjs", "./src", "./dev"]
+	"include": [
+		//
+		"./index.mjs",
+		// "./dev",
+		"./src"
+	]
 }

package/types/index.d.mts

@@ -1,3 +1,4 @@
+export { ToBundledJSPlugin } from "./src/bundler/adds/ToBundledJSPlugin.mjs";
 export { CompileJS } from "./src/bundler/CompileJS.mjs";
 export { CreateESPlugin } from "./src/bundler/CreateESPlugin.mjs";
 export { EsBundler } from "./src/bundler/EsBundler.mjs";
@@ -18,13 +19,18 @@ export { SafeExit } from "./src/class/SafeExit.mjs";
 export { Setup } from "./src/class/Setup.mjs";
 export { Signal } from "./src/class/Signal.mjs";
 export { WorkerMainThread } from "./src/class/WorkerMainThread.mjs";
+export { WorkerResult } from "./src/class/WorkerResult.mjs";
+export { WorkerThread } from "./src/class/WorkerThread.mjs";
 export { Base64URL } from "./src/common/Base64URL.mjs";
 export { Base64URLFromFile } from "./src/common/Base64URLFromFile.mjs";
+export { Dev } from "./src/common/Dev.mjs";
 export { EventNameSpace } from "./src/common/EventNameSpace.mjs";
+export { Trace } from "./src/common/Trace.mjs";
 export { JSautoDOC } from "./src/doc/JSautoDOC.mjs";
 export { CreateImmutable } from "./src/function/CreateImmutable.mjs";
 export { EventCheck } from "./src/function/EventCheck.mjs";
 export { EventObject } from "./src/function/EventObject.mjs";
+export { GetNamedImportAlias } from "./src/function/GetNamedImportAlias.mjs";
 export { GetRuntime } from "./src/function/GetRuntime.mjs";
 export { IsAsync } from "./src/function/IsAsync.mjs";
 export { LazyFactory } from "./src/function/LazyFactory.mjs";
@@ -33,10 +39,8 @@ export { Try } from "./src/function/Try.mjs";
 export { TryAsync } from "./src/function/TryAsync.mjs";
 export { TrySync } from "./src/function/TrySync.mjs";
 export { TsToMjs } from "./src/function/TsToMjs.mjs";
-export { WorkerResult } from "./src/class/WorkerResult.mjs";
-export { WorkerThread } from "./src/class/WorkerThread.mjs";
-export { ToBundledJSPlugin } from "./src/bundler/adds/ToBundledJSPlugin.mjs";
 export type AnyButUndefined = import("./src/types/AnyButUndefined.mjs").AnyButUndefined;
+export type DevTestCB = import("./src/types/DevTestCB.mjs").DevTestCB;
 export type ExtnameType = import("./src/types/ExtnameType.mjs").ExtnameType;
 export type IsListSignal = import("./src/types/IsListSignal.mjs").IsListSignal;
 export type ListArg = import("./src/types/ListArg.mjs").ListArg;
@@ -46,3 +50,4 @@ export type MutationType = import("./src/types/MutationType.mjs").MutationType;
 export type QCBFIFOReturn = import("./src/types/QCBFIFOReturn.mjs").QCBFIFOReturn;
 export type QCBReturn = import("./src/types/QCBReturn.mjs").QCBReturn;
 export type Runtime = import("./src/types/Runtime.mjs").Runtime;
+export type VivthDevCodeBlockStringType = import("./src/types/VivthDevCodeBlockStringType.mjs").VivthDevCodeBlockStringType;

package/types/src/bundler/CompileJS.d.mts

@@ -1,9 +1,9 @@
 /**
  * @description
  * - function to compile `.ts`|`.mts`|`.mjs` file, into a single executable;
- * - also generate js representation;
+ * - also generate js representation of the `bundled` version of the target;
  * - uses [pkg](https://www.npmjs.com/package/pkg), [bun](https://bun.com/docs/bundler/executables), and [deno](https://docs.deno.com/runtime/reference/cli/compile/) compiler under the hood;
- * >- they are used only as packaging agent, and doesn't necessarily supports their advanced feature, such as, assets bundling(use [FSInline](#fsinline) instead);
+ * >- they are used only as packaging/compiler agent, and doesn't necessarily supports their advanced feature, such as, assets bundling(use [`FSInline`](#fsinline) instead);
  * >- `WorkerThread` will be converted to inline using `FSInline` too;
  *
  * !!!WARNING!!!
@@ -22,8 +22,12 @@
  * @param {string} options.entryPoint
  * - need to be manually prefixed;
  * @param {BufferEncoding} [options.encoding]
- * - write and read encoding for the sources;
+ * - read and write encoding for the sources;
  * - default: `utf-8`;
+ * @param {(entryPointContent:string)=>string} [options.preprocessEntryPoint]
+ * - to modify entry point before bundling;
+ * - `entryPointContent` is the original string of the entry point;
+ * - returned value then passed to `ESBundler`;
  * @param {boolean} options.minifyFirst
  * - minify the bundle before compilation;
  * @param {string} options.outDir
@@ -44,35 +48,59 @@
  * }>>}
  * @example
  * import { join } from 'node:path';
+ * import { CompileJS, Console, Paths, Setup } from 'vivth';
  *
- * import { CompileJS, Paths } from 'vivth';
+ * const { paths, safeExit } = Setup;
+ * new paths({
+ * 	root: process?.env?.INIT_CWD ?? process?.cwd(),
+ * });
+ * new safeExit({
+ * 	eventNames: ['SIGINT', 'SIGTERM'],
+ * 	terminator: () => process.exit(0), // OR on deno () => Deno.exit\* (0),
+ * 	listener: (eventName) => {
+ * 		process.once(eventName, function () {
+ * 			if (!safeExit.instance) {
+ * 				return;
+ * 			}
+ * 			safeExit.instance.exiting.correction(true);
+ * 			Console.log(`safe exit via "${eventName}"`);
+ * 		});
+ * 	},
+ * });
+ * const pathRoot = Paths.root;
+ * if (pathRoot) {
+ * 	const [[, error], [, errorbun]] = await Promise.all([
+ * 		CompileJS({
+ * 			entryPoint: join(pathRoot, '/dev/myEntryPoint.mjs'),
+ * 			minifyFirst: true,
+ * 			outDir: join(pathRoot, '/dev-pkg/'),
+ * 			compiler: 'pkg',
+ * 			compilerArguments: {
+ * 				target: 'node18-win-x64',
+ * 			},
+ * 			encoding: 'utf-8',
+ * 		}),
+ * 		await CompileJS({
+ * 			entryPoint: join(pathRoot, '/dev/myEntryPoint.mjs'),
+ * 			minifyFirst: true,
+ * 			outDir: join(pathRoot, '/dev-bun/'),
+ * 			compiler: 'bun',
+ * 			compilerArguments: {
+ * 				target: 'bun-win-x64',
+ * 			},
+ * 			encoding: 'utf-8',
+ * 		}),
+ * 	]);
+ * 	if (error || errorbun) {
+ * 		Console.error({ error, errorbun });
+ * 	}
+ * }
  *
- * const [[resultPkg, errorPkg], [resultBun, errorBun]] = await Promise.all([
- * 	CompileJS({
- * 		entryPoint: join(Paths.root, '/dev'),
- * 		minifyFirst: true,
- * 		outDir: join(Paths.root, '/dev-pkg'),
- * 		compiler: 'pkg',
- * 		compilerArguments: {
- * 			target: ['node18-win-x64'],
- * 		},
- * 		esBundlerPlugins: [],
- * 	}),
- * 	CompileJS({
- * 		entryPoint: join(Paths.root, '/dev'),
- * 		minifyFirst: true,
- * 		outDir: join(Paths.root, '/dev-pkg'),
- * 		compiler: 'bun',
- * 		compilerArguments: {
- * 			target: ['bun-win-x64'],
- * 		},
- * 		esBundlerPlugins: [],
- * 	}),
- * ])
  */
-export function CompileJS({ entryPoint, minifyFirst, encoding, outDir, compiler, compilerArguments, esBundlerPlugins, }: {
+export function CompileJS({ entryPoint, minifyFirst, encoding, outDir, preprocessEntryPoint, compiler, compilerArguments, esBundlerPlugins, }: {
     entryPoint: string;
     encoding?: BufferEncoding | undefined;
+    preprocessEntryPoint?: ((entryPointContent: string) => string) | undefined;
     minifyFirst: boolean;
     outDir: string;
     compiler?: "pkg" | "bun" | "deno" | undefined;