vivth 1.4.10 → 1.5.1

package/src/{types → typehints}/DevTestCB.mjs

@@ -6,6 +6,6 @@
  * @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;
+ * @returns {{removeId:()=>void}}
+ * - calling `removeId` will remove this test from reports;
  */

package/src/typehints/EnvModeType.mjs

@@ -0,0 +1,6 @@
+// @ts-check
+
+/**
+ * - type helper for `EnvMode`;
+ * @typedef {'dev'|'prod'} EnvModeType
+ */

package/src/{types → typehints}/ListArg.mjs

@@ -2,5 +2,5 @@
 
 /**
  * - ListSignal argument type;
- * @typedef {Record<string, string>} ListArg
+ * @typedef {Record<string, any>} ListArg
  */

package/src/{types → typehints}/LitExpResultType.mjs

@@ -1,7 +1,7 @@
 // @ts-check
 
 /**
- * @template {import('./LitExpKeyType.mjs').LitExpKeyType} KEYS
+ * @template {import("./LitExpKeyType.mjs").LitExpKeyType} KEYS
  * @typedef {{result:{whole:string[], named:Array<Record<keyof KEYS, string>>},
  * regexp: RegExp}} LitExpResultType
  */

package/src/typehints/MonkeyPatchedType.mjs

@@ -0,0 +1,13 @@
+// @ts-check
+
+/**
+ * @description
+ * - type helper for `MonkeyPatch`;
+ * @template {any} ORIOBJ
+ * @typedef {ORIOBJ extends (...args: infer A) => infer R
+ *    ? (...args: A) => R
+ *    : ORIOBJ extends abstract new (...args: infer C) => infer I
+ *    ? abstract new (...args: C) => I
+ *    : any
+ * } MonkeyPatchedType
+ */

package/src/typehints/ParametersFollowingN.mjs

@@ -0,0 +1,8 @@
+/**
+ * @preserve
+ * @description
+ * - Drop the first N parameters from METHOD and return the rest;
+ * @template {(...args: any[]) => any} METHOD
+ * @template {number} N
+ * @typedef {import('./ParametersFollowingN.mts').ParametersFollowingN<N, METHOD>} ParametersFollowingN
+ */

package/src/typehints/ParametersFollowingN.mts

@@ -0,0 +1,17 @@
+/**
+ * Utility: build a tuple of length N filled with type T (default = any).
+ */
+export type TupleOfLength<N extends number, T = any, R extends any[] = []> = R['length'] extends N
+	? R
+	: TupleOfLength<N, T, [...R, T]>;
+
+/**
+ * @preserve
+ * @description
+ * - Drop the first N parameters from METHOD and return the rest;
+ * @template {(...args: any[]) => any} METHOD
+ * @template {number} N
+ * @[blank]typedef {import('./ParametersFollowingN.mts').ParametersFollowingN<N, METHOD>} ParametersFollowingN
+ */
+export type ParametersFollowingN<METHOD extends (...args: any[]) => any, N extends number> =
+	Parameters<METHOD> extends [...TupleOfLength<N>, ...infer Rest] ? Rest : [];

package/src/typehints/PrefixedKeysOf.mjs

@@ -0,0 +1,9 @@
+// @ts-check
+
+/**
+ * @description
+ * Define a type helper that extracts keys starting with a specific prefix
+ * @template {any} T
+ * @template {string} Prefix
+ * @typedef {Extract<keyof T, `${Prefix}${string}`>} PrefixedKeysOf
+ */

package/src/typehints/Runtime.mjs

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

package/src/typehints/SafeImportReturnType.mjs

@@ -0,0 +1,6 @@
+// @ts-check
+
+/**
+ * @template {any} IMPORTTARGET
+ * @typedef {Awaited<ReturnType<typeof import('../function/SafeImport.mjs').SafeImport<IMPORTTARGET>>>} SafeImportReturnType
+ */

package/src/typehints/StylePropRefType.mjs

@@ -0,0 +1,12 @@
+// @ts-expect-error
+
+/**
+ * @import {WC_StyleProp_bind} from '../web/bindings/WC_StyleProp_bind.mjs'
+ */
+
+/**
+ * @description
+ * - typehelper to constrict [StyleRef](#styleref) values;
+ * @template {string} STRTYPE
+ * @typedef {ReturnType<typeof WC_StyleProp_bind<STRTYPE>>} StylePropRefType
+ */

