vivth 1.4.9 → 1.5.0

package/src/class/WorkerMainThread.mjs

@@ -8,20 +8,18 @@ import { Console } from './Console.mjs';
 import { Derived } from './Derived.mjs';
 import { Effect } from './Effect.mjs';
 import { Paths } from './Paths.mjs';
-import { SafeExit } from './SafeExit.mjs';
 import { Signal } from './Signal.mjs';
 
 /**
- * @template POST
- * @typedef {import('./WorkerResult.mjs').WorkerResult<POST>} WorkerResult
- */
-/**
- * @template RECEIVE
- * @template POST
- * @typedef {import('./WorkerThread.mjs').WorkerThread<RECEIVE, POST>} WorkerThread
+ * it supposed to be able to call on browser too
+ * ```js
+ * import { SafeExit } from './SafeExit.mjs';
+ * ```
+ * need to add cleaner for SafeExit.instance?.addCallback
  */
+
 /**
- * @typedef {import('../common/lazie.mjs').unwrapLazy} unwrapLazy
+ * @typedef {import('../typehints/VivthCleanup.mjs').VivthCleanup} VivthCleanup
  */
 
 /**
@@ -29,8 +27,18 @@ import { Signal } from './Signal.mjs';
  * - class helper to create `Worker` instance;
  * - before any `Worker` functionaily to be used, you need to setup it with `WorkerThread.setup` and `WorkerMainThread.setup` before runing anytyhing;
  * @template {WorkerThread<any, any>} WT
+ * @implements {VivthCleanup}
  */
 export class WorkerMainThread {
+	/**
+	 * @template POST
+	 * @typedef {import('./WorkerResult.mjs').WorkerResult<POST>} WorkerResult
+	 */
+	/**
+	 * @template RECEIVE
+	 * @template POST
+	 * @typedef {import('./WorkerThread.mjs').WorkerThread<RECEIVE, POST>} WorkerThread
+	 */
 	/**
 	 * @type {boolean}
 	 */
@@ -56,7 +64,7 @@ export class WorkerMainThread {
 	 * ```
 	 * @example
 	 * import { Worker } from 'node:worker_threads';
-	 * import { WorkerMainThread } from 'vivth';
+	 * import { WorkerMainThread } from 'vivth/neutral';
 	 *
 	 * WorkerMainThread.setup({
 	 * 	workerClass: Worker,
@@ -73,10 +81,10 @@ export class WorkerMainThread {
 	 * });
 	 */
 	static setup = ({ workerClass, pathValidator }) => {
-		if (Paths.root === undefined) {
-			return;
-		}
-		if (WorkerMainThread.#isRegistered) {
+		if (
+			/** */
+			WorkerMainThread.#isRegistered
+		) {
 			Console.warn({ message: 'WorkerMainThread.setup, can only be called once' });
 			return;
 		}
@@ -103,28 +111,14 @@ export class WorkerMainThread {
 			type: 'module',
 		});
 	/**
-	 * @template {WorkerThread<any, any>} WT
 	 * @description
 	 * - create Worker_instance;
-	 * @param {string} handler
-	 * @param {Omit<WorkerOptions|import('node:worker_threads').WorkerOptions, 'eval'|'type'>} [options]
-	 * @returns {WorkerMainThread<WT>}
-	 * @example
-	 * import { WorkerMainThread } from 'vivth';
-	 *
-	 * export const myDoubleWorker = WorkerMainThread.newVivthWorker('./doubleWorkerThread.mjs');
-	 */
-	static newVivthWorker(handler, options = {}) {
-		return new WorkerMainThread(handler, options);
-	}
-	/**
-	 * @private
-	 * @param {Parameters<typeof WorkerMainThread<WT>["newVivthWorker"]>[0]} handler
-	 * @param {Parameters<typeof WorkerMainThread<WT>["newVivthWorker"]>[1]} [options]
+	 * @param {import('../bundler/adds/PathFSBundles.mjs').PathFSBundles} handler
+	 * @param {Omit<WorkerOptions|import('node:worker_threads').WorkerOptions, 'eval'|'type'>} options
 	 * @example
-	 * import { WorkerMainThread } from 'vivth';
+	 * import { WorkerMainThread } from 'vivth/neutral';
 	 *
-	 * export const myDoubleWorker = WorkerMainThread.newVivthWorker('./doubleWorkerThread.mjs');
+	 * export const myDoubleWorker = new WorkerMainThread(PathFSBundles.vivthBundles('./doubleWorkerThread.mjs'));
 	 */
 	constructor(handler, options = {}) {
 		/**
@@ -134,7 +128,7 @@ export class WorkerMainThread {
 		const listener = (ev) => {
 			this.#proxyReceiver.value = ev;
 		};
-		WorkerMainThread.#workerFilehandler(handler, options, this, listener);
+		WorkerMainThread.#workerFilehandler(handler.path, options, this, listener);
 	}
 	/**
 	 * @type {import('./Signal.mjs').Signal<import('./WorkerResult.mjs').WorkerResult<WT["POST"]>|MessageEvent<import('./WorkerResult.mjs').WorkerResult<WT["POST"]>>>}
@@ -151,99 +145,99 @@ export class WorkerMainThread {
 	 * @returns {Promise<void>}
 	 */
 	static async #workerFilehandler(handler, options, worker, listener) {
-		let resolvedPath;
 		const pathValidator = WorkerMainThread.pathValidator;
 		const [resolvedPath_, error] = await TryAsync(async () => {
-			if (Paths.root === undefined) {
-				throw new Error('path root undefined');
-			}
 			return await pathValidator({
 				worker: handler,
 				root: Paths.root,
 			});
 		});
-		if (error) {
-			Console.error({
-				error,
-				pathValidator,
-				message: 'invalid pathValidator inputed to `WorkerMainThread`;',
-			});
+		if (
+			/** */
+			error
+		) {
+			Console.error(
+				{
+					error,
+					pathValidator,
+					message: 'invalid pathValidator inputed to `WorkerMainThread`;',
+				},
+				{ now: true },
+			);
 			return;
 		}
-		resolvedPath = resolvedPath_;
+		const resolvedPath = resolvedPath_;
 		const runtime = GetRuntime();
 		const workerClass = WorkerMainThread.workerClass;
 		if (
-			//
+			/** */
 			!workerClass
 		) {
-			Console.error('invalid `Worker` inputed to `WorkerMainThread`;');
+			Console.error('invalid `Worker` inputed to `WorkerMainThread`;', { now: true });
 			return;
 		}
-		const [, errorCreatingWorker] = await Tries({
+		const [[key], errorCreatingWorker] = await Tries({
 			browser: async () => {
-				if (runtime !== 'browser') {
-					throw new Error('not a browser');
+				if (
+					/** */
+					runtime !== 'browser'
+				) {
+					throw 'not a browser';
 				}
-				let worker_;
-				worker_ = worker.#worker.value = new workerClass(
-					resolvedPath,
-					// @ts-expect-error
-					{
-						...options,
-						...WorkerMainThread.#options,
-					}
-				);
-				if ('onmessage' in worker_ === false) {
-					throw new Error('not a browser');
+				const worker_ = (worker.#worker.value = new workerClass(resolvedPath, {
+					...options,
+					...WorkerMainThread.#options,
+				}));
+				if (
+					/** */
+					'onmessage' in worker_ ===
+					false
+				) {
+					throw 'not a browser';
 				}
 				worker_.onmessage = listener;
-				if (SafeExit.instance) {
-					SafeExit.instance.addCallback(async () => {
-						worker_.onmessage = null;
-					});
-				}
+				// SafeExit.instance?.addCallback(async () => {
+				// 	worker_.onmessage = null;
+				// });
 			},
 			nonBrowser: async () => {
-				const worker_ = (worker.#worker.value = new workerClass(
-					resolvedPath,
-					// @ts-expect-error
-					{
-						...options,
-						...WorkerMainThread.#options,
-					}
-				));
-				if ('addEventListener' in worker_) {
+				const worker_ = (worker.#worker.value = new workerClass(resolvedPath, {
+					...options,
+					...WorkerMainThread.#options,
+				}));
+				if (
+					/** */
+					'addEventListener' in worker_
+				) {
 					worker_.addEventListener('message', listener);
-					if (SafeExit.instance) {
-						SafeExit.instance.addCallback(async () => {
-							worker_.removeEventListener('message', listener);
-						});
-					}
-				} else if ('addListener' in worker_) {
+					// SafeExit.instance?.addCallback(async () => {
+					// 	worker_.removeEventListener('message', listener);
+					// });
+					return;
+				}
+				if (
+					/** */
+					'addListener' in worker_
+				) {
 					worker_.addListener('message', listener);
-					if (SafeExit.instance) {
-						SafeExit.instance.addCallback(async () => {
-							worker_.removeListener('message', listener);
-						});
-					}
-				} else {
-					throw new Error('not a standard non browser');
+					// SafeExit.instance?.addCallback(async () => {
+					// 	worker_.removeListener('message', listener);
+					// });
+					return;
 				}
+				throw 'not a standard non browser';
 			},
 		});
-		if (errorCreatingWorker) {
-			Console.error(errorCreatingWorker);
+		if (
+			/** */
+			!key
+		) {
+			Console.error({ errorCreatingWorker }, { now: true });
 			return;
 		}
-		if (SafeExit.instance) {
-			SafeExit.instance.addCallback(async () => {
-				if (worker.#worker.value) {
-					worker.#worker.value.postMessage(closeWorkerThreadEventObject, []);
-				}
-				worker.terminate();
-			});
-		}
+		// SafeExit.instance?.addCallback(async () => {
+		// 	worker.terminate();
+		// });
 	}
 	/**
 	 * lazyly generated because node version need to await
@@ -258,7 +252,11 @@ export class WorkerMainThread {
 	#handler = new Effect(async ({ subscribe }) => {
 		const postData = subscribe(this.#proxyPost).value;
 		const worker = subscribe(this.#worker).value;
-		if (worker === undefined || postData === undefined) {
+		if (
+			/** */
+			worker === undefined ||
+			postData === undefined
+		) {
 			return;
 		}
 		worker.postMessage(postData, []);
@@ -266,9 +264,9 @@ export class WorkerMainThread {
 	/**
 	 * @description
 	 * - terminate all signals that are used on this instance;
-	 * @return {void}
+	 * @return {Promise<void>}
 	 */
-	terminate = () => {
+	vivthCleanup = async () => {
 		this.postMessage(closeWorkerThreadEventObject);
 		/**
 		 * this is more for browser, as most of this are automatically cleaned with `SafeExit`;
@@ -285,7 +283,7 @@ export class WorkerMainThread {
 	 * - result signal of the processed message;
 	 * @type {Derived<WorkerResult<WT["POST"]>>}
 	 * @example
-	 * import { Effect } from 'vivth';
+	 * import { Effect } from 'vivth/neutral';
 	 * import { myDoubleWorker } from './myDoubleWorker.mjs';
 	 *
 	 * const doubleReceiverSignal = myDoubleWorker.receiverSignal;
@@ -296,7 +294,10 @@ export class WorkerMainThread {
 	 */
 	receiverSignal = new Derived(async ({ subscribe }) => {
 		const val = subscribe(this.#proxyReceiver).value;
-		if (val instanceof MessageEvent) {
+		if (
+			/** */
+			val instanceof MessageEvent
+		) {
 			return val.data;
 		}
 		return val;

package/src/class/WorkerThread.mjs

@@ -1,23 +1,38 @@
 // @ts-check
+/// <reference lib='dom' />
 
 import { closeWorkerThreadEventObject } from '../common/eventObjects.mjs';
 import { EventCheck } from '../function/EventCheck.mjs';
+import { LazyFactory } from '../function/LazyFactory.mjs';
 import { Tries } from '../function/Tries.mjs';
 import { TryAsync } from '../function/TryAsync.mjs';
 import { Console } from './Console.mjs';
 import { QChannel } from './QChannel.mjs';
 import { WorkerResult } from './WorkerResult.mjs';
 
+/**
+ * @typedef { import('../typehints/VivthCleanup.mjs').VivthCleanup } VivthCleanup
+ */
+
 /**
  * @description
  * - class helper for `WorkerThread` creation;
  * - before any `Worker` functionaily to be used, you need to setup it with `WorkerThread.setup` and `WorkerMainThread.setup` before runing anytyhing;
  * @template RECEIVE
  * @template POST
+ * @implements {VivthCleanup}
  */
 export class WorkerThread {
+	vivthCleanup = async () => {
+		WorkerThread.#refs?.parentPort?.removeAllListeners();
+		WorkerThread.#refs?.parentPort?.close();
+	};
 	/**
-	 * @typedef {import('../types/QCBReturn.mjs').QCBReturn} QCBReturn
+	 * @returns {QChannel<WorkerThread>}
+	 */
+	#q = LazyFactory(() => new QChannel('WorkerThread'));
+	/**
+	 * @typedef {import('../typehints/QCBReturn.mjs').QCBReturn} QCBReturn
 	 */
 	/**
 	 * @type {Parameters<typeof WorkerThread["setup"]>[0]|undefined}
@@ -35,8 +50,8 @@ export class WorkerThread {
 	 * ```
 	 * @returns {typeof WorkerThread<RECEIVE, POST>}
 	 * @example
-	 * import { WorkerThread } from 'vivth';
 	 * import { parentPort } from 'node:worker_threads';
+	 * import { WorkerThread } from 'vivth/neutral';
 	 *
 	 * export const MyWorkerThreadRef = WorkerThread.setup({ parentPort });
 	 */
@@ -44,10 +59,6 @@ export class WorkerThread {
 		WorkerThread.#refs = refs;
 		return WorkerThread;
 	}
-	/**
-	 * @returns {QChannel<WorkerThread>}
-	 */
-	#qChannel = new QChannel('`WorkerThread` individuals');
 	/**
 	 * @param {any} ev
 	 */
@@ -82,30 +93,26 @@ export class WorkerThread {
 				 * @param {MessageEvent<RECEIVE>|RECEIVE} ev
 				 * @returns {Promise<void>}
 				 */
-				// @ts-expect-error
 				self.onmessage = async function (ev) {
 					const [, error] = await TryAsync(async () => {
 						ev = ev instanceof MessageEvent ? ev.data : ev;
 						if (WorkerThread.#isCloseWorkerEvent(ev)) {
-							this_.#qChannel.close();
-							// @ts-expect-error
+							this_.#q.close();
 							self.onmessage = null;
 							return;
 						}
-						const [data, error] = await this_.#qChannel.callback(this, async ({ isLastOnQ }) => {
+						const [data, error] = await this_.#q.callback(this, async ({ isLastOnQ }) => {
 							// @ts-expect-error
 							return await handler(ev, isLastOnQ);
 						});
 						if (error) {
 							throw error;
 						}
-						// @ts-expect-error
 						self.postMessage(new WorkerResult(data, undefined));
 					});
 					if (error === undefined) {
 						return;
 					}
-					// @ts-expect-error
 					self.postMessage(new WorkerResult(undefined, error?.message ?? 'Unknown error'));
 				};
 			},
