vivth 0.11.1 → 1.0.0

package/types/src/function/TsToMjs.d.mts

@@ -0,0 +1,4 @@
+export function TsToMjs(path_: string, { overrideDir, encoding }?: {
+    overrideDir?: string;
+    encoding?: BufferEncoding;
+}): Promise<void>;

package/types/src/function/WriteFileSafe.d.mts

@@ -0,0 +1,2 @@
+export function WriteFileSafe(outFile: string, content: string, options: import("node:fs").WriteFileOptions): Promise<ReturnType<typeof TryAsync<void>>>;
+import { TryAsync } from './TryAsync.mjs';

package/types/src/types/{AnyButUndefined.type.d.mts → AnyButUndefined.d.mts}

@@ -1 +1,4 @@
+/**
+ * - type helper for ID or objects;
+ */
 export type AnyButUndefined = {} | null | number | string | boolean | symbol | bigint | Function;

package/types/src/types/ExtnameType.d.mts

@@ -0,0 +1,4 @@
+/**
+ * - jsRuntime extention naming convention;
+ */
+export type ExtnameType = `.${string}`;

package/types/src/types/IsListSignal.d.mts

@@ -0,0 +1,4 @@
+/**
+ * - `EnvSignal.get` argument whether signal need to be a list or not;
+ */
+export type IsListSignal = boolean;

package/types/src/types/ListArg.d.mts

@@ -0,0 +1,4 @@
+/**
+ * - ListSignal argument type;
+ */
+export type ListArg = Record<string, string>;

package/types/src/types/MutationType.d.mts

@@ -0,0 +1,5 @@
+/**
+ * - instance method: serves as helper to mutate, and notify for `effects`;
+ * > - `slice` uses `splice` in the background, you don't need to manually reindex when using it;
+ */
+export type MutationType = "push" | "unshift" | "splice" | "swap" | "modify" | "shift" | "remove";

package/types/src/types/QCBFIFOReturn.d.mts

@@ -0,0 +1,4 @@
+/**
+ * - return type of Q callback fifo;
+ */
+export type QCBFIFOReturn = Omit<import("./QCBReturn.mjs").QCBReturn, "isLastOnQ">;

package/types/src/types/QCBReturn.d.mts

@@ -0,0 +1,7 @@
+/**
+ * - return type of Q callback;
+ */
+export type QCBReturn = {
+    resume: () => void;
+    isLastOnQ: boolean;
+};

package/src/class/$.mjs

@@ -1,68 +0,0 @@
-// @ts-check
-
-import { PingFIFO } from './PingFIFO.mjs';
-import { isAsync } from '../common.mjs';
-
-/**
- * @description
- * - a class to `autosubscribe` to an signal changes (`Derived` and `Signal` alike);
- * - for minimal total bundle size use `function` [New$](#new$) instead;
- */
-export class $ {
-	/**
-	 * @typedef {import('../class/Signal.mjs').Signal} Signal
-	 */
-	/**
-	 * @type {Map<$, Set<Signal>>}
-	 */
-	static effects = new Map();
-	/**
-	 * @type {Map<Signal, Set<$>>}
-	 */
-	static mappedSignals = new Map();
-	/**
-	 * @type {Set<Signal>}
-	 */
-	static activeSignal = new Set();
-	/**
-	 * @type {boolean}
-	 */
-	static isRegistering = false;
-	/**
-	 * @returns {void}
-	 */
-	remove$ = () => {
-		$.effects.get(this)?.forEach((signalInstance) => {
-			$.mappedSignals.get(signalInstance).delete(this);
-		});
-		$.effects.set(this, new Set());
-	};
-	/**
-	 * @type {()=>void}
-	 */
-	effect;
-	/**
-	 * @param {$["effect"]} effect
-	 */
-	constructor(effect) {
-		this.effect = effect;
-		new PingFIFO(async () => {
-			$.isRegistering = true;
-			if (isAsync(effect)) {
-				await effect();
-			} else {
-				effect();
-			}
-			$.isRegistering = false;
-			const signalInstances = $.activeSignal;
-			$.effects.set(this, $.activeSignal);
-			signalInstances.forEach((signal) => {
-				if (!$.mappedSignals.has(signal)) {
-					$.mappedSignals.set(signal, new Set());
-				}
-				$.mappedSignals.get(signal).add(this);
-			});
-			$.activeSignal = new Set();
-		});
-	}
-}