package/src/typehints/TemplateLiteralValueHandler.mjs

@@ -0,0 +1,14 @@
+// @ts-check
+
+/**
+ * - type helper for typing `vivth.TemplateLiteral`;
+ * @template {any} INPUTTYPE
+ * @callback TemplateLiteralValueHandler
+ * @param {Object} arg0
+ * @param {INPUTTYPE} arg0.currentValue
+ * @param {number} arg0.index
+ * @param {TemplateStringsArray} arg0.templateStringsArray
+ * @param {INPUTTYPE[]} arg0.valuesArrays
+ * @param {number} arg0.inputLength
+ * @returns {(string|Promise<string>)}
+ */

package/src/typehints/VLifecycleCallbacks.mjs

@@ -0,0 +1,10 @@
+// @ts-check
+
+/**
+ * @template {keyof HTMLElementTagNameMap} TAGNAME
+ * @typedef {Object} VLifecycleCallbacks
+ * @property {(this:HTMLElementTagNameMap[TAGNAME], defer:(onDisconnected:()=>void)=>void)=>void} [onConnected]
+ * @property {(this:HTMLElementTagNameMap[TAGNAME])=>void} [onDisconnected]
+ * @property {(this:HTMLElementTagNameMap[TAGNAME], defer:(onDisconnected:()=>void)=>void)=>void} [onAdopted]
+ * @property {(this:HTMLElementTagNameMap[TAGNAME], name:string, oldValue:string, newValue:string)=>void} [onAttributeChanged]
+ */

package/src/typehints/VivthCleanup.mjs

@@ -0,0 +1,14 @@
+// @ts-check
+
+/**
+ * @description
+ * - return type of object have this method;
+ * @typedef {{vivthCleanup: ()=>Promise<any>}} VivthCleanup
+ * - you can call:
+ * ```js
+ * something.vivthCleanup();
+ * ```
+ * >- class that implements this;
+ * >- function that have this as part of it's return;
+ * - to clean up that object, usually a long lived process;
+ */

package/src/web/BrowserDirMapper.mjs

