vivth 1.4.10 → 1.5.0

package/src/function/ClearRequireCache.mjs

@@ -0,0 +1,33 @@
+// @ts-check
+
+import { createRequire } from 'node:module';
+
+import { ForOfSync } from './ForOfSync.mjs';
+import { fileURLToPath } from 'node:url';
+import { Paths } from '../class/Paths.mjs';
+
+const require = /* @__PURE__ */ createRequire(import.meta.url);
+
+/**
+ * @param {string} string
+ * @returns {string}
+ */
+const fileURLToPathWithDenormalized = (string) => {
+	return Paths.nativeSep(fileURLToPath(string).toString());
+};
+
+/**
+ * @description
+ * - safely clear `import`/`require` `caches`;
+ * @type {(path:string)=>void}
+ * @example
+ * import { ClearRequireCache } from 'vivth/node';
+ *
+ * ClearRequireCache('D://path/to.mjs');
+ */
+export function ClearRequireCache(keysOfCache) {
+	ForOfSync([Paths.nativeSep, fileURLToPathWithDenormalized], (handler) => {
+		const keysOfCache_ = handler(keysOfCache).toString();
+		delete require.cache[keysOfCache_];
+	});
+}

package/src/function/CreateImmutable.mjs

@@ -1,6 +1,7 @@
 // @ts-check
 
 import { Console } from '../class/Console.mjs';
+import { IsTypeOf } from './IsTypeOf.mjs';
 import { LazyFactory } from './LazyFactory.mjs';
 import { TrySync } from './TrySync.mjs';
 
@@ -16,13 +17,13 @@ import { TrySync } from './TrySync.mjs';
  * @param {(this:PARENT)=>OBJECT} object
  * @param {Object} [options]
  * @param {boolean} [options.lazy]
- * @return {OBJECT}
+ * @return {ReturnType<typeof TrySync<OBJECT>>}
  * @example
- * import { CreateImmutable } from 'vivth';
+ * import { CreateImmutable } from 'vivth/neutral';
  *
  * const mappedObject = new Map();
  *