package/src/class/PingFIFO.mjs

@@ -1,78 +0,0 @@
-// @ts-check
-
-import { timeout } from '../common.mjs';
-
-/**
- * @description
- * ```js
- * /**
- *  * @typedef {[callback:()=>(any|Promise<any>),debounce?:(number)]} queueFIFODetails
- *  *[blank]/
- * ```
- * - a class for Queue;
- * - function to auto queue callbacks that will be called `first in first out` style;
- * ```js
- * // @ts-check
- * import { PingFIFO } from 'vivth';
- * const debounceMS = 0; // in miliseconds, optionals, default is 0;
- * const handler = () =>{
- * 	new PingFIFO(async () => {
- * 		// your code
- * 	}, debounceMS);
- * }
- * ```
- * - this class provides `QFIFO.makeQClass`;
- * >- this method will setup `QFIFO` to use the inputed `queueArray`(as arg0) as centralized lookup for queue managed by `QFIFO`;
- * >- usefull to modify this class for browser runtime, since `vivth` cannot just refer to window, you can just add `window["someobject"]`: `Array<queueFIFODetails>` as lookups;
- */
-export class PingFIFO {
-	/**
-	 * @param {queueFIFODetails[]} queueArray
-	 * @returns {typeof PingFIFO}
-	 */
-	static makeQClass = (queueArray) => {
-		PingFIFO.#queue = queueArray;
-		return PingFIFO;
-	};
-	/**
-	 * @type {queueFIFODetails[]}
-	 */
-	static #queue = [];
-	/**
-	 * @type {boolean}
-	 */
-	static #isRunning = false;
-	/**
-	 * @param {()=>(any|Promise<any>)} callback
-	 * @param {number} [debounce]
-	 */
-	constructor(callback, debounce = 0) {
-		PingFIFO.#push([callback, debounce]);
-		if (PingFIFO.#isRunning) {
-			return;
-		}
-		PingFIFO.#run();
-	}
-	/**
-	 * @param {queueFIFODetails} _queue
-	 */
-	static #push = (_queue) => {
-		PingFIFO.#queue.push(_queue);
-	};
-	static #run = async () => {
-		PingFIFO.#isRunning = true;
-		while (PingFIFO.#queue.length !== 0) {
-			const [callback, debounceMs = 0] = PingFIFO.#queue[0];
-			PingFIFO.#queue.shift();
-			await callback();
-			/**
-			 * conditional debounce;
-			 * queue FIFO messing up when have debouncer while `debounceMS` are set to 0;
-			 */
-			// if (debounceMs) {
-			await timeout(debounceMs);
-			// }
-		}
-		PingFIFO.#isRunning = false;
-	};
-}

package/src/class/PingUnique.mjs

