vivth 0.9.4 → 0.11.0

package/README.md

@@ -14,79 +14,67 @@ bun i vivth
 - `vivth` technically can run in any `js runtime`, since it uses non platform specific api;
 - it is written specifically to be used as a primitives for javascript library or runtime, so there are no complex abstraction is, nor will be, added in `vivth` it self;
 
+### version
+- 0.11.x: drop function wrapper for all classes, for better runtime performance
 ## exported-api-and-type-list
 - [$](#$)
 - [Derived](#derived)
+- [PingFIFO](#pingfifo)
+- [PingUnique](#pingunique)
 - [Q](#q)
 - [Signal](#signal)
-- [New$](#new$)
-- [NewDerived](#newderived)
-- [NewPingFIFO](#newpingfifo)
-- [NewPingUnique](#newpingunique)
-- [NewSignal](#newsignal)
-- [tryAsync](#tryasync)
-- [trySync](#trysync)
+- [NewQBlock](#newqblock)
+- [TryAsync](#tryasync)
+- [TrySync](#trysync)
 <h2 id="$">$</h2>
 
-- a class to `autosubscribe` to an signal changes (`Derived` and `Signal` alike);
- for minimal total bundle size use `function` [New$](#new$) instead;
+- a class to `autosubscribe` to an signal changes (`Derived` and `Signal` alike);
 // runs everytime signal.value changes;
 return signal.value * 2;
 // runs everytime signal.value changes;
 console.log(signal.value);
 // console.log(derived.value);
 
 *) <sub>[go to exported list](#exported-api-and-type-list)</sub>
 
 <h2 id="derived">Derived</h2>
 
-- a class for creating signal which its value are derived from other signal (`Derived` and `Signal` alike);
- can be subscribed by using [New$](#new$);
- for minimal total bundle size use `function` [NewDerived](#newderived) instead;
+- a class for creating signal which its value are derived from other signal (`Derived` and `Signal` alike);
 // runs everytime signal.value changes;
 return signal.value * 2;
 // runs everytime derived.value changes;
 console.log(derived.value);
 
 *) <sub>[go to exported list](#exported-api-and-type-list)</sub>
 
-<h2 id="q">Q</h2>
-
-- class that containts static methods to generate Promise based `awaiter` inside async function, to prevent race condition, including but not limited to:
- behaviour:
-
-*) <sub>[go to exported list](#exported-api-and-type-list)</sub>
-
-<h2 id="signal">Signal</h2>
+<h2 id="pingfifo">PingFIFO</h2>
 
-- a class for creating signal;
- can be subscribed by using [New$](#new$) or [NewDerived](#newderived);
- for minimal total bundle size use `function` [NewSignal](#newSignal) instead;
+```js
 * @typedef {[callback:()=>(any|Promise<any>),debounce?:(number)]} queueFIFODetails
 */
- a class for Queue;
- function to auto queue callbacks that will be called `first in first out` style;
- this class provides `QFIFO.makeQClass`;
 
 *) <sub>[go to exported list](#exported-api-and-type-list)</sub>
 
-<h2 id="new$">New$</h2>
+<h2 id="pingunique">PingUnique</h2>
 
-- function to create `autosubscriber`;
 - syntatic sugar for [$](#$);
 // runs everytime signal.value changes;
 return signal.value * 2;
 // runs everytime signal.value changes;
 console.log(signal.value);
 // console.log(derived.value);
+- a class for Queue;
 new PingUnique(uniqueID, async () => {
- this class provides `QUnique.makeQClass`;
 
 *) <sub>[go to exported list](#exported-api-and-type-list)</sub>
 
-<h2 id="newderived">NewDerived</h2>
-
-- function to create `signal` that its value are derived from another `signal`;
 - syntatic sugar for [Derived](#derived);
 // runs everytime signal.value changes;
 return signal.value * 2;
 // runs everytime derived.value changes;
 console.log(derived.value);
-
-*) <sub>[go to exported list](#exported-api-and-type-list)</sub>
-
-<h2 id="newpingfifo">NewPingFIFO</h2>
+<h2 id="q">Q</h2>
 
-- function to auto queue callbacks that will be called `first in first out` style;
- behaviour:
- this class provides `Q.makeQClass`;
+- class that containts static methods to generate Promise based `awaiter` inside async function, to prevent race condition, including but not limited to:
 
 *) <sub>[go to exported list](#exported-api-and-type-list)</sub>
 
-<h2 id="newpingunique">NewPingUnique</h2>
+<h2 id="signal">Signal</h2>
 
-- function to auto queue callbacks:
+- a class for creating signal;
 // runs everytime signal.value changes;
 return signal.value * 2;
 // runs everytime signal.value changes;
 console.log(signal.value);
 
 *) <sub>[go to exported list](#exported-api-and-type-list)</sub>
 
-<h2 id="newsignal">NewSignal</h2>
+<h2 id="newqblock">NewQBlock</h2>
 
-- function to create `signal`;
 - syntatic sugar for [Signal](#signal);
 // runs everytime signal.value changes;
 return signal.value * 2;
 // runs everytime signal.value changes;
 console.log(signal.value);
- will wait next execution of the same `arg1`:`objectReferenceID`, without blocking other calls;
+- a function for Queue;
 const objectReferenceID = 'yourUniqueID'; // can be anything, reference to object is preferable;
 );
 
 *) <sub>[go to exported list](#exported-api-and-type-list)</sub>
 
-<h2 id="tryasync">tryAsync</h2>
+<h2 id="tryasync">TryAsync</h2>
 
 - error as value for asynchronous operation
 
 *) <sub>[go to exported list](#exported-api-and-type-list)</sub>
 
-<h2 id="trysync">trySync</h2>
+<h2 id="trysync">TrySync</h2>
 
 - error as value for synchronous operation
 

package/dev/index.mjs

@@ -24,5 +24,7 @@ new __JSDev({
 		'- `vivth` technically can run in any `js runtime`, since it uses non platform specific api;',
 		'- it is written specifically to be used as a primitives for javascript library or runtime, so there are no complex abstraction is, nor will be, added in `vivth` it self;',
 		'',
+		'### version',
+		'- 0.11.x: drop function wrapper for all classes, for better runtime performance',
 	],
 }).run();

package/index.mjs

@@ -21,18 +21,18 @@
  * - `vivth` technically can run in any `js runtime`, since it uses non platform specific api;
  * - it is written specifically to be used as a primitives for javascript library or runtime, so there are no complex abstraction is, nor will be, added in `vivth` it self;
  * 
+ * ### version
+ * - 0.11.x: drop function wrapper for all classes, for better runtime performance
  */
 export { $ } from './src/class/$.mjs';
 export { Derived } from './src/class/Derived.mjs';
+export { PingFIFO } from './src/class/PingFIFO.mjs';
+export { PingUnique } from './src/class/PingUnique.mjs';
 export { Q } from './src/class/Q.mjs';
 export { Signal } from './src/class/Signal.mjs';
-export { New$ } from './src/function/New$.mjs';
-export { NewDerived } from './src/function/NewDerived.mjs';
-export { NewPingFIFO } from './src/function/NewPingFIFO.mjs';
-export { NewPingUnique } from './src/function/NewPingUnique.mjs';
-export { NewSignal } from './src/function/NewSignal.mjs';
-export { tryAsync } from './src/function/tryAsync.export.mjs';
-export { trySync } from './src/function/trySync.export.mjs';
+export { NewQBlock } from './src/function/NewQBlock.mjs';
+export { TryAsync } from './src/function/TryAsync.mjs';
+export { TrySync } from './src/function/TrySync.mjs';
 /**
- * @typedef {{}|null|number|string|boolean|symbol|bigint|function} anyButUndefined
+ * @typedef {{}|null|number|string|boolean|symbol|bigint|function} AnyButUndefined
  */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "vivth",
-	"version": "0.9.4",
+	"version": "0.11.0",
 	"description": "extremely simple signal as library primitives",
 	"main": "index.mjs",
 	"types": "./types/index.d.mts",

package/src/class/$.mjs

@@ -1,72 +1,82 @@
 // @ts-check
 
-import { NewPingFIFO } from '../function/NewPingFIFO.mjs';
 import { isAsync } from '../common.mjs';
+import { NewQBlock } from '../function/NewQBlock.mjs';
 
 /**
  * @description
  * - a class to `autosubscribe` to an signal changes (`Derived` and `Signal` alike);
- * - for minimal total bundle size use `function` [New$](#new$) instead;
+ * ```js
+ * import { $, Derived, Signal } from 'vivth';
+ * const signal = new Signal(0);
+ * const derived = new Derived(async () =>{
+ *  // runs everytime signal.value changes;
+ *  return signal.value * 2;
+ * });
+ * const autosubscriber = new $(async ()=>{
+ *  // runs everytime signal.value changes;
+ *  console.log(signal.value);
+ *  // console.log(derived.value);
+ * });
+ * signal.value = 1;
+ * ```
  */
 export class $ {
 	/**
 	 * @typedef {import('../class/Signal.mjs').Signal} Signal
 	 */
 	/**
-	 * effects
 	 * @type {Map<$, Set<Signal>>}
 	 */
-	static E = new Map();
+	static effects = new Map();
 	/**
-	 * signalInstance
 	 * @type {Map<Signal, Set<$>>}
 	 */
-	static S = new Map();
+	static mappedSignals = new Map();
 	/**
-	 * activeSignalUponRegistering
 	 * @type {Set<Signal>}
 	 */
-	static A = new Set();
+	static activeSignal = new Set();
 	/**
-	 * isRegistering
 	 * @type {boolean}
 	 */
-	static R = false;
+	static isRegistering = false;
 	/**
 	 * @returns {void}
 	 */
 	remove$ = () => {
-		$.E.get(this)?.forEach((signalInstance) => {
-			$.S.get(signalInstance).delete(this);
-		});
-		$.E.set(this, new Set());
+		NewQBlock(async () => {
+			$.effects.get(this)?.forEach((signalInstance) => {
+				$.mappedSignals.get(signalInstance).delete(this);
+			});
+			$.effects.set(this, new Set());
+		}, $);
 	};
 	/**
-	 * @type {()=>void}
+	 * @type {(arg:{remove$:$["remove$"]})=>void};
 	 */
 	effect;
 	/**
-	 * @param {$["effect"]} effect
+	 * @param {(arg:{remove$:$["remove$"]})=>void} effect
 	 */
 	constructor(effect) {
 		this.effect = effect;
-		NewPingFIFO(async () => {
-			$.R = true;
+		NewQBlock(async () => {
+			$.isRegistering = true;
+			const check = this.effect({ remove$: this.remove$ });
 			if (isAsync(effect)) {
-				await effect();
-			} else {
-				effect();
+				await check;
 			}
-			$.R = false;
-			const signalInstances = $.A;
-			$.E.set(this, $.A);
+			$.isRegistering = false;
+			const signalInstances = $.activeSignal;
+			$.effects.set(this, $.activeSignal);
 			signalInstances.forEach((signal) => {
-				if (!$.S.has(signal)) {
-					$.S.set(signal, new Set());
+				if (!$.mappedSignals.has(signal)) {
+					$.mappedSignals.set(signal, new Set());
 				}
-				$.S.get(signal).add(this);
+				$.mappedSignals.get(signal).add(this);
 			});
-			$.A = new Set();
-		});
+			$.activeSignal = new Set();
+		}, $);
 	}
 }

package/src/class/Derived.mjs

@@ -1,14 +1,25 @@
 // @ts-check
 
 import { Signal } from './Signal.mjs';
-import { New$ } from '../function//New$.mjs';
 import { isAsync } from '../common.mjs';
+import { $ } from './$.mjs';
 
 /**
  * @description
  * - a class for creating signal which its value are derived from other signal (`Derived` and `Signal` alike);
- * - can be subscribed by using [New$](#new$);
- * - for minimal total bundle size use `function` [NewDerived](#newderived) instead;
+ * ```js
+ * import { $, Derived, Signal } from 'vivth';
+ * const signal = new Signal(0);
+ * const derived = new Derived(async () =>{
+ *  // runs everytime signal.value changes;
+ *  return signal.value * 2;
+ * });
+ * const autosubscriber = new $(async ()=>{
+ *  // runs everytime derived.value changes;
+ *  console.log(derived.value);
+ * });
+ * signal.value = 1;
+ * ```
  */
 /**
  * @template V
@@ -16,19 +27,24 @@ import { isAsync } from '../common.mjs';
  */
 export class Derived extends Signal {
 	/**
-	 * @param {()=>V} derivedFunction
+	 * @param {(arg:{remove$:$["remove$"]})=>V} derivedFunction
 	 */
 	constructor(derivedFunction) {
-		// @ts-expect-error
-		super(0);
+		super(undefined);
 		const real = isAsync(derivedFunction)
-			? async () => {
-					super.value = await derivedFunction();
+			? /**
+			   * @param {{remove$:$["remove$"]}} options
+			   */
+			  async (options) => {
+					super.value = await derivedFunction(options);
 			  }
-			: () => {
-					super.value = derivedFunction();
+			: /**
+			   * @param {{remove$:$["remove$"]}} options
+			   */
+			  (options) => {
+					super.value = derivedFunction(options);
 			  };
-		New$(real);
+		new $(real);
 	}
 	/**
 	 * @type {V}

package/src/class/PingFIFO.mjs

@@ -0,0 +1,78 @@
+// @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

@@ -0,0 +1,84 @@
+// @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

@@ -25,16 +25,26 @@
  * - 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 {
 	/**
-	 * @typedef {import('../types/anyButUndefined.type.mjs').anyButUndefined} anyButUndefined
+	 * @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
 	 */
 	/**
-	 * @private
 	 * @type {Promise<void>}
 	 */
-	static f = Promise.resolve();
+	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
@@ -44,8 +54,8 @@ export class Q {
 		const next = new Promise((resolve) => {
 			resolveFn = resolve;
 		});
-		const prev = Q.f;
-		Q.f = next;
+		const prev = Q.#fifo;
+		Q.#fifo = next;
 		await prev;
 		return {
 			resume: () => {
@@ -56,7 +66,7 @@ export class Q {
 	/**
 	 * @type {Map<any, Promise<any>>}
 	 */
-	static u = new Map();
+	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.
@@ -64,23 +74,23 @@ export class Q {
 	 * @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.u.has(id)) {
-			Q.u.set(id, Promise.resolve());
+		if (!Q.#unique.has(id)) {
+			Q.#unique.set(id, Promise.resolve());
 			let resolveFn;
 			const next = new Promise((resolve) => {
 				resolveFn = resolve;
 			});
-			const prev = Q.u.get(id);
-			Q.u.set(id, next);
+			const prev = Q.#unique.get(id);
+			Q.#unique.set(id, next);
 			await prev;
 			return {
 				resume: () => {
 					resolveFn();
-					Q.u.delete(id);
+					Q.#unique.delete(id);
 				},
 			};
 		} else {
-			const prev = Q.u.get(id);
+			const prev = Q.#unique.get(id);
 			await prev;
 			return await Q.unique(id);
 		}