vivth 1.4.9 → 1.5.0

package/src/bundler/adds/ToBundledJSPlugin.mjs

@@ -1,90 +1,151 @@
 // @ts-check
 
-import { basename, extname } from 'node:path';
+import { basename, dirname, extname, relative, resolve } from 'node:path';
 import { readFile } from 'node:fs/promises';
 
 import { CreateESPlugin } from '../CreateESPlugin.mjs';
 import { GetNamedImportAlias } from '../../function/GetNamedImportAlias.mjs';
 import { FileSafe } from '../../class/FileSafe.mjs';
+import { Paths } from '../../class/Paths.mjs';
+import { PipeSync } from '../../function/PipeSync.mjs';
+import { VivthUnBundledCodeBlock } from '../../common/VivthUnBundledCodeBlock.mjs';
+import { Preferrence } from '../../common/Preferrence.mjs';
+import { isModuleTheBundledVersion } from './isModuleTheBundledVersion.mjs';
 
 /**
+ * @param {string} filePath
  * @param {string} originalContent_
  * @returns {string}
  */
-export const removeVivthDevCodeBlock = (originalContent_) => {
-	const alias = GetNamedImportAlias(originalContent_, 'Dev', 'vivth');
+export const commonContentFixesBundled = (filePath, originalContent_) => {
+	return PipeSync(
+		originalContent_,
+		(content) => {
+			for (let i = 0; i < PathFStoBefixed.length; i++) {
+				const stringToBeFixed = PathFStoBefixed[i];
+				if (!stringToBeFixed) {
+					continue;
+				}
+				content = fixPathFS(filePath, content, stringToBeFixed);
+			}
+			return content;
+		},
+		(content) => removeVivthUnBundledCodeBlock(content),
+	);
+};
+
+const PathFStoBefixed = ['Bundles', 'Dir', 'File'];
+
+/**
+ * Rewrite all relative string arguments inside `PathFS` calls.
+ * @param {string} currentFilePath - Absolute path of the current file.
+ * @param {string} originalContent_ - The source code to scan and rewrite.
+ * @param {string} mode
+ * @returns {string} - Modified source code with paths rewritten.
+ */
+const fixPathFS = (currentFilePath, originalContent_, mode) => {
+	const alias = GetNamedImportAlias(originalContent_, `PathFS${mode}`, 'vivth/node');
+	if (!alias) {
+		return originalContent_;
+	}
+	// Regex: match alias("...") or alias('...'), enforcing same quote style
+	const callRegex = new RegExp(`${alias}\\.(vivth[\\w]+)\\((['"])(\\.?\\.?\\/[^'"]*)\\2`, 'g');
+	let modified = originalContent_;
+	modified = modified.replace(callRegex, (full, methodName, quote, relPath) => {
+		if (!relPath) {
+			return full;
+		}
+		const absPath = resolve(dirname(currentFilePath), relPath);
+		const relToRoot = relative(Paths.root, absPath);
+		const normalized = Paths.normalize(relToRoot);
+		return `${alias}.${methodName}(${quote}${normalized}${quote}`;
+	});
+	return modified;
+};
+
+/**
+ * @param {string} originalContent_
+ * @returns {string}
+ */
+const removeVivthUnBundledCodeBlock = (originalContent_) => {
+	const alias = GetNamedImportAlias(originalContent_, 'BundledV', 'vivth/neutral');
 	if (!alias) {
 		return originalContent_;
 	}
 	const regex = new RegExp(
-		`(\\s*${alias}.vivthDevCodeBlock\\s*\\([\\s\\S]*?,\\s*['"]vivthDevCodeBlock['"]\\s*\\)(?:\\;|,|))`,
-		'g'
+		`(\\s*${alias}.${VivthUnBundledCodeBlock}\\s*\\([\\s\\S]*?['"]${VivthUnBundledCodeBlock}['"]\\s*\\)(?:\\;|,))`,
+		'g',
 	);
 	return originalContent_.replace(regex, '');
 };
 
 /**
  * @description
- * - generate `esbuild.Plugin` for changing dev time file into runtime file;
+ * - generate `esbuild.Plugin` for changing unbundled time file into runtime file;
  * - on using esbuild with this plugin, it will:
  * >- replace any module that have similiar file name but ended with Bundled(before extname);
- * >- works on `.mts`|`.ts`|`.mjs`|`.cjs`|`.js`;
- * >- `${fileName}.mjs` -> seek for and use `${fileName}Bundled.mjs`, if not found use `${fileName}.mjs`;
- * >- removes `Dev.vivthDevCodeBlock` code block;
+ * >- works on `.mts`|`.ts`|`.mjs`|`.js`;
+ * >- `${fileName}.mjs` -> seek for and use `${fileName}.bundled.mjs`, if not found use `${fileName}.mjs`;
+ * >- removes `BundledV.vivthUnBundledCodeBlock` code block;
  * @param {string} includedInPath
  * - is generalized path, you can freely uses forward or backward slash;
  * @returns {ReturnType<CreateESPlugin>}
  * @example
- * import { ToBundledJSPlugin } from 'vivth';
+ * import { ToBundledJSPlugin } from 'vivth/node';
  *
  * export const myBundledPlugin = ToBundledJSPlugin('/myProjectName/src/');
  */
 export function ToBundledJSPlugin(includedInPath) {
 	const filter = new RegExp(includedInPath.replace(/[\\/]/g, '[\\\\/]'), '');
-	return CreateESPlugin(`ToBundledJSPlugin:${includedInPath}`, (build) => {
-		build.onLoad({ filter }, async (args) => {
-			const filePath = args.path;
-			const fileExt = extname(filePath);
-			/**
-			 * @type {'js'|'ts'|undefined}
-			 */
-			let loader;
-			switch (fileExt) {
-				case '.mts':
-				case '.ts':
-					loader = 'ts';
-					break;
-				case '.mjs':
-				case '.cjs':
-				case '.js':
-					loader = 'js';
-					break;
-			}
-			/**
-			 * @type {ReturnType<Parameters<import('esbuild').PluginBuild["onLoad"]>[1]>}
-			 */
-			const ret = { loader };
-			if (loader === undefined || filePath.endsWith(`Bundled${fileExt}`)) {
-				const originalContent = (await readFile(filePath)).toString('utf-8');
-				ret.contents = removeVivthDevCodeBlock(originalContent);
+	return CreateESPlugin(
+		`ToBundledJSPlugin:${includedInPath}`,
+		({
+			/** */
+			onLoad,
+		}) => {
+			onLoad({ filter }, async ({ path: filePath }) => {
+				const extension = extname(filePath);
+				/**
+				 * @type {'js'|'ts'|undefined}
+				 */
+				let loader;
+				switch (extension) {
+					case '.mts':
+					case '.cts':
+					case '.ts':
+						loader = 'ts';
+						break;
+					case '.mjs':
+					case '.js':
+						loader = 'js';
+						break;
+				}
+				/**
+				 * @type {ReturnType<Parameters<import('esbuild').PluginBuild["onLoad"]>[1]>}
+				 */
+				const ret = { loader };
+				if (loader === undefined || isModuleTheBundledVersion(filePath, extension)) {
+					const originalContent = (await readFile(filePath)).toString(Preferrence.encoding);
+					ret.contents = commonContentFixesBundled(filePath, originalContent);
+					return ret;
+				}
+				const originalBaseName = basename(filePath);
+				const originalFileName = originalBaseName.replace(extension, '');
+				const realRef = `${originalFileName}.bundled`;
+				const bundledFile = filePath.replace(
+					new RegExp(`${originalBaseName}\$`.replace('.', '\\.'), ''),
+					`${realRef}${extension}`,
+				);
+				const isExist = await FileSafe.exist(bundledFile);
+				if (!isExist) {
+					const originalContent = (await readFile(filePath)).toString(Preferrence.encoding);
+					ret.contents = commonContentFixesBundled(filePath, originalContent);
+					return ret;
+				}
+				const originalContent = (await readFile(bundledFile)).toString(Preferrence.encoding);
+				ret.contents = commonContentFixesBundled(filePath, originalContent);
 				return ret;
-			}
-			const originalBaseName = basename(filePath);
-			const originalFileName = originalBaseName.replace(fileExt, '');
-			const realRef = `${originalFileName}Bundled`;
-			const bundledFile = filePath.replace(
-				new RegExp(`${originalBaseName}\$`.replace('.', '\\.'), ''),
-				`${realRef}${fileExt}`
-			);
-			const [, error] = await FileSafe.exist(bundledFile);
-			if (error) {
-				const originalContent = (await readFile(filePath)).toString('utf-8');
-				ret.contents = removeVivthDevCodeBlock(originalContent);
-				return ret;
-			}
-			const originalContent = (await readFile(bundledFile)).toString('utf-8');
-			ret.contents = removeVivthDevCodeBlock(originalContent);
-			return ret;
-		});
-	});
+			});
+		},
+	);
 }

package/src/bundler/adds/autoExternalize.mjs

@@ -0,0 +1,81 @@
+// @ts-check
+
+import { resolve, relative } from 'node:path';
+
+import { Paths } from '../../class/Paths.mjs';
+import { CreateESPlugin } from '../CreateESPlugin.mjs';
+import { onEndEsBuildErrorLogger } from './onEndEsBuildErrorLogger.mjs';
+import { LastEditedUnix } from './LastEditedUnix.mjs';
+import { Console } from '../../class/Console.mjs';
+import { ForOfSync } from '../../function/ForOfSync.mjs';
+import { FileSafe } from '../../class/FileSafe.mjs';
+import { resolveJSDependencyPath } from './resolveJSDependencyPath.mjs';
+
+/**
+ * @import {Plugin} from 'esbuild'
+ */
+
+/**
+ * @param {string} path
+ * @param {string} targetPath
+ * @param {string} watchPath
+ * @param {string} mapToPath
+ * @param {Map<string, Set<string>>} depMap
+ * @param {Map<string, () => Promise<any>>} esbuildPathRebuild
+ * @returns {Plugin}
+ */
+export const autoExternalize = (
+	path,
+	targetPath,
+	watchPath,
+	mapToPath,
+	depMap,
+	esbuildPathRebuild,
+) => {
+	return CreateESPlugin('JSDirMapper:auto-externalize', ({ onResolve, onEnd }) => {
+		onResolve({ filter: /^\.{1,2}\// }, async ({ resolveDir, path: pathSpecifier }) => {
+			const fullPath = Paths.normalize(resolve(resolveDir, pathSpecifier));
+			if (await resolveJSDependencyPath(fullPath)) {
+				return null;
+			}
+			const runtimePath = fullPath.replace(watchPath, mapToPath);
+			const transpiledModuleRuntimePath = await FileSafe.exist(`${runtimePath}.mjs`);
+			if (!fullPath.endsWith('.mjs') && transpiledModuleRuntimePath) {
+				pathSpecifier = `${pathSpecifier}.mjs`;
+			}
+			const rel = Paths.normalize(relative(watchPath, fullPath));
+			if (rel.startsWith('../')) {
+				return null;
+			}
+			if (!depMap.has(fullPath)) {
+				depMap.set(fullPath, new Set());
+			}
+			depMap.get(fullPath)?.add(path);
+			const resolvedPath = `${pathSpecifier}?t=${await LastEditedUnix(fullPath)}`;
+			return { external: true, path: resolvedPath };
+		});
+		onEnd(async ({ errors: errorsBuild }) => {
+			if (errorsBuild.length) {
+				onEndEsBuildErrorLogger(errorsBuild);
+				return;
+			}
+			Console.info(
+				{
+					JSDirMapper: `✅ Successfully Bundle'${path}' 👉 '${targetPath}'`,
+				},
+				{
+					now: true,
+				},
+			);
+			const importers = depMap.get(path);
+			if (!importers) {
+				return;
+			}
+			await Promise.all(
+				ForOfSync(importers, async (importer) => {
+					await esbuildPathRebuild.get(importer)?.();
+				})[0],
+			);
+		});
+	});
+};

package/src/bundler/adds/emptyBufferValue.mjs

@@ -0,0 +1,5 @@
+// @ts-check
+
+export const emptyBufferValue = () => {
+	return Buffer.from([]);
+};

package/src/bundler/adds/isModuleTheBundledVersion.mjs

@@ -0,0 +1,10 @@
+// @ts-check
+
+/**
+ * @param { string } path
+ * @param { string } ext
+ * @returns { boolean }
+ */
+export const isModuleTheBundledVersion = (path, ext) => {
+	return path.endsWith(`.bundled${ext}`);
+};

package/src/bundler/adds/onEndEsBuildErrorLogger.mjs

@@ -0,0 +1,34 @@
+// @ts-check
+
+import { Console } from '../../class/Console.mjs';
+import { IsStringLooksLikeAPath } from '../../function/IsStringLooksLikeAPath.mjs';
+
+/**
+ * @param {import('esbuild').Message[]} errorData
+ * @returns { void }
+ */
+export const onEndEsBuildErrorLogger = (errorData) => {
+	const errorLog = {
+		...errorData[0],
+		suggestion: ['modify `FileSelfMapper` constructor `argument[1].esbuild`'],
+	};
+	const errorText = errorData[0]?.text;
+	const match = errorText?.toLocaleLowerCase().match(/could not resolve\s+"([^"]+)"/i);
+	if (match) {
+		const [, lib] = match;
+		if (IsStringLooksLikeAPath(lib ?? '')) {
+			Object.assign(errorLog, {
+				message: `'${lib}' doesn't exist`,
+			});
+		} else {
+			Object.assign(errorLog, {
+				platformSuggestion: {
+					node: `add esbuild.platform:'node' AND add '${lib}' into esbuild.external`,
+					browser: `add esbuild.platform:'browser'`,
+				},
+			});
+		}
+	}
+	Console.error(errorLog, { now: true });
+	return;
+};