@@ -125,11 +132,11 @@ export class WorkerThread {
 					const [, error] = await TryAsync(async () => {
 						ev = ev instanceof MessageEvent ? ev.data : ev;
 						if (WorkerThread.#isCloseWorkerEvent(ev)) {
-							this_.#qChannel.close();
+							this_.#q.close();
 							parentPort.off('message', listener);
 							return;
 						}
-						const [data, error] = await this_.#qChannel.callback(this_, async ({ isLastOnQ }) => {
+						const [data, error] = await this_.#q.callback(this_, async ({ isLastOnQ }) => {
 							// @ts-expect-error
 							return await handler(ev, isLastOnQ);
 						});
@@ -145,11 +152,11 @@ export class WorkerThread {
 				};
 				parentPort.on('message', listener);
 			},
-		}).then(([, error]) => {
-			if (error === undefined) {
+		}).then(([, errorMakingWorkerThread]) => {
+			if (errorMakingWorkerThread === undefined || !errorMakingWorkerThread.size) {
 				return;
 			}
-			Console.error(error);
+			Console.error({ errorMakingWorkerThread }, { now: true });
 		});
 	}
 	/**

package/src/common/Base64URL.mjs

@@ -1,5 +1,7 @@
 // @ts-check
 
+import { ForOfSync } from '../function/ForOfSync.mjs';
+
 /**
  * @description
  * - create inline base64 url;
@@ -17,7 +19,8 @@
  * ```
  * @returns {string}
  * @example
- * import { Base64URL } from 'vivth'
+ * import { Base64URL } from 'vivth/neutral';
+ *
  * import fileString from './fileString.mjs';
  *
  * // example for browser;
@@ -26,8 +29,8 @@
 export function Base64URL(fileString, mimeType, btoaFunction) {
 	const utf8 = new TextEncoder().encode(fileString);
 	let binary = '';
-	for (let byte of utf8) {
+	ForOfSync(utf8, (byte) => {
 		binary += String.fromCharCode(byte);
-	}
+	});
 	return `data:${mimeType.toString()};base64,${btoaFunction(binary)}`;
 }

package/src/common/Base64URLFromFile.mjs

@@ -4,21 +4,34 @@ import { readFile } from 'node:fs/promises';
 
 import { lookup } from 'mime-types';
 
+import { TryAsync } from '../function/TryAsync.mjs';
+import { Console } from '../class/Console.mjs';
+
 /**
  * @description
  * - create inline base64 url;
  * - usage:
  * >- can be extremely usefull to display file on desktop app webview, without exposing http server;
- * >- when using `FSInline`, use [Base64URL](#base64url) instead;
+ * >- when using `FSasar`, use [Base64URL](#base64url) instead;
  * @param {string} filePath
- * @returns {Promise<string>}
+ * @returns {Promise<{data:string, mime:string|false}|undefined>}
  * @example
  * import { join } from 'node:path'
  *
- * import { Base64URLFromFile, Paths } from 'vivth'
+ * import { Base64URLFromFile } from 'vivth/node';
+ * import { Paths } from 'vivth/neutral';
  *
  * await Base64URLFromFile(join(Paths.root, '/path/to/file'));
  */
 export async function Base64URLFromFile(filePath) {
-	return `data:${lookup(filePath)};base64,${await readFile(filePath, { encoding: 'base64' })}`;
+	const [res, errorBase64URLFromFile] = await TryAsync(async () => {
+		const mime = lookup(filePath);
+		const data = `data:${lookup(filePath)};base64,${await readFile(filePath, { encoding: 'base64' })}`;
+		return { data, mime };
+	});
+	if (errorBase64URLFromFile) {
+		Console.error({ errorBase64URLFromFile });
+		return;
+	}
+	return res;
 }

