vivth 1.4.9 → 1.5.0

package/src/function/NewDynamicsExport.mjs

@@ -0,0 +1,312 @@
+// @ts-check
+
+import { extname, join, relative } from 'node:path';
+
+import { lookup } from 'mime-types';
+
+import { FSDirArchWatcher } from '../class/FSDirArchWatcher.mjs';
+import { TryAsync } from './TryAsync.mjs';
+import { Console } from '../class/Console.mjs';
+import { LastEditedUnix } from '../bundler/adds/LastEditedUnix.mjs';
+import { ForEach } from '../class/ForEach.mjs';
+import { Paths } from '../class/Paths.mjs';
+import { ForOfSync } from './ForOfSync.mjs';
+import { FileSafe } from '../class/FileSafe.mjs';
+import { Prettivy } from '../class/Prettivy.mjs';
+
+/**
+ * @description
+ * generate generator watcher to `Dynamics`;
+ * 1) `./dynamics`: directory;
+ * 2) `./dynamics/**[blank]/*`(except 3)): watched source for 3);
+ * 3) `./dynamics/Dynamics.mjs`: collection of `modules`|`css`|`commonFile`(with `mimeTypes`);
+ * - this module assumes [Paths](#paths) to be already instantiated;
+ * @param {Object} options
+ * @param {string} options.rootPath
+ * - relative path to pseudo root;
+ * @param {number} [options.debounce]
+ * @param {boolean} [options.useFetchForAssets]
+ * - default: `true`;
+ * >- non js file will be `fetch`ed;
+ * - `false`;
+ * >- will use `import` instead;
+ * >- useful for vite Plugin;
+ * @param {import('chokidar').ChokidarOptions} [options.chokidarOptions]
+ * @param {(normalizedPath:string)=>boolean} [options.eachFilter]
+ * @returns {ReturnType<typeof TryAsync<FSDirArchWatcher<{ handler: string; mime: string | false; lastEditedUnixValue: number; }>>>}
+ */
+export function NewDynamicsExport(
+	/** */
+	{ rootPath, useFetchForAssets = true, debounce, chokidarOptions, eachFilter },
+) {
+	const dynamicImports = 'Dynamics';
+	const pathDynamic = Paths.diskAbsolute(join(rootPath, 'vivth', dynamicImports.toLowerCase()));
+	const pathGeneratedDynamicMapped = Paths.normalize(join(pathDynamic, `${dynamicImports}.mjs`));
+	const jsPrettivy = new Prettivy(pathGeneratedDynamicMapped);
+	return TryAsync(async () => {
+		return new FSDirArchWatcher([pathDynamic], {
+			debounce,
+			chokidarOptions,
+			each: async (eventName, path, stats) => {
+				if (eachFilter && !eachFilter(path)) {
+					throw '';
+				}
+				if (path === pathGeneratedDynamicMapped) {
+					throw '';
+				}
+				switch (eventName) {
+					case 'add':
+					case 'change':
+						if (!stats?.isFile()) {
+							throw '';
+						}
+						break;
+					default:
+						throw '';
+				}
+				const extension = extname(path);
+				switch (extension) {
+					case '.mts':
+					case '.mjs':
+						return {
+							handler: 'importable',
+							mime: lookup(path),
+							lastEditedUnixValue: await LastEditedUnix(path),
+						};
+					case '.ts':
+					case '.js':
+						Console.warn({
+							path,
+							extension,
+							message: `BrowserDirMapper /dynamics/ doesn't handle '${extension}' file, use '.mts' or '.mjs' instead`,
+						});
+						throw ``;
+					case '.wasm':
+						Console.warn({
+							path,
+							extension,
+							message: `BrowserDirMapper /dynamics/ doesn't handle '${extension}' file`,
+						});
+						throw ``;
+					default:
+						let mime;
+						switch (extension) {
+							case '.sass':
+							case '.scss':
+								throw '';
+							default:
+								mime = lookup(path);
+								break;
+						}
+						return {
+							handler: 'fetchable',
+							mime,
+							lastEditedUnixValue: await LastEditedUnix(path),
+						};
+				}
+			},
+			full: async ({ array }) => {
+				/**
+				 * @type {string[]}
+				 */
+				const content = [];
+				/**
+				 * @type {Map<string, string>}
+				 */
+				const types = new Map();
+				/**
+				 * @type {string[]}
+				 */
+				const cssList = [];
+				/**
+				 * @type {string[]}
+				 */
+				const withMimeNotCSS = [];
+				/**
+				 * @type {string[]}
+				 */
+				const moduleImports = [];
+				const cssMime = 'text/css';
+				ForEach.array(array, ([path, { handler, mime, lastEditedUnixValue }]) => {
+					if (!handler) {
+						return;
+					}
+					const relativePath = Paths.normalize(relative(pathDynamic, path));
+					switch (handler) {
+						case 'fetchable':
+							if (!mime) {
+								Console.error(
+									{
+										path,
+										message: `path is ignored due to, unable to check fetchable mime-type`,
+									},
+									{ now: true },
+								);
+							} else {
+								const typeName = `${mime.replace(/\//g, '_')}Mime`;
+								if (!types.has(mime)) {
+									let defintion;
+									if (mime !== cssMime) {
+										defintion = ` * @typedef { string & { __mime: '${mime}' } } ${typeName}`;
+									} else {
+										defintion = '';
+									}
+									types.set(mime, defintion);
+								}
+								let returnType = '';
+								if (mime !== cssMime) {
+									returnType = `/** @type { Promise<${typeName}> } */\n`;
+								}
+								let pseudoImporter;
+								let exprectingError = '';
+								if (mime === cssMime) {
+									if (useFetchForAssets) {
+										pseudoImporter = `return getCSS('./${relativePath}?t=${lastEditedUnixValue}');`;
+									} else {
+										pseudoImporter = `return getCSS('./${relativePath}',\n// @ts-expect-error\n import('./${relativePath}?inline'));`;
+									}
+									cssList.push(
+										`${returnType}get '${relativePath}'() {${exprectingError}${pseudoImporter}},`,
+									);
+								} else {
+									if (useFetchForAssets) {
+										pseudoImporter = `fetch_('./${relativePath}?t=${lastEditedUnixValue}');`;
+									} else {
+										pseudoImporter = `fetch_(import('./${relativePath}?raw'));`;
+									}
+									exprectingError = '\n// @ts-expect-error\n';
+									withMimeNotCSS.push(
+										`${returnType}get '${relativePath}'() {${exprectingError}return ${pseudoImporter}},`,
+									);
+								}
+							}
+							break;
+						case 'importable':
+							let version = '';
+							if (useFetchForAssets) {
+								version = ` /** @version ${lastEditedUnixValue} */`;
+							}
+							moduleImports.push(
+								`get '${relativePath.replace(/\.m/, '-').replace('-js', '')}'(){return import('./${relativePath}' ${version});},`,
+							);
+							break;
+					}
+				});
+				/**
+				 * @type {string[]}
+				 */
+				const mimeTypeHandlers = [];
+				ForOfSync(types, ([, fullTypeVal]) => {
+					if (!fullTypeVal) {
+						return;
+					}
+					mimeTypeHandlers.push(fullTypeVal);
+				});
+				const helpers = ['// @ts-check'];
+				if (withMimeNotCSS.length) {
+					mimeTypeHandlers.unshift('/**');
+					mimeTypeHandlers.push(' */');
+				}
+				if (cssList.length || withMimeNotCSS.length) {
+					if (types.has(cssMime)) {
+						helpers.push(`import { NewStyleSheetAsync } from 'vivth/neutral';`);
+					}
+					if (useFetchForAssets) {
+						helpers.push('const metaURL = import.meta.url;');
+						helpers.push(
+							`/** @param {string} url */\nconst fetch_ = (url) => fetch(new URL(url, metaURL).href).then((r) => r.text());`,
+						);
+					} else if (withMimeNotCSS.length) {
+						helpers.push(
+							`/** @param {Promise<string>} imported */\nconst fetch_ = (imported)=> imported.then((r) =>
+// @ts-expect-error
+r.default);`,
+						);
+					}
+					if (types.has(cssMime)) {
+						helpers.push(`const mappedCSS = new Map();`);
+						if (useFetchForAssets) {
+							helpers.push(`/** @type { (url: string) => Promise<CSSStyleSheet>} */
+const getCSS = (url) => {
+	if (!mappedCSS.has(url)) {
+		const sheetPromise = fetch_(url).then((text) => NewStyleSheetAsync(text));
+		mappedCSS.set(url, sheetPromise);
+	}
+	return mappedCSS.get(url);
+};
+`);
+						} else {
+							helpers.push(`/** @type { (url: string, imported:Promise<string>) => Promise<CSSStyleSheet>} */
+const getCSS = (url, imported) => {
+	if (!mappedCSS.has(url)) {
+		const sheetPromise = imported.then((text) =>
+			// @ts-expect-error
+			NewStyleSheetAsync(text.default));
+		mappedCSS.set(url, sheetPromise);
+	}
+	return mappedCSS.get(url);
+};
+`);
+						}
+					}
+				}
+				content.unshift(
+					...helpers,
+					mimeTypeHandlers.join('\n'),
+					`export const ${dynamicImports} = {`,
+				);
+				ForOfSync(
+					[
+						{ arr: moduleImports, name: 'modules' },
+						{ arr: cssList, name: 'css' },
+						{ arr: withMimeNotCSS, name: 'commons' },
+					],
+					({ arr, name }) => {
+						if (!arr.length) {
+							return;
+						}
+						content.push(`${name}:{`);
+						content.push(...arr);
+						content.push('},');
+					},
+				);
+				content.push('};');
+				const preFormated = `${content.join('\n')}\n`;
+				const [contentFormatted, errorFormatting] = await TryAsync(async () => {
+					return await jsPrettivy.format(preFormated);
+				});
+				if (errorFormatting) {
+					Console.error(
+						{
+							BrowserDirMapper: `❌ Error to formatting '${pathGeneratedDynamicMapped}'`,
+							errorFormatting,
+						},
+						{ now: true },
+					);
+					return;
+				}
+				const [, errorWritePrettifiedDynamicMapped] = await FileSafe.write(
+					pathGeneratedDynamicMapped,
+					contentFormatted,
+					{ encoding: 'utf-8' },
+				);
+				if (errorWritePrettifiedDynamicMapped) {
+					Console.error(
+						{
+							BrowserDirMapper: `❌ Error to write '${pathGeneratedDynamicMapped}'`,
+							errorWritePrettifiedDynamicMapped,
+						},
+						{ now: true },
+					);
+					return;
+				}
+				Console.info(
+					{
+						BrowserDirMapper: `✅ Successfully write '${pathGeneratedDynamicMapped}'`,
+					},
+					{ now: true },
+				);
+			},
+		});
+	});
+}