package/src/bundler/adds/resolveJSDependencyPath.mjs

@@ -0,0 +1,17 @@
+// @ts-check
+
+import { extname } from 'node:path';
+import { FileSafe } from '../../class/FileSafe.mjs';
+
+/**
+ * @param {string} jspath
+ * @returns {Promise<boolean>}
+ */
+export const resolveJSDependencyPath = async (jspath) => {
+	const ext = extname(jspath);
+	if (ext !== '.js') {
+		return false;
+	}
+	const isExist = await FileSafe.exist(jspath.replace(/.js$/g, '.as.ts'));
+	return isExist;
+};

package/src/class/AwaitSignal.mjs

@@ -0,0 +1,119 @@
+// @ts-check
+
+import { IsInstanceOf } from '../function/IsInstanceOf.mjs';
+import { TryAsync } from '../function/TryAsync.mjs';
+import { Console } from './Console.mjs';
+import { Effect } from './Effect.mjs';
+import { Signal } from './Signal.mjs';
+
+/**
+ * @typedef {import('../typehints/VivthCleanup.mjs').VivthCleanup} VivthCleanup
+ */
+
+/**
+ * @description
+ * - `Signal` to unwrap `Promise`;
+ * - useful to create underlying mechanism for something like react `Suspense` component;
+ * - auto queued for last unwrap request;
+ * @template {any} VALUE
+ * @template {any[]} ARGS
+ * @extends {Signal<VALUE|Promise<VALUE>|Error>}
+ * @implements {VivthCleanup}
+ * @example
+ * import { AwaitSignal, Effect } from 'vivth/neutral'
+ * const bigAwaitSignal = new AwaitSignal(fetch('../SomethingReallyBig'));
+ * new Effect(async({ subscribe })=>{
+ * 	const myBigLoadProgress = subscribe(bigAwaitSignal).value;
+ * 	const isError = IsInstanceOf(myBigLoadProgress, Error);
+ * 	if(isError){
+ * 		// handle error here
+ * 		return;
+ * 	}
+ * 	const isAPromise = IsInstanceOf(myBigLoadProgress, Promise);
+ * 	if(isAPromise){
+ * 		// handle suspense here;
+ * 		return;
+ * 	}
+ * 	// handle ready state here;
+ * })
+ */
+export class AwaitSignal extends Signal {
+	/**
+	 * @override
+	 */
+	vivthCleanup = async () => {
+		this.#unwrapper.vivthCleanup();
+		this.remove.ref();
+	};
+	/**
+	 * @type {number}
+	 */
+	#latestPromise = Date.now();
+	/**
+	 * @param {(...args:ARGS)=>Promise<VALUE>} callback
+	 * @param {ARGS} firstCallArguments
+	 */
+	constructor(callback, ...firstCallArguments) {
+		super(callback(...firstCallArguments), ({ timeStamp, value }) => {
+			if (!IsInstanceOf(value, Promise)) {
+				return;
+			}
+			this.#latestPromise = timeStamp;
+		});
+		this.#callback = callback;
+		this.#unwrapper = new Effect(async ({ subscribe, isLastCalled }) => {
+			const latestPromise = this.#latestPromise;
+			const currentValue = subscribe(this).value;
+			if (!IsInstanceOf(currentValue, Promise) || !(await isLastCalled())) {
+				return;
+			}
+			const [newValue, errorUnwrappingPromise] = await TryAsync(async () => {
+				return await currentValue;
+			});
+			if (latestPromise !== this.#latestPromise) {
+				return;
+			}
+			if (!errorUnwrappingPromise) {
+				super.value = newValue;
+				return;
+			}
+			Console.error({ errorUnwrappingPromise });
+			super.value = errorUnwrappingPromise;
+		});
+	}
+	#unwrapper;
+	/**
+	 * @override
+	 * @param {VALUE|Promise<VALUE>|Error} _newValue
+	 */
+	set value(_newValue) {
+		Console.warn({ _newValue, AwaitSignalValueSetter: 'are not to be used' });
+	}
+	/**
+	 * @override
+	 * @returns {VALUE|Promise<VALUE>|Error}
+	 */
+	get value() {
+		return super.value;
+	}
+	/**
+	 * @type {(...args:ARGS)=>Promise<VALUE>}
+	 */
+	#callback;
+	retryCount = 0;
+	/**
+	 * @param {number} maxRetries
+	 * - `0` for no limit;
+	 * @param {ARGS} args
+	 * - integer of retryCount;
+	 */
+	retry = (maxRetries, ...args) => {
+		if (maxRetries !== 0 || ++this.retryCount > maxRetries) {
+			Console.error({
+				AwaitSignal: { callback: this.#callback, retryCount: maxRetries },
+			});
+			return;
+		}
+		super.value = this.#callback(...args);
+	};
+}

