vivth 1.4.10 → 1.5.0

package/src/function/TemplateLiteral.mjs

@@ -4,18 +4,19 @@ import { IsAsync } from './IsAsync.mjs';
 
 /**
  * @description
- * - function helper to create template literal with VALUEhandler to handle each values;
- * @template {(input:any)=>string|Promise<string>} VALUEHANDLER
- * @param {VALUEHANDLER} valueHandler
- * @param {(result:string)=>string} [postProcess]
+ * - function helper to create template literal with valueHandler to handle each values;
+ * @template {any} INPUTTYPE
+ * @template {string|Promise<string>} RET
+ * @param {import('../typehints/TemplateLiteralValueHandler.mjs').TemplateLiteralValueHandler<INPUTTYPE>} valueHandler
+ * @param {(result:string)=>(RET)} [postProcess]
  * @returns {(strings:TemplateStringsArray,
- * ...values:(Parameters<VALUEHANDLER>[0])[])=>
- * ReturnType<VALUEHANDLER>}
+ * ...values:(INPUTTYPE)[])=>
+ * RET}
  * @example
- * import { TemplateLiteral } form 'vivth';
+ * import { TemplateLiteral } from 'vivth/neutral';
  *
  * export const html = TemplateLiteral(
- *  (val) => val,
+ *  ({ ...datas }) => `my string`,
  *  // optional
  *  (res) => return window.body.innerHTML = res
  * );
@@ -26,36 +27,54 @@ import { IsAsync } from './IsAsync.mjs';
 export function TemplateLiteral(valueHandler, postProcess = undefined) {
 	if (IsAsync(valueHandler)) {
 		// @ts-expect-error
-		return async (strings, ...values) => {
+		return async (templateStringsArray, ...valuesArrays) => {
 			const result = [];
-			for (let i = 0; i < strings.length; i++) {
-				result.push(strings[i]);
-				if (i < values.length) {
-					const value = values[i];
-					if (value === undefined) {
+			const inputLength = templateStringsArray.length;
+			for (let index = 0; index < templateStringsArray.length; index++) {
+				result.push(templateStringsArray[index]);
+				if (index < valuesArrays.length) {
+					const currentValue = valuesArrays[index];
+					if (currentValue === undefined) {
 						continue;
 					}
-					result.push(await valueHandler(value));
+					result.push(
+						await valueHandler({
+							index,
+							currentValue,
+							valuesArrays,
+							templateStringsArray,
+							inputLength,
+						}),
+					);
 				}
 			}
 			const resTrue = result.join('');
 			if (!postProcess) {
 				return resTrue;
 			}
-			return postProcess(resTrue);
+			return await postProcess(resTrue);
 		};
 	}
 	// @ts-expect-error
-	return (strings, ...values) => {
+	return (templateStringsArray, ...valuesArrays) => {
 		const result = [];
-		for (let i = 0; i < strings.length; i++) {
-			result.push(strings[i]);
-			if (i < values.length) {
-				const value = values[i];
-				if (value === undefined) {
+		const inputLength = templateStringsArray.length;
+		for (let index = 0; index < templateStringsArray.length; index++) {
+			result.push(templateStringsArray[index]);
+			if (index < valuesArrays.length) {
+				const currentValue = valuesArrays[index];
+				if (currentValue === undefined) {
 					continue;
 				}
-				result.push(valueHandler(value));
+				result.push(
+					valueHandler({
+						index,
+						currentValue,
+						valuesArrays,
+						templateStringsArray,
+						inputLength,
+					}),
+				);
 			}
 		}
 		const resTrue = result.join('');

package/src/function/Timeout.mjs

@@ -7,7 +7,7 @@
  * - in miliseconds;
  * @returns {Promise<void>}
  * @example
- * import { Timeout } from 'vivth';
+ * import { Timeout } from 'vivth/neutral';
  *
  * const test = async () => {
  *   // code0
@@ -17,7 +17,7 @@
  * test();
  */
 export function Timeout(timeMS) {
-	return new Promise((resolve) => {
-		setTimeout(resolve, timeMS);
-	});
+	const { promise, resolve } = Promise.withResolvers();
+	setTimeout(resolve, timeMS);
+	return promise;
 }