@@ -1,84 +0,0 @@
-// @ts-check
-
-import { timeout } from '../common.mjs';
-
-/**
- * @description
- * - a class for Queue;
- * > - different `uniqueID`: called `first in first out` style;
- * > - same `uniqueID`: will be grouped, only the already running callback and the last callback will be called;
- * ```js
- * // @ts-check
- * import { PingUnique } from 'vivth';
- * const uniqueID = 'yourUniqueID'; // can be anything, even a reference to an object;
- * const debounceMS = 0; // in miliseconds, optionals, default is 0;
- * const handler = () =>{
- *  new PingUnique(uniqueID, async () => {
- * 		// your code
- * 	}, debounceMS);
- * }
- * ```
- * - this class provides `QUnique.makeQClass`;
- * >- this method will setup `QUnique` to use the inputed `queueMap`(as arg0) as centralized lookup for queue managed by `QUnique`;
- * >- usefull to modify this class for browser runtime, since `vivth` cannot just refer to window, you can just add `window["someobject"]`: `Map<any, [()=>Promise<any>,number]>` as lookups;
- */
-export class PingUnique {
-	/**
-	 * @param {Map<any, [()=>Promise<void>,number]>} queueMap
-	 * @returns {typeof PingUnique}
-	 */
-	static makeQClass = (queueMap) => {
-		PingUnique.#queue = queueMap;
-		return PingUnique;
-	};
-	/**
-	 * @type {Map<any, [()=>Promise<void>,number]>}
-	 */
-	static #queue = new Map();
-	/**
-	 * @type {boolean}
-	 */
-	static #isRunning = false;
-	/**
-	 * @param {any} id
-	 * @param {()=>Promise<void>} callback
-	 * @param {number} [debounceMS]
-	 */
-	constructor(id, callback, debounceMS = 0) {
-		PingUnique.#push(id, callback, debounceMS);
-		if (!PingUnique.#isRunning) {
-			PingUnique.#run();
-		}
-	}
-	/**
-	 * @param {any} id
-	 * @param {()=>Promise<void>} callback
-	 * @param {number} debounceMS
-	 */
-	static #push = (id, callback, debounceMS) => {
-		PingUnique.#queue.set(id, [callback, debounceMS ? debounceMS : 0]);
-	};
-	static #run = async () => {
-		PingUnique.#isRunning = true;
-		const keysIterator = PingUnique.#queue.keys();
-		let keys = keysIterator.next();
-		while (!keys.done) {
-			const key = keys.value;
-			const q = PingUnique.#queue.get(key);
-			if (!q) {
-				return;
-			}
-			const [callback, debounce] = q;
-			PingUnique.#queue.delete(key);
-			/**
-			 * debounce anyway;
-			 * queue with unique id have characteristic of messing up when have no debouncer;
-			 * especially when request comes too fast;
-			 */
-			await timeout(debounce);
-			await callback();
-			keys = keysIterator.next();
-		}
-		PingUnique.#isRunning = false;
-	};
-}

package/src/class/Q.mjs

@@ -1,98 +0,0 @@
-// @ts-check
-
-/**
- * @description
- * - class that containts static methods to generate Promise based `awaiter` inside async function, to prevent race condition, including but not limited to:
- * > - modifying the same `Map`, `Set`(etc.) `Object`/`Instance` inside a `Promise.all`/any code that might fired simultanously;
- * ```js
- * import { Q } from 'vivth';
- *
- * const handler = async () => {
- * 	// your code;
- * 	const { resume } = await Q.fifo() // or await Q.unique(uniqueID);
- * 	// your code that modifies and/or access same `Map`;
- * 	resume();
- * 	// the rest of your code;
- * 	return;
- * }
- *
- * const runtime = async () => {
- * 	// await Promise.all(handler1, handler2, ..., handlern);
- * }
- *
- * runtime();
- * ```
- * - behaviour:
- * > - `fifo`: call all queued callback `first in first out` style;
- * > - `unique`: call all queued callback with the same `uniqueID` `first in first out` style, if the `uniqueID` is different it will be called in parallel;
- * - this class provides `Q.makeQClass`;
- * >- this method will setup `Q` to use the inputed `uniqueMap`(as arg0) as centralized lookup for queue managed by `Q`;
- * >- usefull to modify this class for browser runtime, since `vivth` cannot just refer to window, you can just add `window["someobject"]`: `Array<Map<any, Promise<any>>>` as lookups;
- */
-export class Q {
-	/**
-	 * @param {Map<any, Promise<any>>} uniqueMap
-	 * @returns {typeof Q}
-	 */
-	static makeQClass = (uniqueMap) => {
-		Q.#unique = uniqueMap;
-		return Q;
-	};
-	/**
-	 * @typedef {import('../types/AnyButUndefined.type.mjs').AnyButUndefined} anyButUndefined
-	 */
-	/**
-	 * @type {Promise<void>}
-	 */
-	static #fifo = Promise.resolve();
-	/**
-	 * Blocks execution for subsequent calls until the current one finishes.
-	 * @returns {Promise<{resume:()=>void}>} Resolves when it's safe to proceed, returning a cleanup function
-	 */
-	static fifo = async () => {
-		let resolveFn;
-		const next = new Promise((resolve) => {
-			resolveFn = resolve;
-		});
-		const prev = Q.#fifo;
-		Q.#fifo = next;
-		await prev;
-		return {
-			resume: () => {
-				resolveFn(); // Resolve the current task
-			},
-		};
-	};
-	/**
-	 * @type {Map<any, Promise<any>>}
-	 */
-	static #unique = new Map();
-	/**
-	 * 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
-	 * @returns {Promise<{resume:()=>void}>} Resolves when it's safe to proceed for the given id, returning a cleanup function
-	 */
-	static unique = async (id) => {
-		if (!Q.#unique.has(id)) {
-			Q.#unique.set(id, Promise.resolve());
-			let resolveFn;
-			const next = new Promise((resolve) => {
-				resolveFn = resolve;
-			});
-			const prev = Q.#unique.get(id);
-			Q.#unique.set(id, next);
-			await prev;
-			return {
-				resume: () => {
-					resolveFn();
-					Q.#unique.delete(id);
-				},
-			};
-		} else {
-			const prev = Q.#unique.get(id);
-			await prev;
-			return await Q.unique(id);
-		}
-	};
-}