@@ -0,0 +1,255 @@
+// @ts-check
+
+import { join, relative, dirname, resolve } from 'node:path';
+import { readFile } from 'node:fs/promises';
+
+import domino from 'domino';
+
+import { pluginVivthBundle } from '../bundler/adds/pluginVivthBundle.mjs';
+import { JSDirMapper } from '../bundler/JSDirMapper.mjs';
+import { FSDirArchWatcher } from '../class/FSDirArchWatcher.mjs';
+import { Paths } from '../class/Paths.mjs';
+import { FileSafe } from '../class/FileSafe.mjs';
+import { ForOfSync } from '../function/ForOfSync.mjs';
+import { Console } from '../class/Console.mjs';
+import { LastEditedUnix } from '../bundler/adds/LastEditedUnix.mjs';
+import { Prettivy } from '../class/Prettivy.mjs';
+import { SafeExit } from '../class/SafeExit.mjs';
+import { Preferrence } from '../common/Preferrence.mjs';
+import { NewDynamicsExport } from '../function/NewDynamicsExport.mjs';
+
+/**
+ * @typedef {import('../typehints/VivthCleanup.mjs').VivthCleanup} VivthCleanup
+ */
+
+/**
+ * @description
+ * - class helper to map dynamic mjs files;
+ * >- includes `mts` file too;
+ * @implements {VivthCleanup}
+ */
+export class BrowserDirMapper {
+	vivthCleanup = async () => {
+		SafeExit.instance?.removeCallback(this.#safeExitCallback);
+	};
+	/**
+	 * @type {Set<string>}
+	 */
+	#setOfHtmlPaths = new Set();
+	/**
+	 * @type {Map<string, number>}
+	 * - `fullpath`;
+	 * - `fullpath?t=${lastEditedUnixValue}`;
+	 */
+	#mapOfAssets = new Map();
+	/**
+	 * @description
+	 * - instantiate the mapper;
+	 * @param {Object} path
+	 * @param {string} path.watch
+	 * @param {string} path.mapTo
+	 * @param {(normalizedPath:string)=>boolean} [path.eachFilter]
+	 * @param {ConstructorParameters<typeof JSDirMapper>[1] &
+	 * 	{
+	 * 		debounce?:number,
+	 * 		chokidarOptions?:import('chokidar').ChokidarOptions
+	 * 	}
+	 * } options
+	 * @example
+	 * import { BrowserDirMapper } from 'vivth/node'
+	 * import { Paths, SafeExit, BrowserDirMapper } from 'vivth/neutral';
+	 *
+	 * new Paths({
+	 * 	root: process.env.INIT_CWD ?? process.cwd(),
+	 * });
+	 *
+	 * new SafeExit();
+	 *
+	 * new BrowserDirMapper(
+	 * 	{ mapTo: '/dist/', watch: '/src/' },
+	 * 	{
+	 * 		esbuild: {
+	 * 			buildOptions: {
+	 * 				minify: true,
+	 * 			},
+	 * 		},
+	 * 	},
+	 * );
+	 */
+	constructor({ watch, mapTo, eachFilter }, options) {
+		this.#start({ watch, mapTo, eachFilter }, options);
+		SafeExit.instance?.addCallback(this.#safeExitCallback);
+	}
+	#safeExitCallback = async () => {
+		await Promise.all(
+			ForOfSync(this.#setOfHtmlPaths, async (htmlTargetPath) => {
+				const prettivy = new Prettivy(htmlTargetPath);
+				const document = domino.createDocument(
+					(await readFile(htmlTargetPath, { encoding: Preferrence.encoding })) ?? '',
+				);
+				const assetSelector = '[src], link[href], [srcset], object[data]';
+				const elements = document.querySelectorAll(assetSelector);
+				const htmlDirname = dirname(htmlTargetPath);
+				await Promise.all(
+					ForOfSync(elements, async (element) => {
+						if (element.hasAttribute('src')) {
+							const currentValue = element.getAttribute('src') ?? '';
+							const assetPath = Paths.normalize(resolve(htmlDirname, currentValue));
+							if (this.#mapOfAssets.has(assetPath)) {
+								const timedAsset = `./${Paths.normalize(relative(htmlDirname, assetPath))}?t=${this.#mapOfAssets.get(assetPath)}`;
+								element.setAttribute('src', timedAsset);
+							}
+							return;
+						}
+						if (element.hasAttribute('srcset')) {
+							const currentValue = element.getAttribute('srcset') ?? '';
+							const assetPath = Paths.normalize(resolve(htmlDirname, currentValue));
+							if (this.#mapOfAssets.has(assetPath)) {
+								const timedAsset = `./${Paths.normalize(relative(htmlDirname, assetPath))}?t=${this.#mapOfAssets.get(assetPath)}`;
+								element.setAttribute('srcset', timedAsset);
+							}
+							return;
+						}
+						if (element.tagName.toLowerCase() === 'link' && element.hasAttribute('href')) {
+							const currentValue = element.getAttribute('href') ?? '';
+							const assetPath = Paths.normalize(resolve(htmlDirname, currentValue));
+							if (this.#mapOfAssets.has(assetPath)) {
+								const timedAsset = `./${Paths.normalize(relative(htmlDirname, assetPath))}?t=${this.#mapOfAssets.get(assetPath)}`;
+								element.setAttribute('href', timedAsset);
+							}
+							return;
+						}
+						if (element.tagName.toLowerCase() === 'object' && element.hasAttribute('data')) {
+							const currentValue = element.getAttribute('data') ?? '';
+							const assetPath = Paths.normalize(resolve(htmlDirname, currentValue));
+							if (this.#mapOfAssets.has(assetPath)) {
+								const timedAsset = `./${Paths.normalize(relative(htmlDirname, assetPath))}?t=${this.#mapOfAssets.get(assetPath)}`;
+								element.setAttribute('object', timedAsset);
+							}
+							return;
+						}
+					})[0],
+				);
+				const updatedHtml = document.documentElement.outerHTML;
+				const finalFileString = await prettivy.format(`<!DOCTYPE html>\n${updatedHtml}`);
+				await FileSafe.write(htmlTargetPath, finalFileString, { encoding: Preferrence.encoding });
+				Console.info(`✅ Successfully patch '${htmlTargetPath}' assets path`);
+			})[0],
+		);
+	};
+	/**
+	 * @param  {ConstructorParameters<typeof BrowserDirMapper>} args
+	 */
+	#start = async (...args) => {
+		const [
+			{ watch, mapTo, eachFilter },
+			{
+				esbuild: { buildOptions, watchOption },
+				asTsToMjsHandler,
+				chokidarOptions,
+				debounce,
+			},
+		] = args;
+		const watchPath = Paths.diskAbsolute(watch);
+		const mapToPath = Paths.diskAbsolute(mapTo);
+		const pathDynamic = Paths.normalize(join(watchPath, 'dynamics'));
+		const dynamicImports = 'Dynamics';
+		const pathGeneratedDynamicMapped = Paths.normalize(join(pathDynamic, `${dynamicImports}.mjs`));
+		await Promise.all(
+			ForOfSync([pathDynamic], async (path) => {
+				FileSafe.exist(path).then(async (isExist) => {
+					if (isExist) {
+						return;
+					}
+					await FileSafe.mkdir(path);
+				});
+			})[0],
+		);
+		const isExist = await FileSafe.exist(pathGeneratedDynamicMapped);
+		if (!isExist) {
+			const [, errorWriteInitialDynamicMapped] = await FileSafe.write(
+				pathGeneratedDynamicMapped,
+				'',
+				{
+					encoding: 'utf-8',
+				},
+			);
+			if (errorWriteInitialDynamicMapped) {
+				Console.error(
+					{
+						BrowserDirMapper: `❌ Error to write '${pathGeneratedDynamicMapped}'`,
+						errorWriteInitialDynamicMapped,
+					},
+					{ now: true },
+				);
+				return;
+			}
+		}
+		const [dynamicDirWatcher, errorCreatingDynamicsWatcher] = await NewDynamicsExport({
+			rootPath: watchPath,
+			debounce,
+			chokidarOptions,
+			eachFilter,
+		});
+		if (errorCreatingDynamicsWatcher) {
+			Console.error({ errorCreatingDynamicsWatcher });
+			return;
+		}
+		this.dynamicDirWatcher = dynamicDirWatcher;
+		dynamicDirWatcher.watcher._addIgnoredPath(pathGeneratedDynamicMapped);
+		this.dirMapper = new JSDirMapper(
+			{
+				mapTo: mapToPath,
+				watch: watchPath,
+				filter: async ({ source, eventName, target }) => {
+					switch (eventName) {
+						case 'add':
+							if (target.endsWith('.html')) {
+								this.#setOfHtmlPaths.add(target);
+							} else {
+								this.#mapOfAssets.set(target, await LastEditedUnix(source));
+							}
+							break;
+						case 'error':
+						case 'unlink':
+							if (target.endsWith('.html')) {
+								this.#setOfHtmlPaths.delete(target);
+							} else {
+								this.#mapOfAssets.delete(target);
+							}
+							break;
+					}
+					return { shouldProcessDefault: true };
+				},
+			},
+			{
+				esbuild: {
+					/** */
+					buildOptions: {
+						...buildOptions,
+						platform: 'browser',
+						plugins: [
+							/** */
+							pluginVivthBundle,
+							...(buildOptions.plugins ?? []),
+						],
+					},
+					watchOption,
+				},
+				asTsToMjsHandler,
+			},
+		);
+	};
+	/**
+	 * @description
+	 * - `FSDirArchWatcher` instance;
+	 * @type {FSDirArchWatcher<any>|undefined}
+	 */
+	dynamicDirWatcher;
+	/**
+	 * @description
+	 * - `JSDirMapper` instance;
+	 * @type {JSDirMapper<any>|undefined}
+	 */
+	dirMapper;
+}

