vivth 1.4.10 → 1.5.1

package/src/function/GetModuleEsbuildPlatform.mjs

@@ -0,0 +1,118 @@
+// @ts-check
+
+import { dirname } from 'node:path';
+
+import { build } from 'esbuild';
+
+import { ForOfSync } from './ForOfSync.mjs';
+import { Paths } from '../class/Paths.mjs';
+import { TryAsync } from './TryAsync.mjs';
+import { SafeImport } from './SafeImport.mjs';
+import { Console } from '../class/Console.mjs';
+
+/**
+ * @param {Set<string>} platforms
+ * @param {string} path
+ * @returns {Promise<void>}
+ */
+const checkByImportWithoutCache = async (platforms, path) => {
+	const [, errorCheckingNodePlatform] = await SafeImport(path);
+	if (errorCheckingNodePlatform) {
+		return;
+	}
+	platforms.add('node');
+};
+
+/**
+ * @param {Set<string>} platforms
+ * @param {string} path
+ * @returns {Promise<void>}
+ */
+const browserBuilder = async (platforms, path) => {
+	await build({
+		entryPoints: [path],
+		platform: 'browser',
+		bundle: true,
+		write: false,
+		mainFields: ['module', 'main'],
+		logLevel: 'silent',
+		target: 'esnext',
+		format: 'esm',
+		absWorkingDir: dirname(path),
+	});
+	platforms.add('browser');
+};
+
+/**
+ * @type {Set<string>}
+ */
+const errorsSet = new Set();
+
+/**
+ * @description
+ * - get valid esbuild platform name for a module path;
+ * @param { string } path
+ * @returns { Promise<'browser'|'node'|'neutral'|'unsupported'> }
+ * @example
+ * // D://lib-root/myModule.mjs
+ * import process from 'node:process'; // lookupA;
+ * import { GetModuleEsbuildPlatform } from "vivth/node";
+ *
+ * await GetModuleEsbuildPlatform('./myModule.mjs'); // 'node'; caused of lookupA;
+ */
+export async function GetModuleEsbuildPlatform(path) {
+	path = Paths.normalize(path);
+	/**
+	 * @type { Set<string> }
+	 */
+	const platforms = new Set();
+
+	await Promise.all(
+		ForOfSync(
+			[
+				async () => {
+					await browserBuilder(platforms, path);
+				},
+				async () => {
+					await checkByImportWithoutCache(platforms, path);
+				},
+			],
+			async (cb) => {
+				return await TryAsync(cb);
+			},
+		)[0],
+	);
+	if (platforms.has('node') && platforms.has('browser')) {
+		if (errorsSet.has(path)) {
+			errorsSet.delete(path);
+			Console.info(
+				{ path, message: 'GetModuleEsbuildPlatform platform issue has been fixed' },
+				{ now: true },
+			);
+		}
+		return 'neutral';
+	}
+	if (platforms.has('browser')) {
+		if (errorsSet.has(path)) {
+			errorsSet.delete(path);
+			Console.info(
+				{ path, message: 'GetModuleEsbuildPlatform platform issue has been fixed' },
+				{ now: true },
+			);
+		}
+		return 'browser';
+	}
+	if (platforms.has('node')) {
+		if (errorsSet.has(path)) {
+			errorsSet.delete(path);
+			Console.info(
+				{ path, message: 'GetModuleEsbuildPlatform platform issue has been fixed' },
+				{ now: true },
+			);
+		}
+		return 'node';
+	}
+	errorsSet.add(path);
+	Console.error({ GetModuleEsbuildPlatformErrorsSet: errorsSet }, { now: true });
+	return 'unsupported';
+}

package/src/function/GetNamedImportAlias.mjs

@@ -10,7 +10,7 @@
  * @param {string} packageName
  * @returns {string|undefined}
  * @example