package/src/class/QFIFO.mjs

@@ -1,66 +0,0 @@
-// @ts-check
-
-import { timeout } from '../common.mjs';
-
-/**
- * @description
- * ```js
- * /**
- *  * @typedef {[callback:()=>(any|Promise<any>),debounce?:(number)]} queueFIFODetails
- *  *[blank]/
- * ```
- * - a class for Queue;
- * - for minimal total bundle size use `function` [NewPingFIFO](#newpingfifo) instead;
- * - this class provides `QFIFO.makeQClass`;
- * >- this method will setup `QFIFO` to use the inputed `queueArray`(as arg0) as centralized lookup for queue managed by `QFIFO`;
- * >- usefull to modify this class for browser runtime, since `vivth` cannot just refer to window, you can just add `window["someobject"]`: `Array<queueFIFODetails>` as lookups;
- */
-export class QFIFO {
-	/**
-	 * @param {queueFIFODetails[]} queueArray
-	 * @returns {typeof QFIFO}
-	 */
-	static makeQClass = (queueArray) => {
-		QFIFO.#queue = queueArray;
-		return QFIFO;
-	};
-	/**
-	 * @type {queueFIFODetails[]}
-	 */
-	static #queue = [];
-	/**
-	 * @type {boolean}
-	 */
-	static #isRunning = false;
-	/**
-	 * @type {(...queueFIFODetails:queueFIFODetails)=>void}
-	 */
-	static assign = (..._queue) => {
-		QFIFO.#push(_queue);
-		if (!QFIFO.#isRunning) {
-			QFIFO.#run();
-		}
-	};
-	/**
-	 * @param {queueFIFODetails} _queue
-	 */
-	static #push = (_queue) => {
-		QFIFO.#queue.push(_queue);
-	};
-	static #run = async () => {
-		QFIFO.#isRunning = true;
-		while (QFIFO.#queue.length !== 0) {
-			const [callback, debounceMs = 0] = QFIFO.#queue[0];
-			QFIFO.#queue.shift();
-			await callback();
-			/**
-			 * conditional debounce;
-			 * queue FIFO messing up when have debouncer while `debounceMS` are set to 0;
-			 */
-			// if (debounceMs) {
-			await timeout(debounceMs);
-			// }
-		}
-		QFIFO.#isRunning = false;
-	};
-}

