vivth 1.1.2 → 1.2.0

package/src/class/QChannel.mjs

@@ -2,13 +2,23 @@
 
 import { LazyFactory } from '../function/LazyFactory.mjs';
 import { TryAsync } from '../function/TryAsync.mjs';
+import { TrySync } from '../function/TrySync.mjs';
+import { Console } from './Console.mjs';
 
 /**
  * @description
  * - class for `Queue` handling;
- * @template {AnyButUndefined} T
+ * @template {AnyButUndefined} DEFINEDANY
  */
 export class QChannel {
+	/**
+	 * @param {string} name
+	 * - only used as helper for logging, and has nothing to do with runtime behaviour;
+	 */
+	constructor(name) {
+		this.name = name;
+		this.open();
+	}
 	/**
 	 * @typedef {import('../types/AnyButUndefined.mjs').AnyButUndefined} AnyButUndefined
 	 * @typedef {import('../types/QCBReturn.mjs').QCBReturn} QCBReturn
@@ -20,6 +30,11 @@ export class QChannel {
 	 * @param {Map<AnyButUndefined, [Promise<any>, {}]>} uniqueMap
 	 * @returns {typeof QChannel}
 	 * - usefull for Queue primitive on multiple library but single reference, like the Web by making the `Map` on `window` object;
+	 * @example
+	 * import { QChannel } from 'vivth';
+	 *
+	 * const myMappedQref = (window['myMappedQref'] = new Map());
+	 * export const MyQClass = QChannel.makeQClass(myMappedQref);
 	 */
 	static makeQClass = (uniqueMap) => {
 		QChannel.#uniquePromiser = uniqueMap;
@@ -33,9 +48,10 @@ export class QChannel {
 	 * - ensures that each id has only one task running at a time.
 	 * - calls with the same id will wait for the previous call to finish.
 	 * @param {AnyButUndefined} id
+	 * @param {QChannel} instance
 	 * @returns {Promise<QCBReturn>} Resolves when it's safe to proceed for the given id, returning a cleanup function
 	 */
-	static #uniqueCB = async (id) => {
+	static #uniqueCB = async (id, instance) => {
 		const existing = QChannel.#uniquePromiser.get(id);
 		let resolveFn;
 		const nextPromise = new Promise((resolve) => {
@@ -56,9 +72,12 @@ export class QChannel {
 		};
 		return {
 			resume,
-			get isLastOnQ() {
-				const [_, lastContext] = QChannel.#uniquePromiser.get(id);
-				return lastContext === context;
+			isLastOnQ: () => {
+				if (!QChannel.#uniquePromiser.has(id)) {
+					return false;
+				}
+				const [, lastContext] = QChannel.#uniquePromiser.get(id);
+				return instance.#shouldRun && lastContext === context;
 			},
 		};
 	};
@@ -67,7 +86,7 @@ export class QChannel {
 	 * - first in first out handler
 	 */
 	static fifo = LazyFactory(() => {
-		const qfifo = new QChannel();
+		const qfifo = new QChannel('main fifo');
 		return {
 			/**
 			 * @static fifo
@@ -91,15 +110,20 @@ export class QChannel {
 			 * @static fifo
 			 * @description
 			 * - blocks execution for subsequent calls until the current one finishes.
-			 * @template ResultType
-			 * @param {()=>Promise<ResultType>} asyncCallback
-			 * @returns {Promise<[ResultType|undefined, Error|undefined]>}
+			 * @template RESULT
+			 * @param {()=>Promise<RESULT>} asyncCallback
+			 * @returns {Promise<[RESULT|undefined, Error|undefined]>}
 			 * @example
 			 * const [result, error] = await QChannel.fifo.callback(async () = > {
 			 * 	// code
 			 * })
 			 */
-			callback: async (asyncCallback) => {
+			callback: async (
+				/**
+				 * @type {()=>Promise<RESULT>}
+				 */
+				asyncCallback
+			) => {
 				return await TryAsync(async () => {
 					const { resume } = await this.fifo.key();
 					const result = await asyncCallback();
@@ -110,17 +134,42 @@ export class QChannel {
 		};
 	});
 	/**
-	 * @type {Map<T, WeakKey>}
+	 * @type {Map<DEFINEDANY, WeakKey>}
 	 */
 	#mapped = new Map();
+	/**
+	 * @type {boolean}
+	 */
+	#shouldRun_;
+	/**
+	 * @returns {boolean}
+	 */
+	get #shouldRun() {
+		const shoulRun = this.#shouldRun_;
+		if (!shoulRun) {
+			Console.warn({ qChannel_name: this.name, message: 'is closed' });
+		}
+		return shoulRun;
+	}
 	/**
 	 * @description
-	 * - clear up all queued on the instance;
-	 * - only clear up the reference, the already called will not be stoped;
+	 * - disable queue;
+	 * - when `closed`, `isLastOnQ` will allways return `false`;
 	 * @returns {void}
 	 */
-	clear = () => {
-		this.#mapped.clear();
+	close = () => {
+		this.#shouldRun_ = false;
+		Console.info({ qChannel_name: this.name, message: 'closed' });
+	};
+	/**
+	 * @description
+	 * - enable queue;
+	 * - when `opened`, `isLastOnQ` will evaluate whether calls are actually the last of queue;
+	 * @returns {void}
+	 */
+	open = () => {
+		this.#shouldRun_ = true;
+		Console.info({ qChannel_name: this.name, message: 'opened' });
 	};
 	/**
 	 * @description
@@ -128,13 +177,13 @@ export class QChannel {
 	 * - caveat:
 	 * >- need to manually call resume();
 	 * >- slightly more performant than `callback`;
-	 * @param {T} keyID
+	 * @param {DEFINEDANY} keyID
 	 * @returns {Promise<QCBReturn>}
 	 * @example
-	 * const q = new QChannel();
+	 * const q = new QChannel('channel name');
 	 * const handler = async () => {
 	 * 	const { resume, isLastOnQ } = await q.key(keyID);
-	 * 	// if (!isLastOnQ) { // imperative debounce if needed
+	 * 	// if (!isLastOnQ()) { // imperative debounce if needed
 	 * 	// 	resume();
 	 * 	// 	return;
 	 * 	// }
@@ -146,13 +195,13 @@ export class QChannel {
 	 * handler();
 	 */
 	key = async (keyID) => {
-		const { resume } = await QChannel.#uniqueCB(this);
+		const { resume } = await QChannel.#uniqueCB(this, this);
 		const mapped = this.#mapped;
 		if (!mapped.has(keyID)) {
 			mapped.set(keyID, {});
 		}
 		resume();
-		return await QChannel.#uniqueCB(mapped.get(keyID));
+		return await QChannel.#uniqueCB(mapped.get(keyID), this);
 	};
 	/**
 	 * @description
@@ -160,25 +209,27 @@ export class QChannel {
 	 * - caveat:
 	 * >- no need to manually call resume();
 	 * >- slightly less performant than `callback`;
-	 * @template ResultType
-	 * @param {T} keyID
-	 * @param {(options:Omit<QCBReturn, "resume">)=>Promise<ResultType>} asyncCallback
-	 * @returns {Promise<[ResultType|undefined, Error|undefined]>}
+	 * @template RESULT
+	 * @param {DEFINEDANY} keyID
+	 * @param {(options:Omit<QCBReturn,
+	 * "resume">) =>
+	 * Promise<RESULT>} asyncCallback
+	 * @returns {ReturnType<typeof TryAsync<RESULT>>}
 	 * @example
-	 * const q = new QChannel();
+	 * const q = new QChannel('channel name');
 	 * const [result, error] = await q.callback(keyID, async ({ isLastOnQ }) = > {
-	 * 	// if (!isLastOnQ) { // imperative debounce if needed
+	 * 	// if (!isLastOnQ()) { // imperative debounce if needed
 	 * 	// 	return;
 	 * 	// }
 	 * 	// code
 	 * })
 	 */
-	callback = async (keyID, asyncCallback) => {
+	async callback(keyID, asyncCallback) {
 		return await TryAsync(async () => {
 			const { resume, isLastOnQ } = await this.key(keyID);
 			const result = await asyncCallback({ isLastOnQ });
 			resume();
 			return result;
 		});
-	};
+	}
 }

package/src/class/SafeExit.mjs

@@ -1,6 +1,7 @@
 // @ts-check
 
 import { TryAsync } from '../function/TryAsync.mjs';
+import { TrySync } from '../function/TrySync.mjs';
 import { Console } from './Console.mjs';
 import { Effect, setOfEffects } from './Effect.mjs';
 import { EnvSignal } from './EnvSignal.mjs';
@@ -15,7 +16,7 @@ export const safeCleanUpCBs = new Set();
  * @description
  * - class helper for describing how to Safely Response on exit events
  * - singleton;
- * @template {[string, ...string[]]} eventNames
+ * - most of functionality might need to access `SafeExit.instance.exiting`, if you get warning, you can instantiate `SafeExit` before running anything;
  */
 export class SafeExit {
 	/**
@@ -27,7 +28,13 @@ export class SafeExit {
 	/**
 	 * @description
 	 * @param {Object} options
-	 * @param {eventNames} options.eventNames
+	 * @param {[string, ...string[]]} options.eventNames
+	 * - eventNames are blank by default, you need to manually name them all;
+	 * - 'exit' will be omited, as it might cause async callbacks failed to execute;
+	 * - example:
+	 * ```js
+	 *  ['SIGINT', 'SIGTERM']
+	 * ```
 	 * @param {()=>void} options.terminator
 	 * - standard node/bun:
 	 * ```js
@@ -47,17 +54,26 @@ export class SafeExit {
 	 * 	});
 	 * };
 	 * ```
+	 * - example Deno:
+	 * ```js
+	 * (eventName) => {
+	 * 	const sig = Deno.signal(eventName);
+	 * 		for await (const _ of sig) {
+	 * 			exiting.correction(true);
+	 * 			sig.dispose();
+	 * 			Console.log(`safe exit via "${eventName}"`);
+	 * 		}
+	 * }
+	 * ```
 	 * - if your exit callback doesn't uses `process` global object you need to input on the SafeExit instantiation
 	 * @example
 	 * import { SafeExit, Console } from 'vivth';
 	 *
 	 * new SafeExit({
-	 * 	// eventNames are blank by default, you need to manually name them all;
-	 * 	// 'exit' will be omited, as it might cause async callbacks failed to execute;
 	 * 	eventNames: ['SIGINT', 'SIGTERM', ...eventNames],
-	 * 	terminator = () => process.exit(0), // OR on deno () => Deno.exit(0),
+	 * 	terminator : () => process.exit(0), // OR on deno () => Deno.exit(0),
 	 * 	// optional deno example
-	 * 	listener = (eventName) => {
+	 * 	listener : (eventName) => {
 	 * 		const sig = Deno.signal(eventName);
 	 * 			for await (const _ of sig) {
 	 * 				exiting.correction(true);
@@ -86,12 +102,12 @@ export class SafeExit {
 	 */
 	exiting = new EnvSignal(false);
 	/**
-	 * @param {eventNames} eventNames
+	 * @param {ConstructorParameters<typeof SafeExit>[0]["eventNames"]} eventNames
 	 * @returns {void}
 	 */
 	#register = (eventNames) => {
 		eventNames.forEach((eventName) => {
-			if (eventName == 'exit') {
+			if (eventName.toLowerCase() === 'exit') {
 				return;
 			}
 			this.#listener(eventName);
@@ -137,14 +153,18 @@ export class SafeExit {
 			effect.options.removeEffect();
 		});
 		for await (const cleanup of safeCleanUpCBs) {
-			const [_, error] = await TryAsync(async () => {
+			const [, error] = await TryAsync(async () => {
 				await cleanup();
 			});
 			if (!error) {
 				continue;
 			}
-			Console.error(error);
+			Console.warn(error);
+		}
+		const [, errorExitting] = TrySync(this.#exit);
+		if (!errorExitting) {
+			return;
 		}
-		this.#exit();
+		Console.error(errorExitting);
 	});
 }

package/src/class/Setup.mjs

@@ -49,9 +49,10 @@ export class Setup {
 	 * - proxy `WorkerMainThread_instance` for Setup;
 	 * @example
 	 * import { Setup } from 'vivth';
+	 * import { Worker } from 'node:worker_threads';
 	 *
 	 * Setup.workerMain({
-	 * 	workerClass: async () => await (import('worker_threads')).Worker,
+	 * 	workerClass: Worker,
 	 * 	basePath: 'public/assets/js/workers',
 	 * 	pathValidator: async (workerPath, root, base) => {
 	 * 		const res = await fetch(`${root}/${base}/${workerPath}`);
@@ -64,10 +65,12 @@ export class Setup {
 	/**
 	 * @description
 	 * - correct `parentPort` reference when needed;
+	 * - export to create new reference to be use to create new WorkerThread instance;
 	 * @example
 	 * import { Setup } from 'vivth';
+	 * import { parentPort } from 'node:worker_threads';
 	 *
-	 * Setup.workerThread({ parentPort: async () => (await import('node:worker_threads')).parentPort });
+	 * export const MyWorkerThreadRef = Setup.workerThread({parentPort});
 	 * // that is the default value, if your parentPort/equivalent API is not that;
 	 * // you need to call this method;
 	 */

package/src/class/Signal.mjs

@@ -14,9 +14,22 @@ export const setOFSignals = new Set();
 /**
  * @description
  * - a class for creating effect to signals;
- * @template Value
+ * @template VALUE
  */
 export class Signal {
+	/**
+	 * @description
+	 * - create a `Signal`;
+	 * @param {VALUE} value
+	 * @example
+	 * import { Signal, Effect } from  'vivth';
+	 *
+	 * const count = new Signal(0);
+	 */
+	constructor(value) {
+		this.#value = value;
+		setOFSignals.add(this);
+	}
 	/**
 	 * @description
 	 * - subsrcibers reference of this instance;
@@ -33,17 +46,17 @@ export class Signal {
 		 * @instance subscribers
 		 * @description
 		 * - manually notify on non primitive value or value that have depths;
-		 * @param {(options:{signalInstance:Signal<Value>})=>Promise<void>} [callback]
+		 * @param {(options:{signalInstance:Signal<VALUE>})=>Promise<void>} [callback]
 		 * @returns {void}
 		 * @example
-		 * // for deep signal like array or object you can:
+		 * import { Signal } from 'vivth';
 		 *
+		 * // for deep signal like array or object you can:
 		 * const arraySignal = new Signal([1,2]);
 		 * arraySignal.value.push(3);
 		 * arraySignal.subscribers.notify();
 		 *
 		 * // OR for more complex mutation:
-		 *
 		 * const objectSignal = new Signal({a:'test', b:'test'});
 		 * objectSignal.subscribers.notify(async ({ signalInstance }) => {
 		 * 	signalInstance.value['c'] = 'testc';
@@ -57,7 +70,7 @@ export class Signal {
 			}
 			TryAsync(async () => {
 				await callback({ signalInstance: this });
-			}).then(([_, error]) => {
+			}).then(([, error]) => {
 				if (error) {
 					Console.error({ message: 'unable to run callback', callback, error });
 					return;
@@ -70,7 +83,7 @@ export class Signal {
 	 * @param {Set<Effect>} setOfSubscribers
 	 */
 	static #notify = (setOfSubscribers) => {
-		const [_, error] = TrySync(() => {
+		const [, error] = TrySync(() => {
 			const effects = setOfSubscribers;
 			effects.forEach((effect) => {
 				if (!setOfEffects.has(effect)) {
@@ -126,38 +139,27 @@ export class Signal {
 			setOFSignals.delete(this);
 		},
 	}));
+
 	/**
-	 * @description
-	 * @param {Value} value
-	 * @example
-	 * import { Signal, Effect } from  'vivth';
-	 *
-	 * const count = new Signal(0);
-	 */
-	constructor(value) {
-		this.#value = value;
-		setOFSignals.add(this);
-	}
-	/**
-	 * @type {Value}
+	 * @type {VALUE}
 	 */
 	#prev = undefined;
 	/**
 	 * @description
 	 * - value before change;
-	 * @type {Value}
+	 * @returns {VALUE}
 	 */
 	get prev() {
 		return this.#prev;
 	}
 	/**
-	 * @type {Value}
+	 * @type {VALUE}
 	 */
 	#value;
 	/**
 	 * @description
 	 * - value after change;
-	 * @type {Value}
+	 * @returns {VALUE}
 	 * @example
 	 * import { Signal, Effect, Derived } from  'vivth';
 	 *
@@ -167,7 +169,7 @@ export class Signal {
 	 * new Effect(async ({ subscribe }) =>{
 	 * 	const countValue = subscribe(count).value; // reactive
 	 * })
-	 * const oneMoreThanCount = new Effect(async ({ subscribe }) =>{
+	 * const oneMoreThanCount = new Derived(async ({ subscribe }) =>{
 	 * 	return subscribe(count).value + 1; // reactive
 	 * })
 	 */
@@ -177,7 +179,7 @@ export class Signal {
 	/**
 	 * @description
 	 * - assign new value then automatically notify all subscribers;
-	 * @type {Value}
+	 * @type {VALUE}
 	 * @example
 	 * import { Signal } from  'vivth';
 	 *