package/src/web/EnsureValidTag.mjs

@@ -0,0 +1,5 @@
+/**
+ * @preserve
+ * @template {string} T
+ * @typedef {import('./EnsureValidTag.mts').EnsureValidTag<T>} EnsureValidTag
+ */

package/src/web/EnsureValidTag.mts

@@ -0,0 +1,10 @@
+import type { WC_TagName_type } from './common/WC_TagName_type.mts';
+
+// If T is valid, return T, otherwise return the literal string 'INVALID_TAG_NAME'
+/**
+ * @preserve
+ * @template {string} T
+ * @[blank]typedef {import('./EnsureValidTag.mts').EnsureValidTag<T>} EnsureValidTag
+ */
+export type EnsureValidTag<T extends string> =
+	WC_TagName_type<T> extends T ? T : 'INVALID_TAG_NAME';

package/src/web/ViteAddDynamics.mjs

@@ -0,0 +1,34 @@
+// @ts-check
+
+import { NewDynamicsExport } from '../function/NewDynamicsExport.mjs';
+
+/**
+ * @description
+ * - `vite.rollup/down` plugin abstraction for [NewDynamicsExport](#newdynamicsexport);
+ * @param {Parameters<typeof NewDynamicsExport>} args
+ * @returns {import('vite').PluginOption}
+ */
+export function ViteAddDynamics(...args) {
+	/**
+	 * @type {boolean|undefined}
+	 */
+	let started;
+	return {
+		name: 'vivth/web:AddDynamics',
+		apply: 'serve', // <-- only applies in dev server
+		async configureServer(devServer) {
+			if (started) {
+				return;
+			}
+			started = true;
+			args[0].useFetchForAssets = false;
+			const [dynamicExports, errorCreatingDynamicExport] = await NewDynamicsExport(...args);
+			if (errorCreatingDynamicExport) {
+				return;
+			}
+			devServer.httpServer?.on('close', () => {
+				dynamicExports.vivthCleanup();
+			});
+		},
+	};
+}