- * CreateImmutable(window, 'mySharedObject', {
+ * const [object, errorCreatingImmutable] = CreateImmutable(window, 'mySharedObject', {
  * 	setMap(name_, value) => {
  * 		mappedObject.set(name_, value)
  * 	},
@@ -30,40 +31,42 @@ import { TrySync } from './TrySync.mjs';
  * })
  */
 export function CreateImmutable(parent, keyName, object, { lazy = true } = {}) {
-	if (parent === undefined || typeof parent !== 'object') {
-		const error = {
-			object,
-			parent,
-			keyName,
-			message: 'Invalid parent object provided to `CreateImmutable`;',
-		};
-		Console.error(error);
-		throw Error(JSON.stringify(error));
-	}
-	let [, error] = TrySync(() => {
-		Object.defineProperty(parent, keyName, {
-			value: lazy ? LazyFactory(() => object.call(parent)) : object.call(parent),
-			writable: false,
-			configurable: false,
-			enumerable: false,
+	return TrySync(() => {
+		if (parent === undefined || !IsTypeOf(parent, 'object')) {
+			const error = {
+				object,
+				parent,
+				keyName,
+				message: 'Invalid parent object provided to `CreateImmutable`;',
+			};
+			Console.error(error);
+			throw Error(JSON.stringify(error));
+		}
+		let [, error] = TrySync(() => {
+			Object.defineProperty(parent, keyName, {
+				value: lazy ? LazyFactory(() => object.call(parent)) : object.call(parent),
+				writable: false,
+				configurable: false,
+				enumerable: false,
+			});
 		});
+		if (error) {
+			[, error] = TrySync(() => {
+				// @ts-expect-error
+				parent[keyName] = lazy ? LazyFactory(() => object.call(parent)) : object.call(parent);
+			});
+		}
+		if (error) {
+			const error = {
+				parent,
+				message: `"${keyName}" already defined on the "parent"`,
+				// @ts-expect-error
+				realValue: parent[keyName],
+			};
+			Console.warn(error);
+			throw JSON.stringify(error);
+		}
+		// @ts-expect-error
+		return parent[keyName];
 	});
-	if (error) {
-		[, error] = TrySync(() => {
-			// @ts-expect-error
-			parent[keyName] = lazy ? LazyFactory(() => object.call(parent)) : object.call(parent);
-		});
-	}
-	if (error) {
-		const error = {
-			parent,
-			message: `"${keyName}" already defined on the "parent"`,
-			// @ts-expect-error
-			realValue: parent[keyName],
-		};
-		Console.warn(error);
-		throw new Error(JSON.stringify(error));
-	}
-	// @ts-expect-error
-	return parent[keyName];
 }

package/src/function/EventCheck.mjs

@@ -1,6 +1,7 @@
 // @ts-check
 
 import { EventNameSpace } from '../common/EventNameSpace.mjs';
+import { IsTypeOf } from './IsTypeOf.mjs';
 
 /**
  * @description
@@ -9,10 +10,12 @@ import { EventNameSpace } from '../common/EventNameSpace.mjs';
  * @param {Record<typeof EventNameSpace, string>} eventObject
  * @returns {boolean}
  * @example
- * import { EventCheck } from 'vivth';
+ * import { EventCheck } from 'vivth/neutral';
  * import { incomingMessage } from './some/where.mjs';
  *
  * const eventObjectPayload = EventObject('worker:exit');
+ *
+ * console.log(EventCheck(incomingMessage, eventObjectPayload));
  * // assuming `incomingMessage`, also created using EventObject('worker:exit');
  * // or manually {[EventNameSpace]:'worker:exit'};
  * // which either will result true;
@@ -20,7 +23,7 @@ import { EventNameSpace } from '../common/EventNameSpace.mjs';
 export function EventCheck(object, eventObject) {
 	return (
 		object &&
-		typeof object === 'object' &&
+		IsTypeOf(object, 'object') &&
 		EventNameSpace in object &&
 		object[EventNameSpace] === eventObject[EventNameSpace]
 	);

package/src/function/EventObject.mjs

@@ -9,13 +9,9 @@ import { EventNameSpace } from '../common/EventNameSpace.mjs';
  * @param {NAME} name
  * @returns {{[EventNameSpace]: NAME}}
  * @example
- * import { EventCheck } from 'vivth';
- * import { incomingMessage } from './some/where.mjs';
+ * import { EventObject } from 'vivth/neutral';
  *
- * const eventObjectPayload = EventObject('worker:exit');
- * // assuming `incomingMessage`, also created using EventObject('worker:exit');
- * // or manually {[EventNameSpace]:'worker:exit'};
- * // which either will result true;
+ * export const eventObjectPayload = EventObject('worker:exit');
  */
 export function EventObject(name) {
 	return { [EventNameSpace]: name };

package/src/function/ForInAsync.mjs

@@ -0,0 +1,76 @@
+// @ts-check
+
+import { TryAsync } from './TryAsync.mjs';
+
+/**
+ * @description
+ * - safe `Object` async iterator helper;
+ * >- collect errors then returns it as Set<Error>;
+ * @template {Record<string|number|symbol, any>} OBJECT
+ * @template {any} RETURNTYPE
+ * @param {OBJECT} object
+ * @param {(
+ * key:keyof OBJECT,
+ * value:OBJECT[keyof OBJECT],
+ * options:{
+ * prevError:Error|undefined,
+ * breakEarly:()=>void,
+ * },
+ * )=>Promise<RETURNTYPE|undefined>} handlerCallback
+ * - when `breakEarly` is called, the loop will break at the begining of the next iteration;
+ * - typehint according to your js flavor, so the function make setOfResult typed;
+ * @returns {Promise<[Set<RETURNTYPE>, Set<Error>]>}
+ * @example
+ * import { ForInAsync } from 'vivth/neutral';
+ *
+ * const object = { A: 'a', B: 'b' };
+ * const setOfError = await ForInAsync(
+ * 	object,
+ * 	async (key, value, { prevError, breakEarly }) => {
+ * 		// if(prevError) {
+ * 		// 	breakEarly(); // imperative break;
+ * 		// 	return; // undefined return will not be added to result;
+ * 		// }
+ * 	}
+ * );
+ */
+export async function ForInAsync(object, handlerCallback) {
+	/**
+	 * @type {Set<Error>}
+	 */
+	const errors = new Set();
+	/**
+	 * @type {Set<RETURNTYPE>}
+	 */
+	const results = new Set();
+	/**
+	 * @type {Error|undefined}
+	 */
+	let prevError;
+	let breakEarly_ = false;
+	const breakEarly = () => {
+		breakEarly_ = true;
+	};
+	for (const key in object) {
+		if (breakEarly_) {
+			break;
+		}
+		const value = object[key];
+		if (!Object.hasOwn(object, key) || value === undefined) {
+			continue;
+		}
+		const [result, error] = await TryAsync(
+			async () => await handlerCallback(key, value, { prevError, breakEarly }),
+		);
+		if (error) {
+			prevError = error;
+			errors.add(error);
+			continue;
+		}
+		if (result === undefined) {
+			continue;
+		}
+		results.add(result);
+	}
+	return [results, errors];
+}

package/src/function/ForInSync.mjs

@@ -0,0 +1,87 @@
+// @ts-check
+
+import { TrySync } from './TrySync.mjs';
+
+/**
+ * @description
+ * - safe `Object` iterator helper;
+ * >- collect errors then returns it as Set<Error>;
+ * @template {Record<string|number|symbol, any>} OBJECT
+ * @template {any} RETURNTYPE
+ * @param {OBJECT} object
+ * @param {(
+ * key:keyof OBJECT,
+ * value:OBJECT[keyof OBJECT],
+ * options:{
+ * prevError:Error|undefined,
+ * breakEarly:()=>void,
+ * },
+ * )=>RETURNTYPE|undefined} handlerCallback
+ * - when `breakEarly` is called, the loop will break at the begining of the next iteration;
+ * - typehint according to your js flavor, so the function make setOfResult typed;
+ * @returns {[Set<RETURNTYPE>, Set<Error>]}
+ * @example
+ * import { ForInSync } from 'vivth/neutral';
+ *
+ * const object = { A: 'a', B: 'b' };
+ * const [setOfResult , setOfError] = ForInSync(
+ * 	object,
+ * 	(key, value, { prevError, breakEarly }) => {
+ * 		// if(prevError) {
+ * 		// 	breakEarly(); // imperative break;
+ * 		// 	return; // undefined return will not be added to result;
+ * 		// }
+ * 	}
+ * );
+ */
+export function ForInSync(object, handlerCallback) {
+	/**
+	 * @type {Set<Error>}
+	 */
+	const errors = new Set();
+	/**
+	 * @type {Set<RETURNTYPE>}
+	 */
+	const results = new Set();
+	/**
+	 * @type {Error|undefined}
+	 */
+	let prevError;
+	let breakEarly_ = false;
+	const breakEarly = () => {
+		breakEarly_ = true;
+	};
+	for (const key in object) {
+		if (
+			/** */
+			breakEarly_
+		) {
+			break;
+		}
+		const value = object[key];
+		if (
+			/** */
+			!Object.hasOwn(object, key) ||
+			value === undefined
+		) {
+			continue;
+		}
+		const [result, error] = TrySync(() => handlerCallback(key, value, { prevError, breakEarly }));
+		if (
+			/** */
+			error
+		) {
+			prevError = error;
+			errors.add(error);
+			continue;
+		}
+		if (
+			/** */
+			result === undefined
+		) {
+			continue;
+		}
+		results.add(result);
+	}
+	return [results, errors];
+}

package/src/function/ForOfAsync.mjs

@@ -0,0 +1,61 @@
+// @ts-check
+
+import { TryAsync } from './TryAsync.mjs';
+
+/**
+ * @description
+ * - loop through iterable safely;
+ * @template {any} T
+ * @template {any} RETURNTYPE
+ * @param {Iterable<T>} iterable
+ * @param {(value: T,
+ * options:{
+ * prevError:Error|undefined,
+ * breakEarly:()=>void,
+ * }) => Promise<RETURNTYPE|undefined>} handlerCallback
+ * - when `breakEarly` is called, the loop will break at the begining of the next iteration;
+ * - typehint according to your js flavor, so the function make setOfResult typed;
+ * @returns {Promise<[Set<RETURNTYPE>, Set<Error>]>}
+ * @example
+ * import { ForOfAsync } from 'vivth/neutral';
+ *
+ * await ForOfAsync(iterable, async(value, { prevError, breakEarly })=>{
+ * 	// code
+ * })
+ */
+export async function ForOfAsync(iterable, handlerCallback) {
+	/**
+	 * @type {Set<Error>}
+	 */
+	const errors = new Set();
+	/**
+	 * @type {Set<RETURNTYPE>}
+	 */
+	const results = new Set();
+	/**
+	 * @type {Error|undefined}
+	 */
+	let prevError;
+	let breakEarly_ = false;
+	const breakEarly = () => {
+		breakEarly_ = true;
+	};
+	for await (const value of iterable) {
+		if (breakEarly_) {
+			break;
+		}
+		const [result, error] = await TryAsync(
+			async () => await handlerCallback(value, { prevError, breakEarly }),
+		);
+		if (error) {
+			prevError = error;
+			errors.add(error);
+			continue;
+		}
+		if (result === undefined) {
+			continue;
+		}
+		results.add(result);
+	}
+	return [results, errors];
+}

package/src/function/ForOfSync.mjs

@@ -0,0 +1,70 @@
+// @ts-check
+
+import { TrySync } from './TrySync.mjs';
+
+/**
+ * @description
+ * - loop through iterable safely;
+ * @template {any} T
+ * @template {any} RETURNTYPE
+ * @param {Iterable<T>} iterable
+ * @param {(value: T,
+ * options:{
+ * prevError:Error|undefined,
+ * breakEarly:()=>void,
+ * }) => RETURNTYPE|undefined} handlerCallback
+ * - when `breakEarly` is called, the loop will break at the begining of the next iteration;
+ * - typehint according to your js flavor, so the function make setOfResult typed;
+ * @returns {[Set<RETURNTYPE>, Set<Error>]}
+ * @example
+ * import { ForOfSync, TryAsync } from 'vivth/neutral';
+ *
+ * ForOfSync(iterable, (value, { prevError, breakEarly })=>{
+ * 	// code
+ * });
+ *
+ * await Promise.all(ForOfSync([
+ * 	async()=>{
+ * 		// code to run pararelly
+ * 	},
+ * 	async()=>{
+ * 		// code to run pararelly
+ * 	},
+ * ], async(cb)=>{
+ * 	return await cb();
+ * })[0])
+ */
+export function ForOfSync(iterable, handlerCallback) {
+	/**
+	 * @type {Set<Error>}
+	 */
+	const errors = new Set();
+	/**
+	 * @type {Set<RETURNTYPE>}
+	 */
+	const results = new Set();
+	/**
+	 * @type {Error|undefined}
+	 */
+	let prevError;
+	let breakEarly_ = false;
+	const breakEarly = () => {
+		breakEarly_ = true;
+	};
+	for (const value of iterable) {
+		if (breakEarly_) {
+			break;
+		}
+		const [result, error] = TrySync(() => handlerCallback(value, { prevError, breakEarly }));
+		if (error) {
+			prevError = error;
+			errors.add(error);
+			continue;
+		}
+		if (result === undefined) {
+			continue;
+		}
+		results.add(result);
+	}
+	return [results, errors];
+}

package/src/function/GetBufferFromRelativePath.mjs

@@ -0,0 +1,25 @@
+// @ts-check
+
+import { FSasar } from '../bundler/FSasar.mjs';
+import { PathFSFile } from '../bundler/adds/PathFSFile.mjs';
+
+/**
+ * @description
+ * - get content from relativePath;
+ * - only usefull to unbundled environtment;
+ * - if your goal is to include on the `.asar`, use [FSasar](#fsasar) instead;
+ * @param {string} relativePath
+ * - relative path from the caller;
+ * @returns {ReturnType<typeof FSasar.file>}
+ * @example
+ * import { GetContentFromRelativePath } from 'vivth/node';
+ *
+ * await GetContentFromRelativePath('../doc/parsedFile.mjs', 'utf-8');
+ */
+export async function GetBufferFromRelativePath(relativePath) {
+	return await FSasar.file(
+		PathFSFile.vivthFile(relativePath, {
+			shouldNotIncludes: '/vivth/src/function/GetContentFromRelativePath.mjs',
+		}),
+	);
+}

package/src/function/GetFilesFromDir.mjs

@@ -0,0 +1,49 @@
+// @ts-check
+
+import { join } from 'node:path';
+import { readdir } from 'node:fs/promises';
+
+import { TryAsync } from './TryAsync.mjs';
+import { Console } from '../class/Console.mjs';
+import { Paths } from '../class/Paths.mjs';
+import { ForOfSync } from './ForOfSync.mjs';
+
+/**
+ * @description
+ * - helper function to get file from dir;
+ * @param {string} dirAbsolutePath
+ * @param {RegExp} pathRule
+ * @param {Set<string>} [fileNames]
+ * - fill manually to imediately add result to existing `Set` without expecting return;
+ * @returns {Promise<Set<string>>}
+ * @example
+ * import { GetFilesFromDir } from 'vivth/node';
+ *
+ * const files = await GetFilesFromDir(join(Paths.root, '/dev/'), /[\s\S]\*[noblank]/); // without \[noblank]
+ */
+export async function GetFilesFromDir(dirAbsolutePath, pathRule, fileNames = new Set()) {
+	const [entries, errorReadDir] = await TryAsync(async () => {
+		return await readdir(dirAbsolutePath, { withFileTypes: true });
+	});
+	if (errorReadDir) {
+		Console.error({ errorReadDir }, { now: true });
+		return fileNames;
+	}
+	await Promise.all(
+		ForOfSync(entries, async (entry) => {
+			const fullPath = join(dirAbsolutePath, entry.name);
+			if (!pathRule.test(fullPath)) {
+				return;
+			}
+			if (entry.isFile()) {
+				fileNames.add(Paths.normalize(fullPath));
+				return;
+			}
+			if (!entry.isDirectory()) {
+				return;
+			}
+			await GetFilesFromDir(fullPath, pathRule, fileNames);
+		})[0],
+	);
+	return fileNames;
+}

package/src/function/GetMaxFilenameLength.mjs

@@ -0,0 +1,32 @@
+// @ts-check
+
+import process from 'node:process';
+import { constants } from 'node:fs';
+
+/**
+ * @type { undefined|number }
+ */
+let length;
+const fallbacklenght = 255;
+
+/**
+ * @description
+ * - Get OS-specific max filename length;
+ * - On POSIX: fs.constants.NAME_MAX;
+ * - On Windows: 255 (per component, unless long paths enabled);
+ * - used internally to validate name length for [`UniqueFSTempName`](#uniquefstempname);
+ * @returns {number}
+ */
+export function GetMaxFilenameLength() {
+	if (length === undefined) {
+		if (process.platform === 'win32') {
+			length = fallbacklenght; // fallback if undefined
+		} else {
+			length =
+				// @ts-expect-error
+				constants.NAME_MAX || fallbacklenght; // fallback if undefined
+		}
+	}
+	// @ts-expect-error
+	return length;
+}