package/src/function/NewObjectWrapper.mjs

@@ -0,0 +1,14 @@
+// @ts-check
+
+/**
+ * @description
+ * - object creation mapper;
+ * @template {Object} OBJ
+ * @template {any} MODIFIED
+ * @param {OBJ} object
+ * @param {(obj:OBJ)=>MODIFIED} callback
+ * @returns {MODIFIED}
+ */
+export function NewObjectWrapper(object, callback) {
+	return callback(object);
+}

package/src/function/ObjectRegistrar.mjs

@@ -0,0 +1,23 @@
+// @ts-check
+
+/**
+ * @description
+ * - function helper to object registrar;
+ * @template {any[]} ARGS
+ * @template {any} OBJ
+ * @param {(...args:ARGS)=>OBJ} registrarCallback
+ * @returns {Parameters<typeof ObjectRegistrar<ARGS, OBJ>>[0]}
+ * @example
+ * import { ObjectRegistrar, Signal, ForOfSync } from 'vivth/neutral';
+ *
+ * const autoCleanedUpSignal = ObjectRegistrar(()=>{
+ *
+ * })
+ *
+ * const mySignal = autoCleanedUpSignal(1);
+ */
+export function ObjectRegistrar(registrarCallback) {
+	return (...obj) => {
+		return registrarCallback(...obj);
+	};
+}

