vivth 1.3.2 → 1.3.4

package/src/class/FileSafe.mjs

@@ -1,6 +1,8 @@
 // @ts-check
-import { writeFile, mkdir, copyFile, rename, rm } from 'node:fs/promises';
+
+import { writeFile, mkdir, copyFile, rename, rm, access } from 'node:fs/promises';
 import { dirname } from 'node:path';
+import { constants } from 'node:fs';
 
 import { TryAsync } from '../function/TryAsync.mjs';
 
@@ -9,6 +11,33 @@ import { TryAsync } from '../function/TryAsync.mjs';
  * - collection of static methods of file access with added safety to mkdir before proceeding;
  */
 export class FileSafe {
+	/**
+	 * @description
+	 * - method to safely detects whether filePaths exist;
+	 * - uses fs/promises access under the hood;
+	 * - also returning promise of result & error as value;
+	 * @param {string} filePath
+	 * @returns {ReturnType<typeof TryAsync<true>>}
+	 * @example
+	 * import { join } from 'node:path';
+	 * import { FileSafe, Paths } from 'vivth';
+	 *
+	 * const [, error] = await FileSafe.write(
+	 * 	join(Paths.root, '/some/path.mjs'),
+	 * );
+	 * if (!error) {
+	 * 	// file exists
+	 * } else {
+	 * 	// file not exists
+	 * }
+	 */
+	static exist = async (filePath) => {
+		// @ts-expect-error
+		return await TryAsync(async () => {
+			await access(filePath, constants.F_OK);
+			return true;
+		});
+	};
 	/**
 	 * @description
 	 * - method to create file safely by recursively mkdir the dirname of the outFile;

package/src/class/ListSignal.mjs

@@ -85,7 +85,7 @@ export class ListSignal extends Signal {
 			 * @instance arrayMethods
 			 * @description
 			 * - reference to structuredClone elements of `value`;
-			 * - calling doesn't notify
+			 * - calling doesn't notify for changes;
 			 * @returns {Array<LISTARG>}
 			 */
 			get structuredClone() {

package/src/class/LitExp.mjs

@@ -12,6 +12,7 @@ import { TrySync } from '../function/TrySync.mjs';
  * >- destructuring is meant for extensive typehelper;
  * >- and destructuring can lead to unhandled error here and there;
  * >- therefore error as value is introduced to help to prevent error on runtime;
+ * - made primarily for generating string file, that are purely managed programatically;
  * @template {LitExpKeyType} KEYS
  */
 export class LitExp {
@@ -32,7 +33,7 @@ export class LitExp {
 	 * new RegExp(escapedLiteral, 'g');
 	 */
 	static escape = (string) => {
-		return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+		return string.replace(/[.*+?^${}()|[\]\\\]]/g, '\\$&');
 	};
 	/**
 	 * @description
@@ -131,7 +132,7 @@ export class LitExp {
 					throw new Error('string undefined');
 				}
 				if (i + 1 == stringsLength && string === '') {
-					result.push('(?:\\s+?|$)');
+					result.push('(?:\\s+?|;|,|$|)');
 				} else {
 					result.push(LitExp.escape(string));
 				}

package/src/class/Paths.mjs

@@ -1,7 +1,5 @@
 // @ts-check
 
-import { relative } from 'node:path';
-
 import { Console } from './Console.mjs';
 
 /**
@@ -25,15 +23,8 @@ export class Paths {
 	 * ```
 	 * - node/bun compatible:
 	 * ```js
-	 * process?.env?.INIT_CWD ?? process?.cwd()
-	 * ```
-	 * - deno: need for `deno run --allow-env --allow-read your_script.ts`:
-	 * ```js
-	 * Deno.env.get("INIT_CWD") ?? Deno.cwd()
-	 * ```
-	 * - pkg:
-	 * ```js
-	 * __dirname
+	 * import process from 'node:process';
+	 * process.env.INIT_CWD ?? process.cwd()
 	 * ```
 	 * - other: you need to check your JSRuntime for the rootPath reference;
 	 * @example

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

@@ -36,14 +36,10 @@ export class SafeExit {
 	 *  ['SIGINT', 'SIGTERM']
 	 * ```
 	 * @param {()=>void} options.terminator
-	 * - standard node/bun:
+	 * - standard, process must be imported statically from 'node:process':
 	 * ```js
 	 * () => process.exit(0),
 	 * ```
-	 * - Deno:
-	 * ```js
-	 * () => Deno.exit(0),
-	 * ```
 	 * @param {(eventName:string)=>void} [options.listener]
 	 * - default value
 	 * ```js
@@ -52,34 +48,21 @@ export class SafeExit {
 	 * 		SafeExit.instance.exiting.correction(true);
 	 * 		Console.log(`safe exit via "${eventName}"`);
 	 * 	});
-	 * };
-	 * ```
-	 * - example Deno:
-	 * ```js
-	 * (eventName) => {
-	 * 	const sig = Deno.signal(eventName);
-	 * 		for await (const _ of sig) {
-	 * 			exiting.correction(true);
-	 * 			sig.dispose();
-	 * 			Console.log(`safe exit via "${eventName}"`);
-	 * 		}
 	 * }
 	 * ```
 	 * - 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';
 	 *
 	 * new SafeExit({
 	 * 	eventNames: ['SIGINT', 'SIGTERM', ...eventNames],
-	 * 	terminator : () => process.exit(0), // OR on deno () => Deno.exit(0),
-	 * 	// optional deno example
+	 * 	terminator : () => process.exit(0),
 	 * 	listener : (eventName) => {
-	 * 		const sig = Deno.signal(eventName);
-	 * 			for await (const _ of sig) {
-	 * 				exiting.correction(true);
-	 * 				sig.dispose();
+	 * 			process.once(eventName, function () {
+	 * 				SafeExit.instance?.exiting.correction(true);
 	 * 				Console.log(`safe exit via "${eventName}"`);
-	 * 			}
+	 * 			});
 	 * 	}
 	 * });
 	 */
@@ -157,7 +140,7 @@ export class SafeExit {
 	 * 	// code
 	 * }
 	 * SafeExit.instance.addCallback(exitCallback);
-	 *
+	 * // somewhere else
 	 * SafeExit.instance.removeCallback(exitCallback);
 	 */
 	removeCallback = (cb) => {

package/src/class/Setup.mjs

@@ -20,15 +20,12 @@ export class Setup {
 	 * 	// 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;
 	 * 	eventNames: ['SIGINT', 'SIGTERM', ...eventNames],
-	 * 	terminator = () => process.exit(0), // OR on deno () => Deno.exit(0),
-	 * 	// optional deno example
-	 * 	listener = (eventName) => {
-	 * 		const sig = Deno.signal(eventName);
-	 * 			for await (const _ of sig) {
-	 * 				exiting.correction(true);
-	 * 				sig.dispose();
+	 * 	terminator : () => process.exit(0),
+	 * 	listener : (eventName) => {
+	 * 			process.once(eventName, function () {
+	 * 				SafeExit.instance?.exiting.correction(true);
 	 * 				Console.log(`safe exit via "${eventName}"`);
-	 * 			}
+	 * 			});
 	 * 	}
 	 * });
 	 */

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,7 +3,9 @@
 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';
 import { SafeExit } from '../class/SafeExit.mjs';
@@ -36,21 +38,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 +204,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 +249,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 +262,6 @@ export class JSautoDOC {
 			if (trueContent === undefined) {
 				return;
 			}
-
 			const hasNoAutoDoc = /\/\*\*[\s\*]*?@noautodoc[\s\*]*?\*\//.test(trueContent);
 			if (hasValidExportObject) {
 				mjsMain.push(
@@ -398,7 +403,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/correctBeforeParse.mjs

@@ -1,9 +1,9 @@
 // @ts-check
 
+import { readFile, writeFile } from 'node:fs/promises';
 import { basename } from 'node:path';
 
 import { TryAsync } from '../function/TryAsync.mjs';
-import { readFile, writeFile } from 'node:fs/promises';
 import { Console } from '../class/Console.mjs';
 import { Timeout } from '../function/Timeout.mjs';
 import { LitExp } from '../class/LitExp.mjs';

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"
+	]
 }