package/src/class/QUnique.mjs

@@ -1,75 +0,0 @@
-// @ts-check
-
-import { timeout } from '../common.mjs';
-
-/**
- * @description
- * - a class for Queue;
- * - for minimal total bundle size use `function` [NewPingUnique](#newpingunique) instead;
- * - this class provides `QUnique.makeQClass`;
- * >- this method will setup `QUnique` to use the inputed `queueMap`(as arg0) as centralized lookup for queue managed by `QUnique`;
- * >- usefull to modify this class for browser runtime, since `vivth` cannot just refer to window, you can just add `window["someobject"]`: `Map<any, [()=>Promise<any>,number]>` as lookups;
- */
-export class QUnique {
-	/**
-	 * @param {Map<any, [()=>Promise<any>,number]>} queueMap
-	 * @returns {typeof QUnique}
-	 */
-	static makeQClass = (queueMap) => {
-		QUnique.#queue = queueMap;
-		return QUnique;
-	};
-	/**
-	 * @typedef {Object} queueUniqueObject
-	 * @property {any} i
-	 * @property {()=>(any|Promise<any>)} c
-	 * @property {number} [d]
-	 */
-	/**
-	 * @type {Map<any, [()=>Promise<any>,number]>}
-	 */
-	static #queue = new Map();
-	/**
-	 * @type {boolean}
-	 */
-	static #isRunning = false;
-	/**
-	 * @type {(queueUniqueObject:queueUniqueObject)=>void}
-	 */
-	static assign = (_queue) => {
-		QUnique.#push(_queue);
-		if (!QUnique.#isRunning) {
-			QUnique.#run();
-		}
-	};
-	/**
-	 * @param {queueUniqueObject} _queue
-	 */
-	static #push = (_queue) => {
-		const { i, c, d } = _queue;
-		QUnique.#queue.set(i, [c, d ? d : 0]);
-	};
-	static #run = async () => {
-		QUnique.#isRunning = true;
-		const keysIterator = QUnique.#queue.keys();
-		let keys = keysIterator.next();
-		while (!keys.done) {
-			const key = keys.value;
-			const q = QUnique.#queue.get(key);
-			if (!q) {
-				return;
-			}
-			const [callback, debounce] = q;
-			QUnique.#queue.delete(key);
-			/**
-			 * debounce anyway;
-			 * queue with unique id have characteristic of messing up when have no debouncer;
-			 * especially when request comes too fast;
-			 */
-			await timeout(debounce);
-			await callback();
-			keys = keysIterator.next();
-		}
-		QUnique.#isRunning = false;
-	};
-}

package/src/common.mjs

@@ -1,16 +0,0 @@
-// @ts-check
-
-/**
- * @param {number} ms
- * @returns {Promise<void>}
- */
-export const timeout = (ms) =>
-	new Promise((resolve) => {
-		setTimeout(resolve, ms);
-	});
-
-/**
- * @param {(...any:any)=>(any|Promise<any>)} fn
- * @returns {boolean}
- */
-export const isAsync = (fn) => fn.constructor.name === 'AsyncFunction';

package/src/function/NewQBlock.mjs

@@ -1,39 +0,0 @@
-// @ts-check
-
-import { Q } from '../class/Q.mjs';
-import { TryAsync } from './TryAsync.mjs';
-
-/**
- * @description
- * - a function for Queue;
- * - will wait next execution of the same `arg1`:`objectReferenceID`, without blocking other calls;
- * ```js
- * // @ts-check
- * import { NewQBlock } from 'vivth';
- *  const objectReferenceID = 'yourUniqueID'; // can be anything, reference to object is preferable;
- * const handler = () =>{
- * 	NewQBlock(async () => {
- * 		// your code
- * 	 }, objectReferenceID //- default, will refer to `arg0`:`asyncCallaback`;
- *  );
- * }
- * ```
- */
-/**
- * will wait next execution of the same `arg1`:`objectReferenceID`, without blocking other calls;
- * @param {()=>Promise<void>} asyncCallaback
- * @param {any} [objectReferenceID]
- * - default, will refer to `arg0`:`asyncCallaback`;
- */
-export const NewQBlock = (asyncCallaback, objectReferenceID = undefined) => {
-	TryAsync(async () => {
-		const { resume } = await Q.unique(objectReferenceID ?? asyncCallaback);
-		await asyncCallaback();
-		resume();
-	}).then(([_, error]) => {
-		if (!error) {
-			return;
-		}
-		console.error(error);
-	});
-};