package/src/function/ParseSQLFile.mjs

@@ -0,0 +1,129 @@
+// @ts-check
+
+import { basename, extname } from 'node:path';
+
+import { FileSafe } from '../class/FileSafe.mjs';
+import { TryAsync } from './TryAsync.mjs';
+import { readFile } from 'node:fs/promises';
+import { Preferrence } from '../common/Preferrence.mjs';
+import { LitExp } from '../class/LitExp.mjs';
+import { LazyFactory } from './LazyFactory.mjs';
+import { TrySync } from './TrySync.mjs';
+import { FactoryKey } from '../common/FactoryKey.mjs';
+import { ForOfSync } from './ForOfSync.mjs';
+import { Paths } from '../class/Paths.mjs';
+import { Console } from '../class/Console.mjs';
+
+const templater = LazyFactory(() => {
+	return TrySync(() => {
+		const temp = LitExp.prepare({
+			typeBrace0: /\/\*\s+/,
+			type: /[\w]+/,
+			typeBrace1: /\s+\*\/\s*?/,
+			name: /(?:\:|)[\w]+/,
+			closing: /[,\s;]/,
+		});
+		const [literalSQLTemplate, errorTemplating] = temp;
+		if (errorTemplating) {
+			throw errorTemplating;
+		}
+		return literalSQLTemplate`${'typeBrace0'}${'type'}${'typeBrace1'}${'name'}`;
+	});
+});
+
+/**
+ * @description
+ * - parse then generate file right next to said sql file;
+ * - this function assume `Paths` already instantiated;s
+ * @param {string} path
+ * @param {(
+ *  arg0:{input:Record<string, string>,output:Record<string, string>, sqlString:string}
+ * )=>
+ *  {ext:string, content:string}
+ * } [fileGenerator]
+ * - file string generator;
+ * - the default will generate mjs callback type, and sql string;
+ * >- `callback` type: basename + 'CBType';
+ * >- `sql` string: basename + 'SQL';
+ * @returns {ReturnType<typeof TryAsync<boolean>>}
+ */
+export async function ParseSQLFile(
+	path,
+	fileGenerator = ({ input, output, sqlString }) => {
+		const exportname = basename(path).replace(/\./g, '').replace(/sql$/, '');
+		const content = `// @ts-check
+/**
+ * @typedef {${JSON.stringify(input).replace(/"/g, '')}} INPUT
+ * @typedef {${JSON.stringify(output).replace(/"/g, '')}[]} RESPONSE
+ */
+/**
+ * @callback ${exportname}CBType
+ * @param {INPUT} input
+ * @returns {Promise<RESPONSE>} 
+ */
+export const ${exportname}SQL = \`${sqlString.replace(/\`/g, '\\`')}\`;
+`;
+		return { ext: '.mjs', content };
+	},
+) {
+	return await TryAsync(async () => {
+		path = Paths.diskAbsolute(path);
+		if (extname(path) !== '.sql') {
+			Console.warn(`'${path}' not an sql file`);
+			return false;
+		}
+		if (!(await FileSafe.exist(path))) {
+			throw `'${!(await FileSafe.exist(path))}' doesn't exist`;
+		}
+		templater[FactoryKey];
+		const [templateHandler, errorTemplating] = templater;
+		if (errorTemplating) {
+			throw { errorTemplating };
+		}
+		const sqlString = (await readFile(path, { encoding: Preferrence.encoding })).replace(
+			/\s+/g,
+			' ',
+		);
+		const [matchedAndGrouped, errorMatching] = templateHandler.evaluate.matchedAllAndGrouped(
+			sqlString,
+			{
+				flags: 'g',
+				whiteSpaceSensitive: false,
+			},
+		);
+		if (errorMatching) {
+			throw { errorMatching };
+		}
+		const {
+			result: { named },
+		} = matchedAndGrouped;
+		if (!Object.keys(named).length) {
+			throw { path, message: 'detected no input nor output' };
+		}
+		const res = { input: {}, output: {} };
+		ForOfSync(named, ({ type, name }) => {
+			if (name.startsWith(':')) {
+				name = name.replace(':', '').toString();
+				// @ts-expect-error
+				res.input[name] = type;
+			} else {
+				// @ts-expect-error
+				res.output[name] = type;
+			}
+		});
+		const { content, ext } = fileGenerator({ input: res.input, output: res.output, sqlString });
+		let extTrue = ext;
+		if (!ext.startsWith('.')) {
+			extTrue = `.${ext}`;
+		}
+		const pathMJS = `${path}${extTrue}`;
+		const [, errorWrite] = await FileSafe.write(pathMJS, content, {
+			encoding: Preferrence.encoding,
+		});
+		if (errorWrite) {
+			throw { errorWrite };
+		}
+		Console.info(`✅ Successfully generate type from '${path}' to '${pathMJS}'`);
+		return true;
+	});
+}