package/src/common/BundledV.bundled.mjs

@@ -0,0 +1,7 @@
+// @ts-check
+
+export class BundledV {
+	static get isBundled() {
+		return true;
+	}
+}

package/src/common/BundledV.mjs

@@ -0,0 +1,45 @@
+// @ts-check
+
+/**
+ * @description
+ * - class helper for `vivth` `Bundled` values;
+ */
+export class BundledV {
+	static #isBundled = false;
+	/**
+	 * @description
+	 * - readonly value of whether the script run after being bundled with `vivth` or not;
+	 * @readonly
+	 * @type {boolean}
+	 * @example
+	 * import { BundledV } from 'vivth/neutral';
+	 *
+	 * if(BundledV.isBundled){
+	 * 	// code
+	 * }
+	 */
+	static get isBundled() {
+		return BundledV.#isBundled;
+	}
+	/**
+	 * @description
+	 * - to create `unbundled` only codeBlock;
+	 * >- when properly bundled via `vivth` bundling mechanism, this code block will be removed;
+	 * @param {()=>void} callback
+	 * @param {import('./VivthUnBundledCodeBlock.mjs').VivthUnBundledCodeBlock} _closing
+	 * - must be filled for regexp detection;
+	 * @returns {void}
+	 * @example
+	 * import { BundledV } from 'vivth/neutral';
+	 *
+	 * BundledV.vivthUnBundledCodeBlock(() => {
+	 * 	// code
+	 * }, 'vivthUnBundledCodeBlock')
+	 */
+	static vivthUnBundledCodeBlock = (callback, _closing) => {
+		if (BundledV.isBundled) {
+			return;
+		}
+		callback();
+	};
+}