package/src/web/ViteGetAllHTMLFile.mjs

@@ -0,0 +1,97 @@
+// @ts-check
+
+import {
+	/** */
+	resolve,
+	relative,
+	extname,
+	// sep,
+} from 'node:path';
+import { readdirSync, statSync } from 'node:fs';
+import { Paths } from '../class/Paths.mjs';
+import { TryAsync } from '../function/TryAsync.mjs';
+import { Console } from '../class/Console.mjs';
+
+/**
+ * @param {string} currentDir
+ * @param {string} absoluteDist
+ * @param {string} absoluteDir
+ * @param {Record<string, any>} inputs
+ * @returns {void}
+ */
+function scanDir(currentDir, absoluteDist, absoluteDir, inputs) {
+	// Fast paths to ignore heavy directories right away at the top level
+	const dirName = currentDir.split('/').pop() ?? '.';
+	if (dirName === 'node_modules' || dirName.startsWith('.')) {
+		return;
+	}
+
+	const files = readdirSync(currentDir);
+
+	for (const file of files) {
+		const fullPath = Paths.normalize(resolve(currentDir, file));
+		const isDirectory = statSync(fullPath).isDirectory();
+
+		// Safely check if the directory is actually the build destination folder
+		if (fullPath === absoluteDist || fullPath.startsWith(absoluteDist + '/')) {
+			continue;
+		}
+
+		if (isDirectory) {
+			scanDir(fullPath, absoluteDist, absoluteDir, inputs);
+		} else if (extname(file) === '.html') {
+			const relativePath = Paths.normalize(relative(absoluteDir, fullPath));
+
+			// Vite requires forward slashes for internal module IDs/names
+			const urlKey = relativePath.replace(/[\\]/g, '/').replace(/\.html$/, '');
+
+			inputs[urlKey] = fullPath;
+		}
+	}
+}
+
+/**
+ * @description
+ * - Automatically discovers HTML files in a directory and maps them to input keys;
+ * - [Paths](#paths) needs to be instantiated;
+ * @param {string} dirPath - The absolute or relative path to the directory to scan.
+ * @param {string} distPath - The distribution folder name to exclude.
+ * @returns {import('vite').PluginOption}
+ */
+export function ViteGetAllHTMLFile(dirPath, distPath) {
+	return {
+		name: 'vivth/web:ViteGetAllHTMLFile',
+		async config({ build }) {
+			const buildPromise = TryAsync(async () => {
+				const absoluteDir = Paths.diskAbsolute(dirPath);
+				const absoluteDist = Paths.diskAbsolute(distPath);
+				const inputs = {};
+				try {
+					scanDir(absoluteDir, absoluteDist, absoluteDir, inputs);
+				} catch (error) {
+					throw { autoHtmlInputs: `Error scanning directory '${dirPath}'`, error };
+				}
+
+				build = build || {};
+				const optionsKey = build.rolldownOptions ? 'rolldownOptions' : 'rollupOptions';
+				build[optionsKey] = build[optionsKey] || {};
+				const input = build[optionsKey].input ?? {};
+				build[optionsKey].input = {
+					// @ts-expect-error
+					...input,
+					...inputs,
+				};
+
+				console.log('📦 Dynamic HTML Inputs Generated:', inputs);
+			});
+			const dynamicsHandler = TryAsync(async () => {});
+			const [[, errorBuild], [, errorDynamic]] = await Promise.all([buildPromise, dynamicsHandler]);
+			if (errorBuild) {
+				Console.error({ errorBuild });
+			}
+			if (errorDynamic) {
+				Console.error({ errorDynamic });
+			}
+		},
+	};
+}