package/src/function/PipeAsync.mjs

@@ -0,0 +1,30 @@
+// @ts-check
+
+/**
+ * @description
+ * - create an async pipeline starting from an initial value;
+ * - every step must return the same type (VALUE), but may be sync or async.
+ * @template {any} VALUE
+ * @param {VALUE} intialValue
+ * @param {...((currentvalue:VALUE)=>VALUE|Promise<VALUE>)} pipeFunctions
+ * @returns {Promise<VALUE>}
+ * @example
+ * import { PipeAsync } from 'vivth/neutral';
+ *
+ * const res = await PipeAsync(
+ *  'intialValue', // res: Promise<"intialValue">
+ *  (val) => `${val}:1`, // res: Promise<"intialValue:1">
+ *  async (val) => `${val}:2`, // res: Promise<"intialValue:1:2">
+ *  (val) => `${val}:3` // res: Promise<"intialValue:1:2:3">
+ * );
+ */
+export async function PipeAsync(intialValue, ...pipeFunctions) {
+	for (let i = 0; i < pipeFunctions.length; i++) {
+		const function_ = pipeFunctions[i];
+		if (!function_) {
+			continue;
+		}
+		intialValue = await function_(intialValue);
+	}
+	return intialValue;
+}

package/src/function/PipeSync.mjs