package/src/common/CreateStringID.mjs

@@ -5,7 +5,7 @@ import { LazyFactory } from '../function/LazyFactory.mjs';
 import { Timeout } from '../function/Timeout.mjs';
 import { TryAsync } from '../function/TryAsync.mjs';
 
-const qchannel = LazyFactory(() => new QChannel('CreateStringID'));
+const q = LazyFactory(() => new QChannel('CreateStringID'));
 
 /**
  * @description
@@ -13,21 +13,22 @@ const qchannel = LazyFactory(() => new QChannel('CreateStringID'));
  * - the asynchrounous nature is to prevent race condition that might resulting same Id being generated;
  * >- queued using QChannel;
  * @param {string} [prefix]
+ * @param {string} [suffix]
  * @returns {ReturnType<typeof TryAsync<string>>}
  * @example
- * import { CreateStringID } from 'vivth';
+ * import { CreateStringID } from 'vivth/neutral';
  *
  * (async () => {
- * 	const [myUniqueID, errorCreatingUniqueID] = await CreateStringID('myPrefix');
+ * 	const [myUniqueID, errorCreatingUniqueID] = await CreateStringID('myPrefix', 'mySuffix');
  * 	if(errorCreatingUniqueID) {
  * 		return;
  * 	}
- * 	Console.log(myUniqueID); // `myPrefix${Date.now()}`
+ * 	Console.log(myUniqueID); // `myPrefix${Date.now()}mySuffix`
  * })()
  */
-export async function CreateStringID(prefix = '') {
-	return await qchannel.callback('newStringID', async () => {
+export async function CreateStringID(prefix = '', suffix = '') {
+	return await q.callback('newStringID', async () => {
 		await Timeout(1);
-		return `${prefix}${Date.now()}`;
+		return `${prefix}${Date.now()}${suffix}`;
 	});
 }