vivth 1.1.1 → 1.2.0

package/src/class/WorkerThread.mjs

@@ -2,7 +2,6 @@
 
 import { closeWorkerThreadEventObject } from '../common/eventObjects.mjs';
 import { EventCheck } from '../function/EventCheck.mjs';
-import { LazyFactory } from '../function/LazyFactory.mjs';
 import { Try } from '../function/Try.mjs';
 import { TryAsync } from '../function/TryAsync.mjs';
 import { Console } from './Console.mjs';
@@ -12,39 +11,43 @@ import { WorkerResult } from './WorkerResult.mjs';
 /**
  * @description
  * - class helper for `WorkerThread` creation;
- * @template Receive
- * @template Post
+ * - 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
  */
 export class WorkerThread {
 	/**
-	 * @type {{parentPort:()=>Promise<any>}}
+	 * @typedef {import('../types/QCBReturn.mjs').QCBReturn} QCBReturn
 	 */
-	static #parentPortRef = LazyFactory(() => {
-		return { parentPort: async () => (await import('node:worker_threads')).parentPort };
-	});
+	/**
+	 * @type {Parameters<typeof WorkerThread["setup"]>[0]}
+	 */
+	static #refs = undefined;
 	/**
 	 * @description
 	 * - need to be called and exported as new `WorkerThread` class reference;
-	 * @template Receive_
-	 * @template Post_
-	 * @param {{parentPort:()=>Promise<any>}} parentPortRef
-	 * - correct parentPort reference;
-	 * @returns {typeof WorkerThread<Receive_, Post_>}
+	 * @template RECEIVE
+	 * @template POST
+	 * @param {{parentPort:import('worker_threads')["parentPort"]}} refs
+	 * -example:
+	 * ```js
+	 * import { parentPort } from 'node:worker_threads';
+	 * ```
+	 * @returns {typeof WorkerThread<RECEIVE, POST>}
 	 * @example
 	 * import { WorkerThread } from 'vivth';
+	 * import { parentPort } from 'node:worker_threads';
 	 *
-	 * WorkerThread.setup({ parentPort: async () => await import('node:worker_threads') });
-	 * // that is the default value, if your parentPort/equivalent API is not that;
-	 * // you need to call this method;
+	 * export const MyWorkerThreadRef = WorkerThread.setup({ parentPort });
 	 */
-	static setup = (parentPortRef) => {
-		this.#parentPortRef = parentPortRef;
+	static setup(refs) {
+		WorkerThread.#refs = refs;
 		return WorkerThread;
-	};
+	}
 	/**
 	 * @returns {QChannel<WorkerThread>}
 	 */
-	#qChannel = new QChannel();
+	#qChannel = new QChannel('`WorkerThread` individuals');
 	/**
 	 * @param {any} ev
 	 */