@@ -0,0 +1,28 @@
+// @ts-check
+
+/**
+ * @description
+ * @template {any} VALUE
+ * @param {VALUE} intialValue
+ * @param {...((currentvalue:VALUE)=>VALUE)} pipeFunctions
+ * @returns {VALUE}
+ * @example
+ * import { PipeSync } from 'vivth/neutral';
+ *
+ * const res = PipeSync(
+ *  'intialValue', // res: "intialValue"
+ *  (val) => `${val}:1`, // res: "intialValue:1"
+ *  (val) => `${val}:2`, // res: "intialValue:1:2"
+ *  (val) => `${val}:3` // res: "intialValue:1:2:3"
+ * );
+ */
+export function PipeSync(intialValue, ...pipeFunctions) {
+	for (let i = 0; i < pipeFunctions.length; i++) {
+		const function_ = pipeFunctions[i];
+		if (!function_) {
+			continue;
+		}
+		intialValue = function_(intialValue);
+	}
+	return intialValue;
+}

package/src/function/SafeImport.mjs

@@ -0,0 +1,77 @@
+// @ts-check
+
+import { pathToFileURL } from 'node:url';
+
+import { GetRuntime } from './GetRuntime.mjs';
+import { ClearRequireCache } from './ClearRequireCache.mjs';
+import { Paths } from '../class/Paths.mjs';
+import { init } from 'import-without-cache';
+import { LazyFactory } from './LazyFactory.mjs';
+import { QChannel } from '../class/QChannel.mjs';
+import { PipeSync } from './PipeSync.mjs';
+
+let isInited = false;
+
+const q = LazyFactory(() => new QChannel('SafeImport'));
+
+/**
+ * @param {string} path
+ * @returns {string}
+ */
+const ifNodeThenCorrectPath = (path) => {
+	if (GetRuntime() !== 'node') {
+		return path;
+	}
+	return (path = pathToFileURL(path).href);
+};
+
+/**
+ * @param {string} path
+ * @returns {Promise<any>}
+ */
+const queuedCallback = async (path) => {
+	if (GetRuntime() === 'node' && !isInited) {
+		isInited = true;
+		init({ skipNodeModules: true });
+	}
+	ClearRequireCache(path);
+	const result = await import(
+		/** */
+		path,
+		{ with: { cache: 'no' } }
+	);
+	ClearRequireCache(path);
+	return result;
+};
+
+/**
+ * @description
+ * - import while imediately call clearing require caches;
+ * - `usecases`:
+ * >- long running process that need to prevent memory leak from uncleanable `cached import`;
+ * >- to simply import fresh everytime;
+ * - the imported module can then just be treated like any other variable, to only lived and tracked by variable reference only;
+ * - due to how `vivth/node.ClearRequireCache` works, parallel await (like using Promise.all, or not awaited until later) will be done squentially(if targetting the same path);
+ * @template { any } T
+ * - put the type
+ * @param {string} path
+ * - either absolute `diskAbsolutepath` or from `Paths.root`;
+ * @returns {ReturnType<typeof import('./TryAsync.mjs').TryAsync<T>>}
+ * @example
+ * // Paths.root/myscript.mjs
+ * import { SafeImport } from 'vivth/node';
+ *
+ * // add type with: import('vivth/neutral').SafeImportReturnType<import('./something.mjs')>
+ * const [importedModule, errorSafeImport] = await SafeImport('/absolute/path/from/Paths.root/something.mjs');
+ */
+export async function SafeImport(path) {
+	path = PipeSync(
+		/** */
+		Paths.diskAbsolute(path),
+		Paths.nativeSep,
+		ifNodeThenCorrectPath,
+	);
+	return await q.callback(path, async () => {
+		return await queuedCallback(path);
+	});
+}