package/src/function/Tries.mjs

@@ -1,6 +1,6 @@
 // @ts-check
 
-import { TryAsync } from './TryAsync.mjs';
+import { ForInAsync } from './ForInAsync.mjs';
 
 /**
  * @description
@@ -18,12 +18,12 @@ import { TryAsync } from './TryAsync.mjs';
  * @param {RecordTryType} tryRecord
  * @returns {Promise<
  * 	[[keyof RecordTryType, RETURNTYPE], undefined]
- * 	| [[undefined, undefined], Error|undefined]
+ * 	| [[undefined, undefined], Set<Error>]
  * >}
  * @example
- * import { Tries } from 'vivth';
+ * import { Tries } from 'vivth/neutral';
  *
- * const [[key, result], error] = await Tries({
+ * const [[key, result], setOfError] = await Tries({
  * 	someRuntime: async ({ prevError }) => {
  * 		// asuming on this one doesn't naturally throw error,
  * 		// yet you need to continue to next key,
@@ -53,19 +53,25 @@ import { TryAsync } from './TryAsync.mjs';
  */
 export async function Tries(tryRecord) {
 	/**
-	 * @type {Error|undefined}
+	 * @type {undefined|keyof RecordTryType}
 	 */
-	let prevError = undefined;
-	for (const key in tryRecord) {
-		const callback = tryRecord[key];
-		const [result, error] = await TryAsync(async () => {
-			return await callback({ prevError });
-		});
-		if (error) {
-			prevError = error;
-			continue;
-		}
+	let key;
+	/**
+	 * @type {undefined|RETURNTYPE}
+	 */
+	let result;
+	const [, setOfError] = await ForInAsync(
+		tryRecord,
+		async (key_, callback, { prevError, breakEarly }) => {
+			const result_ = await callback({ prevError });
+			breakEarly(); // when not error, it will break after return;
+			key = key_;
+			result = result_;
+		},
+	);
+	if (key) {
+		// @ts-expect-error
 		return [[key, result], undefined];
 	}
-	return [[undefined, undefined], prevError];
+	return [[undefined, undefined], setOfError];
 }

package/src/function/TryAsync.mjs

@@ -10,7 +10,7 @@ import { resolveErrorArray } from './resolveErrorArray.mjs';
  * @param {()=>Promise<RESULT>} asyncFunction_
  * @returns {Promise<[RESULT,undefined]|[undefined,Error]>}
  * @example
- * import { TryAsync } from 'vivth';
+ * import { TryAsync } from 'vivth/neutral';
  *
  * let [res, error] = await TryAsync(async () => {
  * 	return await fetch('./someAPI/Path');
@@ -18,11 +18,12 @@ import { resolveErrorArray } from './resolveErrorArray.mjs';
  *
  * [res, error] = await TryAsync(async () => {
  * 	if(!res.ok) {
- * 		throw new Error(404);
+ * 		throw 404;
  * 	}
  * 	return await res.json();
  * })
  */
+
 export async function TryAsync(asyncFunction_) {
 	try {
 		const result = await asyncFunction_();

package/src/function/TryNew.mjs

@@ -12,7 +12,7 @@ import { resolveErrorArray } from './resolveErrorArray.mjs';
  * @returns {[InstanceType<CLASSREF>, undefined]|
  * [undefined, Error]}
  * @example
- * import { TryNew } from 'vivth';
+ * import { TryNew } from 'vivth/neutral';
  *
  * const [instance, error] = TryNew(ClassReference, ...classConstructorParameters)
  * if(!error) {

package/src/function/TsToMjs.mjs

@@ -1,7 +1,7 @@
 // @ts-check
 
 import { readFile } from 'node:fs/promises';
-import { basename, dirname, extname, join } from 'node:path';
+import { basename, dirname, extname, join, relative } from 'node:path';
 
 import { transform } from 'esbuild';
 
@@ -9,43 +9,206 @@ import { Console } from '../class/Console.mjs';
 import { Paths } from '../class/Paths.mjs';
 import { TryAsync } from './TryAsync.mjs';
 import { FileSafe } from '../class/FileSafe.mjs';
+import { Preferrence } from '../common/Preferrence.mjs';
+import { CompileAS } from '../bundler/CompileAS.mjs';
+import { ForOfSync } from './ForOfSync.mjs';
+import { PipeSync } from './PipeSync.mjs';
+
+const suffixFor_asar = '_ASasar';
+const suffixForUniversal = '_ASUniversal';
 
 /**
  * @description
  * - 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`;
- * @param {string} path_
- * - path from `Paths.root`;
+ * >- at [at]\[blank\]typedef, import itself.mts pointing to the same exported object to fully type it in mjs(which `vivth` used to generate exports);
+ * - auto compile and typehint `.as.ts` to `.wasm`;
+ * @param {string} path
+ * - `relative`(to `Paths.root`) OR `absolute`, both are accepted;
  * @param {Object} [options]
- * @param {string} [options.overrideDir]
+ * @param {string} [options.overrideOutputDir]
  * - default: write conversion to same directory;
  * - path are relative to project root;
  * @param {BufferEncoding} [options.encoding]
  * - default: `utf-8`;
+ * @param {import('../typehints/AutoDocASOptions.mjs').AutoDocASOptions} [options.assemblyScriptOptions]
  * @returns {Promise<void>}
  * @example
- * import { TsToMjs } from 'vivth';
+ * import { TsToMjs } from 'vivth/node';
  *
- * await TsToMjs('./myFile.mts', { encoding: 'utf-8', overrideDir: './other/dir' });
+ * await TsToMjs('./myFile.mts', { encoding: 'utf-8', overrideOutputDir: './other/dir' });
+ */
+export async function TsToMjs(
+	path,
+	{
+		overrideOutputDir = undefined,
+		encoding = Preferrence.encoding,
+		assemblyScriptOptions = undefined,
+	} = {},
+) {
+	path = Paths.diskAbsolute(path);
+	if (path.endsWith('.as.ts')) {
+		if (basename(path).startsWith('-') || !assemblyScriptOptions) {
+			return;
+		}
+
+		const [, errorCompilingAssemblyScript] = await TryAsync(async () => {
+			let {
+				ASArgv = [],
+				ASAPIOptions = undefined,
+				generateFSasarImporter = false,
+			} = assemblyScriptOptions;
+			path = Paths.normalize(path);
+			const pathNoExt = path.replace(/.as.ts$/, '');
+			const wasmPath = `${pathNoExt}.wasm`;
+			const { error: errorCompileAS } = await CompileAS(
+				[path, '--outFile', wasmPath, '--bindings', 'esm', ...ASArgv],
+				ASAPIOptions,
+			);
+			if (errorCompileAS) {
+				throw { errorCompileAS };
+			}
+			if (generateFSasarImporter) {
+				const handler = [
+					/**
+					 * @param {string} path
+					 * @returns {string}
+					 */
+					(path) => relative(dirname(path), path),
+					/**
+					 * @param {string} path
+					 * @returns {string}
+					 */
+					(path) => {
+						if (!pathNoExt.includes('/vivth/src/')) {
+							return 'vivth/all';
+						}
+						if (path.startsWith('.')) {
+							return Paths.normalize(path);
+						}
+						return Paths.normalize(`./${path}`);
+					},
+				];
+				const paths__ = [
+					'/src/function/InstantiateAssemblyScript.mjs',
+					'/src/bundler/adds/PathFSFile.mjs',
+				];
+				const res = [];
+				for (let i = 0; i < paths__.length; i++) {
+					const path_ = paths__[i];
+					if (!path_) {
+						continue;
+					}
+					res.push(PipeSync(join(Paths.root, path_), ...handler));
+				}
+				const [importInstantiateAssemblyScriptFrom = '', importPathFSFrom = ''] = res;
+				const baseNameNoExt = basename(pathNoExt);
+				const mjsNoExt = `${baseNameNoExt}${suffixFor_asar}`;
+				const mjsPath = `${mjsNoExt}.mjs`;
+				const [, errorWrite] = await FileSafe.write(
+					`${pathNoExt}${suffixFor_asar}.mjs`,
+					`// @ts-check
+import { InstantiateAssemblyScript } from '${Paths.normalize(importInstantiateAssemblyScriptFrom)}';
+import { PathFSFile } from '${Paths.normalize(importPathFSFrom)}';
+
+/**
+ * @-description-
+ * - \`typehinted\` WASM of AssemblyScript binding;
+ * >- can only be used for \`nodeJS\` compatible runtime;
+ * >- DO NOT USE ON BROWSER RUNTIME;
+ * - used for integration with \`vivth.FSasar\`;
+ * >- able to be bundled inline;
+ * @param {Parameters<typeof InstantiateAssemblyScript<import('./fib.js')>>[1]} [import_]
+ * @returns {ReturnType<typeof InstantiateAssemblyScript<import('./fib.js')>>}
  */
-export async function TsToMjs(path_, { overrideDir = undefined, encoding = 'utf-8' } = {}) {
-	if (Paths.root === undefined) {
+export const ${mjsNoExt} = ( import_ = {} ) => InstantiateAssemblyScript(PathFSFile.vivthFile('./${baseNameNoExt}.wasm'), import_);
+`.replace('-description-', 'description'),
+					{ encoding: Preferrence.encoding },
+				);
+				if (errorWrite) {
+					Console.error(
+						{
+							[TsToMjs.name]: `❌error generate FSInline Importer '${mjsPath}'`,
+							errorWrite,
+						},
+						{
+							now: true,
+						},
+					);
+					return;
+				}
+				Console.info(
+					{
+						[TsToMjs.name]: `✅successfully generate FSInline Importer '${mjsPath}'`,
+					},
+					{
+						now: true,
+					},
+				);
+			}
+			Console.info(
+				{
+					[TsToMjs.name]: `✅successfully compiles '${path}'`,
+				},
+				{
+					now: true,
+				},
+			);
+		});
+		if (errorCompilingAssemblyScript) {
+			Console.error({ errorCompilingAssemblyScript }, { now: true });
+		}
 		return;
 	}
-	const rootPath = Paths.normalize(Paths.root);
-	if (Paths.normalize(path_).startsWith(rootPath) === false) {
-		path_ = Paths.normalize(join(rootPath, path_));
+	const ext = extname(path);
+	if (
+		/** */
+		ext === '.js' &&
+		(await FileSafe.exist(path.replace(/.js$/, '.as.ts')))
+	) {
+		const [content, errorReadFile] = await TryAsync(async () => {
+			return (await readFile(path)).toString(Preferrence.encoding);
+		});
+		if (errorReadFile) {
+			Console.error({ errorReadFile }, { now: true });
+			return;
+		}
+		const regex = /export\s+const\s+({[\s\S]*?})\s*=\s*await/g;
+		const matches = content.matchAll(regex).toArray();
+		await Promise.all(
+			ForOfSync(matches, async (match) => {
+				const match1 = match[1];
+				const trueContent = `// @ts-check
+
+import ${match1} from './${basename(path)}';
+
+/**
+ * @-description-
+ * - \`typehinted\` WASM of AssemblyScript binding, can be used for:
+ * >- \`browser\` runtime;
+ * >- \`nodeJS\` compatible runtime;
+ */
+export const ${basename(path.replace(/.js$/, suffixForUniversal))} = ${match1};
+`.replace('-description-', 'description');
+				await FileSafe.write(path.replace(/.js$/, `${suffixForUniversal}.mjs`), trueContent, {
+					encoding: Preferrence.encoding,
+				});
+			})[0],
+		);
+		return;
 	}
-	const ext = extname(path_);
-	if (ext !== '.ts' && ext !== '.mts') {
+	if (
+		(ext === '.ts' && (await FileSafe.exist(path.replace(/.ts$/, '.as.ts')))) ||
+		(ext !== '.ts' && ext !== '.mts')
+	) {
 		return;
 	}
-	const [content, error] = await TryAsync(async () => {
-		return await readFile(path_, { encoding });
+	const [content, errorReadFile] = await TryAsync(async () => {
+		return await readFile(path, { encoding });
 	});
-	if (error) {
-		Console.error(error);
+	if (errorReadFile) {
+		Console.error({ errorReadFile }, { now: true });
 		return;
 	}
 	const [result, transformError] = await TryAsync(async () => {
@@ -58,14 +221,14 @@ export async function TsToMjs(path_, { overrideDir = undefined, encoding = 'utf-
 		});
 	});
 	if (transformError || result === undefined) {
-		Console.error(transformError);
+		Console.error({ transformError }, { now: true });
 		return;
 	}
-	const outputDir = overrideDir ? join(rootPath, overrideDir) : dirname(path_);
-	const outputPath = join(outputDir, basename(path_).replace(ext, '.mjs'));
+	const outputDir = !!overrideOutputDir ? Paths.diskAbsolute(overrideOutputDir) : dirname(path);
+	const outputPath = join(outputDir, basename(path).replace(new RegExp(`${ext}$`), '.mjs'));
 	const [, writeError] = await FileSafe.write(outputPath, result.code, { encoding });
 	if (writeError === undefined) {
 		return;
 	}
-	Console.error(writeError);
+	Console.error({ writeError }, { now: true });
 }

package/src/function/UniqueFSTempName.mjs

@@ -0,0 +1,33 @@
+// @ts-check
+
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { createHash } from 'node:crypto';
+
+import { Paths } from '../class/Paths.mjs';
+import { GetMaxFilenameLength } from './GetMaxFilenameLength.mjs';
+
+/**
+ * @description
+ * - generate unique full path name to temp directory + 'vivth/${uniqueName}.tmp';
+ * - filename length already calibrated for each os;
+ * @param {string} path
+ * @param {string} [fileExtention]
+ * @returns {string}
+ */
+export function UniqueFSTempName(path, fileExtention = '.tmp') {
+	if (!fileExtention.startsWith('.')) {
+		fileExtention = `.${fileExtention}`;
+	}
+	if (fileExtention !== '.tmp') {
+		fileExtention = `.tmp${fileExtention}`;
+	}
+	const hash = createHash('sha256').update(Paths.normalize(path)).digest('hex');
+	let tempPath = Paths.normalize(join(tmpdir(), 'vivth', `${hash}`));
+	const maxlen = GetMaxFilenameLength() - fileExtention.length;
+	if (maxlen < tempPath.length) {
+		tempPath = tempPath.slice(0, maxlen);
+	}
+	tempPath = `${tempPath}${fileExtention}`;
+	return tempPath;
+}

package/src/function/errorToMessage.mjs

@@ -0,0 +1,21 @@
+// @ts-check
+
+/**
+ * @param {Error} err
+ * @returns {import('esbuild').Message}
+ */
+export function errorToMessage(err) {
+	return {
+		id: '', // Add this line to satisfy the interface requirement
+		text: err.message,
+		location: null,
+		notes: [
+			{
+				text: err.stack || '',
+				location: null,
+			},
+		],
+		pluginName: 'my-plugin',
+		detail: err,
+	};
+}

package/src/function/resolveErrorArray.mjs

@@ -5,5 +5,19 @@
  * @returns {[undefined, Error]}
  */
 export const resolveErrorArray = (unknown) => {
-	return [undefined, unknown instanceof Error ? unknown : new Error(String(unknown))];
+	if (unknown instanceof Error) {
+		return [undefined, unknown];
+	}
+	let message;
+	try {
+		message = JSON.stringify(unknown);
+	} catch {
+		try {
+			message = String(unknown);
+		} catch {
+			message = '[Unstringifiable value]';
+		}
+	}
+	const err = new Error(message);
+	return [undefined, err];
 };