@@ -59,9 +62,13 @@ export class WorkerThread {
 	 * import { MyWorkerThread } from './MyWorkerThread.mjs';
 	 *
 	 * const doubleWorker = new MyWorkerThread((ev, isLastOnQ) => {
-	 * 	// if(!isLastOnQ) {
+	 * 	// if(!isLastOnQ()) {
 	 * 	// 	return null; // can be used for imperative debouncing;
 	 * 	// }
+	 * 	// await fetch('some/path')
+	 * 	// if(!isLastOnQ()) {
+	 * 	// 	return;
+	 * 	// }
 	 * 	return ev = ev \* 2;
 	 * });
 	 */
@@ -71,13 +78,14 @@ export class WorkerThread {
 		Try({
 			post: async () => {
 				/**
-				 * @param {MessageEvent<Receive>|Receive} ev
+				 * @param {MessageEvent<RECEIVE>|RECEIVE} ev
 				 * @returns {Promise<void>}
 				 */
 				self.onmessage = async function (ev) {
-					const [_, error] = await TryAsync(async () => {
+					const [, error] = await TryAsync(async () => {
 						ev = ev instanceof MessageEvent ? ev.data : ev;
 						if (WorkerThread.#isCloseWorkerEvent(ev)) {
+							this_.#qChannel.close();
 							self.onmessage = null;
 							return;
 						}
@@ -96,15 +104,16 @@ export class WorkerThread {
 				};
 			},
 			parentPost: async () => {
-				const parentPort = await WorkerThread.#parentPortRef.parentPort();
+				const { parentPort } = WorkerThread.#refs;
 				/**
-				 * @param {MessageEvent<Receive>|Receive} ev
+				 * @param {MessageEvent<RECEIVE>|RECEIVE} ev
 				 * @returns {Promise<void>}
 				 */
 				const listener = async function (ev) {
-					const [_, error] = await TryAsync(async () => {
+					const [, error] = await TryAsync(async () => {
 						ev = ev instanceof MessageEvent ? ev.data : ev;
 						if (WorkerThread.#isCloseWorkerEvent(ev)) {
+							this_.#qChannel.close();
 							parentPort.off('message', listener);
 							return;
 						}
@@ -123,7 +132,7 @@ export class WorkerThread {
 				};
 				parentPort.on('message', listener);
 			},
-		}).then(([_, error]) => {
+		}).then(([, error]) => {
 			if (!error) {
 				return;
 			}
@@ -133,19 +142,19 @@ export class WorkerThread {
 	/**
 	 * @description
 	 * - type helper;
-	 * @type {(ev: Receive, isLastOnQ:boolean) => Post}
+	 * @type {(ev: RECEIVE, isLastOnQ:QCBReturn["isLastOnQ"]) => POST}
 	 */
 	handler;
 	/**
 	 * @description
 	 * - helper type, hold no actual value;
-	 * @type {Receive}
+	 * @type {RECEIVE}
 	 */
-	Receive;
+	RECEIVE;
 	/**
 	 * @description
 	 * - helper type, hold no actual value;
-	 * @type {Post}
+	 * @type {POST}
 	 */
-	Post;
+	POST;
 }

package/src/common/Base64URL.mjs

@@ -9,18 +9,23 @@
  * @param {string} mimeType
  * @param {(string:string)=>string} btoaFunction
  * - check your js runtime `btoa`;
- * @returns {string}
+ * - node compatible:
+ * ```js
+ * (str, prevBufferEncoding) =>
+ * 	Buffer.from(str, prevBufferEncoding).toString('base64')
+ * ```
+ * @returns {Base64URLString}
  * @example
  * import { Base64URL } from 'vivth'
- * import { fileString } from './fileString.mjs';
+ * import fileString from './fileString.mjs';
  *
  * Base64URL(fileString, 'application/javascript', btoa);
  */
-export const Base64URL = (fileString, mimeType, btoaFunction) => {
+export function Base64URL(fileString, mimeType, btoaFunction) {
 	const utf8 = new TextEncoder().encode(fileString);
 	let binary = '';
 	for (let byte of utf8) {
 		binary += String.fromCharCode(byte);
 	}
-	return `data:${mimeType};base64,${btoaFunction(binary)}`;
-};
+	return `data:${mimeType.toString()};base64,${btoaFunction(binary)}`;
+}

package/src/common/Base64URLFromFile.mjs

@@ -0,0 +1,24 @@
+// @ts-check
+
+import { readFile } from 'node:fs/promises';
+
+import { lookup } from 'mime-types';
+
+/**
+ * @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;
+ * @param {string} filePath
+ * @returns {Promise<Base64URLString>}
+ * @example
+ * import { join } from 'node:path'
+ *
+ * import { Base64URLFromFile, Paths } from 'vivth'
+ *
+ * await Base64URLFromFile(join(Paths.root, '/path/to/file'));
+ */
+export async function Base64URLFromFile(filePath) {
+	return `data:${lookup(filePath)};base64,${await readFile(filePath, { encoding: 'base64' })}`;
+}

package/src/common/keys.mjs

@@ -0,0 +1,3 @@
+// @ts-check
+
+export const keys_vivthGenereteDir = '.vivth';

package/src/doc/JSautoDOC.mjs

@@ -5,7 +5,6 @@ import { readFile, stat } from 'node:fs/promises';
 
 import chokidar from 'chokidar';
 import { EventSignal } from '../class/EventSignal.mjs';
-import { QChannel } from '../class/QChannel.mjs';
 import { parsedFile } from './parsedFile.mjs';
 import { SafeExit } from '../class/SafeExit.mjs';
 import { Effect } from '../class/Effect.mjs';
@@ -13,10 +12,9 @@ import { Paths } from '../class/Paths.mjs';
 import { Signal } from '../class/Signal.mjs';
 import { LazyFactory } from '../function/LazyFactory.mjs';
 import { TryAsync } from '../function/TryAsync.mjs';
-import { Timeout } from '../function/Timeout.mjs';
 import { Console } from '../class/Console.mjs';
 import { TsToMjs } from '../function/TsToMjs.mjs';
-import { WriteFileSafe } from '../function/WriteFileSafe.mjs';
+import { FileSafe } from '../class/FileSafe.mjs';
 
 /**
  * @typedef {import('fs').Stats} Stats
@@ -47,7 +45,7 @@ const acceptableExt = new Set(['.mjs', '.mts', '.ts']);
  * >>- `"at"description` are treated as plain `markdown`;
  * >>- first `"at"${string}` after `"at"description` until `"at"example` will be treated as `javascript` comment block on the `markdown`;
  * >>- `"at"example` are treated as `javascript` block on the `markdown` file, and should be placed last on the same comment block;
- * >>- you can always look at `vivth/src` files to check how the source, and the `README.md` and `index.mjs` is documentation/generation results;
+ * >>- you can always look at `vivth/src` files to check how the source, and the `README.md` and `index.mjs` documentation/generation results;
  */
 export class JSautoDOC {
 	/**
@@ -69,25 +67,9 @@ export class JSautoDOC {
 	 * @param {import('chokidar').ChokidarOptions} [options.option]
 	 * - ChokidarOptions;
 	 * @example
-	 * import { Console, Setup, JSautoDOC } from 'vivth';
+	 * import { JSautoDOC } from 'vivth';
 	 *
-	 * const { paths, safeExit } = Setup;
-	 *
-	 * new paths({
-	 * 	root: process?.env?.INIT_CWD ?? process?.cwd(),
-	 * });
-	 *
-	 * new safeExit({
-	 * 	exitEventNames: ['SIGINT', 'SIGTERM', 'exit'],
-	 * 	exitCallbackListeners: (eventName) => {
-	 * 		process.once(eventName, function () {
-	 * 			safeExit.instance.exiting.correction(true);
-	 * 			Console.log(`safe exit via "${eventName}"`);
-	 * 		});
-	 * 	},
-	 * });
-	 *
-	 * new JSautoDOC({
+	 *  new JSautoDOC({
 	 * 	paths: { dir: 'src', file: 'index.mjs', readMe: 'README.md' },
 	 * 	copyright: 'this library is made and distributed under MIT license;',
 	 * 	tableOfContentTitle: 'list of exported API and typehelpers',
@@ -189,39 +171,32 @@ export class JSautoDOC {
 	 * @type {Signal<string>}
 	 */
 	#readMESRCContent = LazyFactory(() => new Signal(undefined));
-	/**
-	 * @type {QChannel<JSautoDOC>}
-	 */
-	#modQ = new QChannel();
-	#generatedREADME_md = new Effect(async ({ subscribe }) => {
-		this.#modQ.callback(this, async ({ isLastOnQ }) => {
-			if (!isLastOnQ) {
-				return;
-			}
-			await Timeout(1000);
-			const contentSRC = subscribe(this.#readMESRCContent).value;
-			const filepaths = subscribe(this.#filePaths).value;
-			if (!contentSRC || !filepaths) {
-				return;
-			}
-			const { readme, mjsFile } = await this.#generateFromSRC(contentSRC, filepaths);
-			const readmePath = join(Paths.root, this.#paths.readMe);
-			const mjsFilePath = join(Paths.root, this.#paths.file);
-			const [[, errorWriteReadme], [, errorWriteMjsFile]] = await Promise.all([
-				WriteFileSafe(readmePath, readme, { encoding }),
-				WriteFileSafe(join(Paths.root, this.#paths.file), mjsFile, { encoding }),
-			]);
-			if (!errorWriteMjsFile) {
-				Console.info({ message: `successfully generate: '${mjsFilePath}'` });
-			} else {
-				Console.error({ message: `unable to generate: '${mjsFilePath}';`, errorWriteMjsFile });
-			}
-			if (!errorWriteReadme) {
-				Console.info({ message: `successfully generate: '${readmePath}'` });
-			} else {
-				Console.error({ message: `unable to generate: '${readmePath}';`, errorWriteReadme });
-			}
-		});
+	#generatedREADME_md = new Effect(async ({ subscribe, isLastCalled }) => {
+		const contentSRC = subscribe(this.#readMESRCContent).value;
+		const filepaths = subscribe(this.#filePaths).value;
+		if (!(await isLastCalled(100)) || !contentSRC || !filepaths) {
+			return;
+		}
+		const { readme, mjsFile } = await this.#generateFromSRC(contentSRC, filepaths);
+		if (!(await isLastCalled())) {
+			return;
+		}
+		const readmePath = join(Paths.root, this.#paths.readMe);
+		const mjsFilePath = join(Paths.root, this.#paths.file);
+		const [[, errorWriteReadme], [, errorWriteMjsFile]] = await Promise.all([
+			FileSafe.write(readmePath, readme, { encoding }),
+			FileSafe.write(mjsFilePath, mjsFile, { encoding }),
+		]);
+		if (!errorWriteReadme) {
+			Console.info({ message: `successfully generate: '${readmePath}'` });
+		} else {
+			Console.error({ message: `unable to generate: '${readmePath}';`, errorWriteReadme });
+		}
+		if (!errorWriteMjsFile) {
+			Console.info({ message: `successfully generate: '${mjsFilePath}'` });
+		} else {
+			Console.error({ message: `unable to generate: '${mjsFilePath}';`, errorWriteMjsFile });
+		}
 	});
 	/**
 	 * @param {string} string
@@ -355,12 +330,13 @@ export class JSautoDOC {
 				return;
 			}
 			dispatch.value = new parsedFile(path__, encoding);
+			await dispatch.value.parse();
 			dispatch.subscribers.notify();
 			this.#filePaths.subscribers.notify(async ({ signalInstance }) => {
 				Console.info({ [eventName]: path__ });
 				signalInstance.value.add(path__);
 			});
-		}).then(([_, error]) => {
+		}).then(([, error]) => {
 			if (!error) {
 				return;
 			}

package/src/doc/parsedFile.mjs

@@ -35,34 +35,35 @@ export class parsedFile {
 		}
 		this.#relativePath = Paths.normalize(relative(root, this.#fullPath));
 		this.#encoding = encoding;
-		this.content.parsed().then(({ details, error, exportName }) => {
-			if (error) {
-				return;
-			}
-			for (let i = 0; i < details.length; i++) {
-				const [
-					_,
-					__,
-					instanceOrStaticDef,
-					fullDescription,
-					isExport,
-					typeOfVar,
-					getterOrSetter,
-					namedVar,
-				] = details[i];
-				const interpreted = this.#interpreteArrayDesc(
-					exportName,
-					instanceOrStaticDef,
-					fullDescription,
-					isExport,
-					typeOfVar,
-					getterOrSetter,
-					namedVar
-				);
-				this.documented.readme.add(interpreted);
-			}
-		});
 	}
+	parse = async () => {
+		const { details, error, exportName } = await this.content.parsed();
+		if (error) {
+			return;
+		}
+		for (let i = 0; i < details.length; i++) {
+			const [
+				_,
+				__,
+				instanceOrStaticDef,
+				fullDescription,
+				isExport,
+				typeOfVar,
+				getterOrSetter,
+				namedVar,
+			] = details[i];
+			const interpreted = this.#interpreteArrayDesc(
+				exportName,
+				instanceOrStaticDef,
+				fullDescription,
+				isExport,
+				typeOfVar,
+				getterOrSetter,
+				namedVar
+			);
+			this.documented.readme.add(interpreted);
+		}
+	};
 	documented = LazyFactory(() => {
 		return {
 			typedef: async () => {
@@ -373,13 +374,13 @@ export class parsedFile {
 		const this_ = this;
 		return {
 			/**
-			 * @type {string}
+			 * @returns {string}
 			 */
 			get withExt() {
 				return basename(this_.#fullPath);
 			},
 			/**
-			 * @type {string}
+			 * @returns {string}
 			 */
 			get noExt() {
 				return basename(this_.#fullPath, extname(this_.#fullPath));
@@ -390,13 +391,13 @@ export class parsedFile {
 		const this_ = this;
 		return {
 			/**
-			 * @type {string}
+			 * @returns {string}
 			 */
 			get relative() {
 				return this_.#relativePath;
 			},
 			/**
-			 * @type {string}
+			 * @returns {string}
 			 */
 			get full() {
 				return this_.#fullPath;
@@ -407,13 +408,13 @@ export class parsedFile {
 		const this_ = this;
 		return {
 			/**
-			 * @type {string}
+			 * @returns {string}
 			 */
 			get relative() {
 				return dirname(this_.#relativePath);
 			},
 			/**
-			 * @type {string}
+			 * @returns {string}
 			 */
 			get full() {
 				return dirname(this_.#fullPath);
@@ -424,7 +425,7 @@ export class parsedFile {
 		const this_ = this;
 		return {
 			/**
-			 * @type {string|undefined}
+			 * @returns {string|undefined}
 			 */
 			get withDot() {
 				if (this_.isDirectory && !this_.isFile) {
@@ -433,7 +434,7 @@ export class parsedFile {
 				return extname(this_.#fullPath);
 			},
 			/**
-			 * @type {string|undefined}
+			 * @returns {string|undefined}
 			 */
 			get noDot() {
 				if (this_.isDirectory && !this_.isFile) {
@@ -515,7 +516,7 @@ export class parsedFile {
 		};
 	});
 	/**
-	 * @type {[Promise<any>, undefined]|[undefined, Error]}
+	 * @returns {[Promise<any>, undefined]|[undefined, Error]}
 	 */
 	get importAsModuleJS() {
 		const realTimePath = `${this.#fullPath}?${Date.now()}`;

package/src/function/CreateImmutable.mjs

@@ -9,14 +9,14 @@ import { TrySync } from './TrySync.mjs';
  * - function for create immutable object;
  * - usefull for binding immutable object to global for shared object:
  * >- e.g. to window object in browser;
- * @template {Object} P
- * @template {Object} O
+ * @template {Object} PARENT
+ * @template {Object} OBJECT
  * @param {string} keyName
- * @param {P} parent
- * @param {(this:P)=>O} object
+ * @param {PARENT} parent
+ * @param {(this:PARENT)=>OBJECT} object
  * @param {Object} [options]
  * @param {boolean} [options.lazy]
- * @return {O}
+ * @return {OBJECT}
  * @example
  * import { CreateImmutable } from 'vivth';
  *
@@ -29,7 +29,7 @@ import { TrySync } from './TrySync.mjs';
  * 	getMap(name_) => mappedObject.get(name_),
  * })
  */
-export const CreateImmutable = (parent, keyName, object, { lazy = true } = {}) => {
+export function CreateImmutable(parent, keyName, object, { lazy = true } = {}) {
 	if (!parent || typeof parent !== 'object') {
 		Console.error({
 			object,
@@ -39,7 +39,7 @@ export const CreateImmutable = (parent, keyName, object, { lazy = true } = {}) =
 		});
 		return;
 	}
-	let [_, error] = TrySync(() => {
+	let [, error] = TrySync(() => {
 		Object.defineProperty(parent, keyName, {
 			value: lazy ? LazyFactory(() => object.call(parent)) : object.call(parent),
 			writable: false,
@@ -48,7 +48,7 @@ export const CreateImmutable = (parent, keyName, object, { lazy = true } = {}) =
 		});
 	});
 	if (error) {
-		[_, error] = TrySync(() => {
+		[, error] = TrySync(() => {
 			parent[keyName] = lazy ? LazyFactory(() => object.call(parent)) : object.call(parent);
 		});
 	}
@@ -61,4 +61,4 @@ export const CreateImmutable = (parent, keyName, object, { lazy = true } = {}) =
 		return;
 	}
 	return parent[keyName];
-};
+}

package/src/function/EventCheck.mjs

@@ -17,11 +17,11 @@ import { EventNameSpace } from '../common/EventNameSpace.mjs';
  * // or manually {[EventNameSpace]:'worker:exit'};
  * // which either will result true;
  */
-export const EventCheck = (object, eventObject) => {
+export function EventCheck(object, eventObject) {
 	return (
 		object &&
 		typeof object === 'object' &&
 		EventNameSpace in object &&
 		object[EventNameSpace] === eventObject[EventNameSpace]
 	);
-};
+}

package/src/function/EventObject.mjs

@@ -4,9 +4,9 @@ import { EventNameSpace } from '../common/EventNameSpace.mjs';
 /**
  * @description
  * - simple object generation function helper for [EventCheck](#eventcheck), for multiple context, eg: `mainThread` <-> `workerThread`;
- * @template {string} N
- * @param {N} name
- * @returns {{[EventNameSpace]: N}}
+ * @template {string} NAME
+ * @param {NAME} name
+ * @returns {{[EventNameSpace]: NAME}}
  * @example
  * import { EventCheck } from 'vivth';
  * import { incomingMessage } from './some/where.mjs';
@@ -16,6 +16,6 @@ import { EventNameSpace } from '../common/EventNameSpace.mjs';
  * // or manually {[EventNameSpace]:'worker:exit'};
  * // which either will result true;
  */
-export const EventObject = (name) => {
+export function EventObject(name) {
 	return { [EventNameSpace]: name };
-};
+}

package/src/function/GetRuntime.mjs

@@ -0,0 +1,38 @@
+// @ts-check
+
+/**
+ * @typedef {import("../types/Runtime.mjs").Runtime} Runtime
+ */
+
+/**
+ * @type {Runtime|undefined}
+ */
+let runtime = undefined;
+
+/**
+ * @description
+ * - detects the current JavaScript runtime;
+ * @type {()=>Runtime}
+ * @example
+ * import { GetRuntime } form 'vivth';
+ *
+ * const runtime = GetRuntime();
+ */
+export function GetRuntime() {
+	if (!runtime) {
+		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 (typeof window !== 'undefined' && typeof document !== 'undefined') {
+			runtime = 'browser';
+		} else {
+			runtime = 'unknown';
+		}
+	}
+	return runtime;
+}

package/src/function/IsAsync.mjs

@@ -18,6 +18,6 @@
  * IsAsync(a); // false
  * IsAsync(b); // true
  */
-export const IsAsync = (functionReference) => {
+export function IsAsync(functionReference) {
 	return functionReference.constructor.name === 'AsyncFunction';
-};
+}