package/types/src/class/$.d.mts

@@ -1,38 +0,0 @@
-/**
- * @description
- * - a class to `autosubscribe` to an signal changes (`Derived` and `Signal` alike);
- * - for minimal total bundle size use `function` [New$](#new$) instead;
- */
-export class $ {
-    /**
-     * @typedef {import('../class/Signal.mjs').Signal} Signal
-     */
-    /**
-     * @type {Map<$, Set<Signal>>}
-     */
-    static effects: Map<$, Set<import("../class/Signal.mjs").Signal<any>>>;
-    /**
-     * @type {Map<Signal, Set<$>>}
-     */
-    static mappedSignals: Map<import("../class/Signal.mjs").Signal<any>, Set<$>>;
-    /**
-     * @type {Set<Signal>}
-     */
-    static activeSignal: Set<import("../class/Signal.mjs").Signal<any>>;
-    /**
-     * @type {boolean}
-     */
-    static isRegistering: boolean;
-    /**
-     * @param {$["effect"]} effect
-     */
-    constructor(effect: $["effect"]);
-    /**
-     * @returns {void}
-     */
-    remove$: () => void;
-    /**
-     * @type {()=>void}
-     */
-    effect: () => void;
-}

package/types/src/class/PingFIFO.d.mts

@@ -1,57 +0,0 @@
-/**
- * @description
- * ```js
- * /**
- *  * @typedef {[callback:()=>(any|Promise<any>),debounce?:(number)]} queueFIFODetails
- *  *[blank]/
- * ```
- * - a class for Queue;
- * - function to auto queue callbacks that will be called `first in first out` style;
- * ```js
- * // @ts-check
- * import { PingFIFO } from 'vivth';
- * const debounceMS = 0; // in miliseconds, optionals, default is 0;
- * const handler = () =>{
- * 	new PingFIFO(async () => {
- * 		// your code
- * 	}, debounceMS);
- * }
- * ```
- * - this class provides `QFIFO.makeQClass`;
- * >- this method will setup `QFIFO` to use the inputed `queueArray`(as arg0) as centralized lookup for queue managed by `QFIFO`;
- * >- usefull to modify this class for browser runtime, since `vivth` cannot just refer to window, you can just add `window["someobject"]`: `Array<queueFIFODetails>` as lookups;
- */
-export class PingFIFO {
-    /**
-     * @param {queueFIFODetails[]} queueArray
-     * @returns {typeof PingFIFO}
-     */
-    static makeQClass: (queueArray: queueFIFODetails[]) => typeof PingFIFO;
-    /**
-     * @type {queueFIFODetails[]}
-     */
-    static "__#1@#queue": queueFIFODetails[];
-    /**
-     * @type {boolean}
-     */
-    static "__#1@#isRunning": boolean;
-    /**
-     * @param {queueFIFODetails} _queue
-     */
-    static "__#1@#push": (_queue: queueFIFODetails) => void;
-    static "__#1@#run": () => Promise<void>;
-    /**
-     * @param {()=>(any|Promise<any>)} callback
-     * @param {number} [debounce]
-     */
-    constructor(callback: () => (any | Promise<any>), debounce?: number);
-}
-/**
- * *[blank]/
- * ```
- * - a class for Queue;
- * - function to auto queue callbacks that will be called `first in first out` style;
- * ```js
- * //
- */
-export type queueFIFODetails = [callback: () => (any | Promise<any>), debounce?: (number)];