package/src/class/Console.mjs

@@ -15,15 +15,33 @@ export class Console {
 			error: '\x1b[31m', // red
 		},
 	};
+	/**
+	 * @param {any} data
+	 * @param {import("../typehints/ConsoleAdditionalSettingType.mjs").ConsoleAdditionalSettingType} args
+	 * @return {object}
+	 */
+	static #addArgsHandler = (data, { now: now_ }) => {
+		const obj = { message: data };
+		if (now_) {
+			Object.assign(obj, { now: Date.now() });
+		}
+		return obj;
+	};
 	/**
 	 * @param {string} prefix
 	 * @param {'log'|'info'|'error'|'warn'} mode
 	 * @param {any} data
+	 * @param {import("../typehints/ConsoleAdditionalSettingType.mjs").ConsoleAdditionalSettingType} [addArgs]
 	 * @returns {void}
 	 */
-	static #call = (prefix, mode, data) => {
+	static #call = (prefix, mode, data, addArgs) => {
+		if (addArgs) {
+			data = Console.#addArgsHandler(data, addArgs);
+		}
 		const fn = console[mode];
-		if (typeof fn !== 'function') return;
+		if (typeof fn !== 'function') {
+			return;
+		}
 
 		const color = Console.#ansi.colors[mode] || '';
 		const styledPrefix = `${color}${Console.#ansi.bold}${prefix} ${mode.toUpperCase()}:${
@@ -35,57 +53,61 @@ export class Console {
 	/**
 	 * @description
 	 * @param {any} data
+	 * @param {import("../typehints/ConsoleAdditionalSettingType.mjs").ConsoleAdditionalSettingType} [addArgs]
 	 * @returns {void}
 	 * @example
-	 * import { Console } from 'vivth';
+	 * import { Console } from 'vivth/neutral';
 	 *
 	 * Console.log({
 	 * 	hello: 'world!!',
 	 * });
 	 */
-	static log = (data) => {
-		return Console.#call('🟢', 'log', data);
+	static log = (data, addArgs) => {
+		return Console.#call('🟢', 'log', data, addArgs);
 	};
 	/**
 	 * @description
 	 * @param {any} data
+	 * @param {import("../typehints/ConsoleAdditionalSettingType.mjs").ConsoleAdditionalSettingType} [addArgs]
 	 * @returns {void}
 	 * @example
-	 * import { Console } from 'vivth';
+	 * import { Console } from 'vivth/neutral';
 	 *
 	 * Console.info({
 	 * 	hello: 'world!!',
 	 * });
 	 */
-	static info = (data) => {
-		return Console.#call('🔵', 'info', data);
+	static info = (data, addArgs) => {
+		return Console.#call('🔵', 'info', data, addArgs);
 	};
 	/**
 	 * @description
 	 * @param {any} data
+	 * @param {import("../typehints/ConsoleAdditionalSettingType.mjs").ConsoleAdditionalSettingType} [addArgs]
 	 * @returns {void}
 	 * @example
-	 * import { Console } from 'vivth';
+	 * import { Console } from 'vivth/neutral';
 	 *
 	 * Console.warn({
 	 * 	hello: 'world!!',
 	 * });
 	 */
-	static warn = (data) => {
-		return Console.#call('🟠', 'warn', data);
+	static warn = (data, addArgs) => {
+		return Console.#call('🟠', 'warn', data, addArgs);
 	};
 	/**
 	 * @description
 	 * @param {any} data
+	 * @param {import("../typehints/ConsoleAdditionalSettingType.mjs").ConsoleAdditionalSettingType} [addArgs]
 	 * @returns {void}
 	 * @example
-	 * import { Console } from 'vivth';
+	 * import { Console } from 'vivth/neutral';
 	 *
 	 * Console.error({
 	 * 	hello: 'world!!',
 	 * });
 	 */
-	static error = (data) => {
-		return Console.#call('🔴', 'error', data);
+	static error = (data, addArgs) => {
+		return Console.#call('🔴', 'error', data, addArgs);
 	};
 }

package/src/class/DataLog.mjs

@@ -0,0 +1,29 @@
+// @ts-check
+
+/**
+ * @description
+ * - class helper for signal performant logging, more or less just for type hinting;
+ * - internally used as Signal value logging instance;
+ * @template {any} VALUE
+ */
+export class DataLog {
+	/**
+	 * @description
+	 * @param {VALUE} value
+	 */
+	constructor(value) {
+		this.value = value;
+	}
+	/**
+	 * @description
+	 * - data value;
+	 * @type {VALUE}
+	 */
+	value;
+	/**
+	 * @description
+	 * - occurence unix timestamp;
+	 * @type {number}
+	 */
+	timeStamp = Date.now();
+}