- * import { GetNamedImportAlias } from 'vivth';
+ * import { GetNamedImportAlias } from 'vivth/neutral';
  *
  * const checkNoAlias = `
  * import { something } from 'packageName';
@@ -24,7 +24,7 @@
 export function GetNamedImportAlias(content, moduleName, packageName) {
 	const checkIfImportingFromVivthRegex = new RegExp(
 		`(import\\s+{\\s*[\\s\\S]*(?<imported>${moduleName})\\s+as\\s+(?<alias>[a-zA-Z0-9]+)[\\s\\S]*\\s*}\\s+from\\s+['"]${packageName}['"])|(import\\s+{\\s*[\\s\\S]*(?<imported>${moduleName})[\\s\\S]*\\s*}\\s+from\\s+['"]${packageName}['"])`,
-		'g'
+		'g',
 	);
 	const matched = checkIfImportingFromVivthRegex.exec(content);
 	if (!matched || !matched.groups) {

package/src/function/GetRuntime.mjs

@@ -1,7 +1,9 @@
 // @ts-check
 
+import { IsTypeOf } from './IsTypeOf.mjs';
+
 /**
- * @typedef {import("../types/Runtime.mjs").Runtime} Runtime
+ * @typedef {import("../typehints/Runtime.mjs").Runtime} Runtime
  */
 
 /**
@@ -14,26 +16,20 @@ let runtime;
  * - detects the current JavaScript runtime;
  * @type {()=>Runtime}
  * @example
- * import { GetRuntime } form 'vivth';
+ * import { GetRuntime } from 'vivth/neutral';
  *
  * const runtime = GetRuntime();
  */
 export function GetRuntime() {
 	if (runtime === undefined) {
-		if (typeof Bun !== 'undefined') {
-			runtime = 'bun';
-		}
-		// @ts-expect-error
-		else if (typeof Deno !== 'undefined') {
-			runtime = 'deno';
-		} else if (typeof process !== 'undefined' && process.versions?.node) {
-			runtime = 'node';
-		} else if (
+		if (
 			// @ts-expect-error
-			typeof window !== 'undefined' &&
-			// @ts-expect-error
-			typeof document !== 'undefined'
+			!IsTypeOf(Bun, 'undefined')
 		) {
+			runtime = 'bun';
+		} else if (!IsTypeOf(process, 'undefined') && process.versions?.node) {
+			runtime = 'node';
+		} else if (!IsTypeOf(window, 'undefined') && !IsTypeOf(document, 'undefined')) {
 			runtime = 'browser';
 		} else {
 			runtime = 'unknown';

package/src/function/InstantiateAssemblyScript.mjs

@@ -0,0 +1,22 @@
+// @ts-check
+
+import { instantiate } from '@assemblyscript/loader';
+import { FSasar } from '../bundler/FSasar.mjs';
+
+/**
+ * @description
+ * - function wrapper for `.asar` `.wasm` from `AssemblyScript` asset;
+ * - conventions for using this class in conjuction with `JSautoDOC`:
+ * @template {Record<string, unknown>} RESULTTYPE
+ * @param {import('../bundler/adds/PathFSFile.mjs').PathFSFile} filePathFromProject
+ * - call `PathFSFile.vivthFile`;
+ * @param {Parameters<import('../typehints/AssemblyScriptLoaderInstantiate.mjs').AssemblyScriptLoaderInstantiate<RESULTTYPE>>[1]} [imports]
+ * @returns {Promise<import('../typehints/AssemblyScriptExportsType.mjs').AssemblyScriptExportsType<RESULTTYPE>>}
+ * @example
+ * import { PathFSFile, InstantiateAssemblyScript } from 'vivth/node';
+ *
+ * InstantiateAssemblyScript(PathFSFile.vivthFile('../function/myAsm.wasm'));;
+ */
+export async function InstantiateAssemblyScript(filePathFromProject, imports) {
+	return await instantiate(Buffer.from(await FSasar.file(filePathFromProject)), imports);
+}

package/src/function/IsAsync.mjs

@@ -6,7 +6,7 @@
  * @param {(...any:any)=>(any|Promise<any>)} functionReference
  * @returns {boolean}
  * @example
- * import { IsAsync } from 'vivth';
+ * import { IsAsync } from 'vivth/neutral';
  *
  * const a = function (params) {
  * 	// code

package/src/function/IsInstanceOf.mjs

@@ -0,0 +1,29 @@
+// @ts-check
+
+/**
+ * @description
+ * A type-safe `instanceof` helper.
+ * @template OBJ
+ * @param {unknown} obj - The object to test
+ * @param {new (...args: any[]) => OBJ} classRef - A constructor reference for T
+ * @returns {obj is OBJ}
+ * @example
+ * import { IsInstanceOf, Signal, Effect } from 'vivth/neutral';
+ *
+ * const a = new Signal(0);
+ * IsInstanceOf(a, Signal); // true
+ * IsInstanceOf(a, Effect); // false
+ *
+ * // but why not
+ * if(!(a instanceof Signal)){
+ *  //
+ * };
+ *
+ * // here's why
+ * if(!IsInstanceOf(a, Signal)){
+ *  //
+ * };
+ */
+export function IsInstanceOf(obj, classRef) {
+	return obj instanceof classRef;
+}

package/src/function/IsSameFile.mjs

@@ -0,0 +1,41 @@
+// @ts-check
+
+import { resolve } from 'path-unified';
+import { IsStringLooksLikeAPath } from './IsStringLooksLikeAPath.mjs';
+import { Console } from '../class/Console.mjs';
+import { Paths } from '../class/Paths.mjs';
+
+/**
+ * @param {string} url
+ * @returns {string}
+ */
+const stripFileUrl = (url) => {
+	return url.startsWith('file://') ? url.slice(7) : url;
+};
+
+/**
+ * @description
+ * - check if two path is the same file;
+ * @param {string} pathA
+ * @param {string} pathB
+ * @returns {boolean}
+ * @example
+ * // `D://myFile.mjs` cwd at `D://`
+ * import { IsSameFile } from "vivth/node";
+ *
+ * IsSameFile('D:\\mFile.mjs', 'D://mFile.mjs') // true;
+ * IsSameFile('//mFile.mjs', 'D://mFile.mjs') // true;
+ * // both path are auto resolved to Paths.root;
+ * IsSameFile('D:\\mFile.mjs', 'D:\\notmfile.mjs') // false;
+ */
+export function IsSameFile(pathA, pathB) {
+	if (!IsStringLooksLikeAPath(pathA) || !IsStringLooksLikeAPath(pathB)) {
+		Console.warn(`'${pathA}' AND/OR '${pathB}' is not a valid path`);
+		return false;
+	}
+	const cleanA = resolve(Paths.diskAbsolute(stripFileUrl(pathA)));
+	const cleanB = resolve(Paths.diskAbsolute(stripFileUrl(pathB)));
+	const result = cleanA === cleanB;
+	// Console.log({ result, cleanA, cleanB });
+	return result;
+}

package/src/function/IsStringLooksLikeAPath.mjs

@@ -0,0 +1,20 @@
+// @ts-check
+
+/**
+ * @description
+ * - check if string lookslike a path;
+ * @param {string} spec
+ * @returns {boolean}
+ * @example
+ * import { IsStringLooksLikeAPath } from 'vivth/neutral';
+ *
+ * looksLikePath("./foo.mjs"); // true
+ * looksLikePath("../bar.ts"); // true
+ * looksLikePath("/usr/lib.js"); // true
+ * looksLikePath("C:\\lib\\mod"); // true
+ * looksLikePath("react"); // false
+ * looksLikePath("node:path"); // false
+ */
+export function IsStringLooksLikeAPath(spec) {
+	return /^(\.{1,2}\/|\/|[A-Za-z]:\\)/.test(spec) || /[\\/]/.test(spec);
+}

package/src/function/IsTypeOf.mjs

@@ -0,0 +1,27 @@
+const TypeMap = {
+  string: "",
+  number: 0,
+  boolean: true,
+  object: {},
+  function: () => {
+  },
+  undefined: void 0,
+  symbol: /* @__PURE__ */ Symbol(),
+  bigint: 0n
+};
+/**
+ * @preserve
+ * @description
+ * A type-safe `typeof` helper.
+ * @template {keyof typeof TypeMap} K
+ * @param {unknown} object - The value to check.
+ * @param {K} type - The type string to compare against.
+ * @returns {object is typeof TypeMap[K]} - Returns true if the type matches, narrowing the type.
+ */
+function IsTypeOf(object, type) {
+  return typeof object === type;
+}
+export {
+  IsTypeOf,
+  TypeMap
+};

package/src/function/IsTypeOf.mts

@@ -0,0 +1,31 @@
+/**
+ * Map of 'typeof' string results to their actual TypeScript types.
+ * Using a constant object allows for type-safe extraction without
+ * manual conditional mapping.
+ */
+export const TypeMap = {
+	string: '',
+	number: 0,
+	boolean: true,
+	object: {},
+	function: () => {},
+	undefined: undefined,
+	symbol: Symbol(),
+	bigint: 0n,
+};
+
+/**
+ * @preserve
+ * @description
+ * A type-safe `typeof` helper.
+ * @template {keyof typeof TypeMap} K
+ * @param {unknown} object - The value to check.
+ * @param {K} type - The type string to compare against.
+ * @returns {object is typeof TypeMap[K]} - Returns true if the type matches, narrowing the type.
+ */
+export function IsTypeOf<K extends keyof typeof TypeMap>(
+	object: unknown,
+	type: K,
+): object is (typeof TypeMap)[K] {
+	return typeof object === type;
+}

package/src/function/LazyFactory.mjs

@@ -1,6 +1,6 @@
 // @ts-check
 
-import { unwrapLazy } from '../common/lazie.mjs';
+import { FactoryKey } from '../common/FactoryKey.mjs';
 
 /**
  * @description
@@ -8,12 +8,14 @@ import { unwrapLazy } from '../common/lazie.mjs';
  * >- usefull for lazily instantiating an object, since instance naturally have props/methods;
  * @template FACTORY
  * @param {() => FACTORY} factory
- * @returns {FACTORY & {[unwrapLazy]: ()=> FACTORY}}
- * - the unwrapLazy prop can be accessed to force instatiation/call;
- * >- `unwrapLazy` prop name can be checked by checking the list of possible prop, from your ide;
- * >- as of version `1.0.0`, value is `vivth:unwrapLazy;`;
+ * @returns {FACTORY & {[FactoryKey]: FACTORY}}
+ * - the FactoryKey prop can be accessed to force instatiation/call;
+ * - usefull for Object that has different accessor behaviour when being get via Proxy, including but not limited too:
+ * >- `Set<any>`;
+ * >- `Map<any, any>`;
+ * >- non referenced object, like `Effect`;
  * @example
- * import { LazyFactory } from  'vivth';
+ * import { LazyFactory, FactoryKey } from 'vivth/neutral';
  *
  * class MyClass{
  *    constructor() {
@@ -33,45 +35,45 @@ import { unwrapLazy } from '../common/lazie.mjs';
  * const a = myInstance; // not yet initiated;
  * const b = a.myProp // imediately initiated;
  * // OR
- * myInstance["vivth:unwrapLazy;"]() // forcefully call factory generator;
+ * myInstance[FactoryKey] // forcefully call factory generator;
  */
 export function LazyFactory(factory) {
 	/**
 	 * @type {FACTORY|undefined}
 	 */
 	let instance;
+	const generateIfUndefined = () => {
+		if (instance !== undefined) {
+			return;
+		}
+		instance = factory();
+	};
 	// @ts-expect-error
 	return new Proxy(
-		{},
+		/** */
+		() => {},
 		{
 			get(_, prop) {
-				if (prop === unwrapLazy) {
-					if (instance === undefined) {
-						instance = factory();
-					}
-					return () => instance;
-				}
-				if (instance === undefined) {
-					instance = factory();
+				generateIfUndefined();
+				if (prop === FactoryKey) {
+					return instance;
 				}
 				// @ts-expect-error
 				return instance[prop];
 			},
 			set(_, prop, newValue) {
-				if (instance === undefined) {
-					instance = factory();
-				}
+				generateIfUndefined();
 				// @ts-expect-error
 				instance[prop] = newValue;
 				return true;
 			},
 			apply(_, thisArg, args) {
-				if (instance === undefined) {
-					instance = factory();
+				generateIfUndefined();
+				if (typeof instance !== 'function') {
+					throw new TypeError('LazyFactory: instance is not callable');
 				}
-				// @ts-expect-error
 				return Reflect.apply(instance, thisArg, args);
 			},
-		}
+		},
 	);
 }

package/src/function/MonkeyPatch.mjs

@@ -0,0 +1,38 @@
+// @ts-check
+
+/**
+ * @import {MonkeyPatchedType} from '../typehints/MonkeyPatchedType.mjs'
+ */
+
+/**
+ * Monkey‑patch an environmental API by replacing a property on a parent object
+ * with a new function or class. This allows you to intercept or override
+ * browser/Node globals (e.g. `XMLHttpRequest`, `Worker`, `fetch`) without
+ * modifying the rest of your application code.
+ *
+ * ## Notes
+ * - Run this before other code that consumes the patched API.
+ * - Existing instances created before patching are unaffected.
+ * - If the property is non‑writable, assignment will throw.
+ * - For classes, always call `super(...args)` in your constructor.
+ * - For functions, preserve the call signature to avoid type errors.
+ *
+ * @template {Object} PAR
+ * @template {keyof PAR} KEY
+ * @param {PAR} parent - The parent object holding the property (e.g. `window`).
+ * @param {KEY} key - The property name on the parent to replace.
+ * @param {(
+ *    arg0:{originalObject:PAR[KEY]}
+ *  ) => MonkeyPatchedType<PAR[KEY]>
+ * } newObjectGenerator
+ *   - Function that receives the original object and returns the patched version.
+ *   - For classes: extend `originalObject` and override methods.
+ *   - For functions: spread arguments(and when necessary, delegate to `originalObject`).
+ * @returns {void}
+ */
+export function MonkeyPatch(parent, key, newObjectGenerator) {
+	const originalObject = parent[key];
+	/** @type {any} */
+	const newObject = newObjectGenerator({ originalObject });
+	parent[key] = newObject;
+}

package/src/function/NewAnimationTimeline.mjs

@@ -0,0 +1,55 @@
+// @ts-check
+
+import { TrySync } from './TrySync.mjs';
+
+/**
+ * @description
+ * - create animation timeline helper;
+ * @param {Object} options
+ * @param {number} options.fps
+ * - frame per second;
+ * @param {{seconds:number}|{frames:number}} options.duration
+ * @param {(frame:{index:number, total:number, percentage:number})=>void} callback
+ * - called every frame until duration ends;
+ * @returns {()=>void}
+ * - early clearInterval callback;
+ */
+export function NewAnimationTimeline({ fps, duration }, callback) {
+	/** @type {ReturnType<typeof setInterval> | undefined} */
+	let interval;
+	let totalFrames;
+	if ('frames' in duration) {
+		totalFrames = duration.frames;
+	} else {
+		totalFrames = Math.round(fps * duration.seconds);
+	}
+	let currentFrame = 0;
+	const clear = () => {
+		clearInterval(interval);
+	};
+	interval = setInterval(() => {
+		const [, errorAnimate] = TrySync(() => {
+			currentFrame++;
+			callback({
+				get index() {
+					return currentFrame;
+				},
+				get total() {
+					return totalFrames;
+				},
+				get percentage() {
+					return currentFrame / totalFrames;
+				},
+			});
+		});
+		if (errorAnimate) {
+			console.error({ errorAnimate });
+			clear();
+			return;
+		}
+		if (currentFrame >= totalFrames && interval) {
+			clear();
+		}
+	}, 1000 / fps);
+	return clear;
+}

package/src/function/NewChainable.mjs

@@ -0,0 +1,69 @@
+// @ts-check
+
+/**
+ * @description
+ * - Wraps a target object in a chainable;
+ * - example:
+ * ```html
+ * <canvas id="myCanvas" width="400" height="400"></canvas>
+ * ```
+ * - chain call are synchronous without awaiting;
+ * >- if the method are async, it could cause race condition;
+ * @template {object} OBJ
+ * @param {OBJ} ctx
+ * @returns {import("../typehints/ChainableType.mjs").ChainableType<OBJ>}
+ * @example
+ * import { NewChainable, TrySync } from 'vivth/neutral';
+ *
+ * TrySync(()=>{
+ * const canvas = document.getElementById('myCanvas');
+ * if (!canvas) {
+ * 	return;
+ * }
+ *
+ * const ctx2D = canvas.getContext('2d');
+ *
+ * // instead of repeating call method from `ctx2D`, you can:
+ * NewChainable(ctx2D)
+ * 	.beginPath()
+ * 	.moveTo(50, 50)
+ * 	.lineTo(200, 50)
+ * 	.lineTo(200, 200)
+ * 	.closePath()
+ * 	.stroke();
+ * 	// .this to get ctx2D reference;
+ * })
+ */
+export function NewChainable(ctx) {
+	/**
+	 * @type {import("../typehints/ChainableType.mjs").ChainableType<OBJ>}
+	 */
+	// @ts-expect-error
+	let proxy = null;
+
+	// @ts-expect-error
+	proxy = new Proxy(ctx, {
+		get(target, prop, receiver) {
+			if (prop === 'this') {
+				return ctx;
+			}
+			const value = Reflect.get(target, prop, receiver);
+
+			if (typeof value === 'function') {
+				// @ts-expect-error
+				return (...args) => {
+					value.apply(target, args);
+					return proxy;
+				};
+			}
+
+			return value;
+		},
+		set(target, prop, value) {
+			// @ts-expect-error
+			target[prop] = value;
+			return true;
+		},
+	});
+	return proxy;
+}