vivth 0.9.4 → 0.11.0

package/src/class/Signal.mjs

@@ -5,33 +5,43 @@ import { $ } from './$.mjs';
 /**
  * @description
  * - 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
+ * 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);
+ * });
+ * signal.value = 1;
+ * ```
  */
 /**
  * @template Value
  */
 export class Signal {
 	/**
-	 * subscribed
 	 * @protected
 	 */
-	get S() {
-		return $.S.get(this);
+	get subscribed() {
+		return $.mappedSignals.get(this);
 	}
 	/**
 	 * destroy all props
 	 */
 	unRef = () => {
 		this.removeAll$();
-		this.V = null;
+		this.#Value = null;
 	};
 	/**
 	 * remove all effects
 	 * @return {void}
 	 */
 	removeAll$ = () => {
-		this.S?.forEach(($_) => {
+		this.subscribed?.forEach(($_) => {
 			$_.remove$();
 		});
 	};
@@ -41,7 +51,7 @@ export class Signal {
 	 * @return {void}
 	 */
 	remove$ = ($_) => {
-		if ($.E.get($_)?.has(this)) {
+		if ($.effects.get($_)?.has(this)) {
 			$_.remove$();
 		}
 	};
@@ -49,54 +59,52 @@ export class Signal {
 	 * @param {Value} value
 	 */
 	constructor(value) {
-		this.V = value;
+		this.#Value = value;
 	}
 	/**
-	 * @private
 	 * @type {Value}
 	 */
-	P = undefined;
+	#prev = undefined;
 	get prev() {
-		return this.P;
+		return this.#prev;
 	}
 	/**
-	 * @private
 	 * @type {Value}
 	 */
-	V;
+	#Value;
 	/**
 	 * @type {Value}
 	 */
 	get nonReactiveValue() {
-		return this.V;
+		return this.#Value;
 	}
 	/**
 	 * @type {Value}
 	 */
 	get value() {
-		if ($.R) {
-			$.A.add(this);
+		if ($.isRegistering) {
+			$.activeSignal.add(this);
 		}
-		return this.V;
+		return this.#Value;
 	}
 	/**
 	 * @type {Value}
 	 */
 	set value(newValue) {
-		if (this.V === newValue) {
+		if (this.#Value === newValue) {
 			return;
 		}
-		this.P = this.V;
-		this.V = newValue;
+		this.#prev = this.#Value;
+		this.#Value = newValue;
 		this.call$();
 	}
 	/**
 	 * @returns {void}
 	 */
 	call$ = () => {
-		if (!this.S) {
+		if (!this.subscribed) {
 			return;
 		}
-		this.S.forEach(($_) => $_.effect());
+		this.subscribed.forEach(($_) => $_.effect({ remove$: $_.remove$ }));
 	};
 }

package/src/function/NewQBlock.mjs

@@ -0,0 +1,39 @@
+// @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/src/function/{tryAsync.export.mjs → TryAsync.mjs}

@@ -10,7 +10,7 @@
  * @param {()=>Promise<ResultType>} asyncFunction_
  * @returns {Promise<[ResultType|undefined, Error|undefined]>}
  */
-export const tryAsync = async (asyncFunction_) => {
+export const TryAsync = async (asyncFunction_) => {
 	try {
 		const result = await asyncFunction_();
 		return [result, undefined];

package/src/function/{trySync.export.mjs → TrySync.mjs}

@@ -10,7 +10,7 @@
  * @param {()=>ResultType} function_
  * @returns {[ResultType|undefined, Error|undefined]}
  */
-export const trySync = (function_) => {
+export const TrySync = (function_) => {
 	try {
 		const result = function_();
 		return [result, undefined];

package/src/types/{anyButUndefined.type.mjs → AnyButUndefined.type.mjs}

@@ -1,5 +1,5 @@
 // @ts-check
 
 /**
- * @typedef {{}|null|number|string|boolean|symbol|bigint|function} anyButUndefined
+ * @typedef {{}|null|number|string|boolean|symbol|bigint|function} AnyButUndefined
  */

package/tsconfig.json

@@ -10,5 +10,5 @@
 		"esModuleInterop": true,
 		"skipLibCheck": true
 	},
-	"include": ["./index.mjs"]
+	"include": ["./index.mjs", "./src"]
 }

package/types/index.d.mts

@@ -1,12 +1,10 @@
 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 type anyButUndefined = {} | null | number | string | boolean | symbol | bigint | Function;
+export { NewQBlock } from "./src/function/NewQBlock.mjs";
+export { TryAsync } from "./src/function/TryAsync.mjs";
+export { TrySync } from "./src/function/TrySync.mjs";
+export type AnyButUndefined = {} | null | number | string | boolean | symbol | bigint | Function;

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

@@ -1,42 +1,55 @@
 /**
  * @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: Map<$, Set<import("../class/Signal.mjs").Signal<any>>>;
+    static effects: Map<$, Set<import("../class/Signal.mjs").Signal<any>>>;
     /**
-     * signalInstance
      * @type {Map<Signal, Set<$>>}
      */
-    static S: Map<import("../class/Signal.mjs").Signal<any>, Set<$>>;
+    static mappedSignals: Map<import("../class/Signal.mjs").Signal<any>, Set<$>>;
     /**
-     * activeSignalUponRegistering
      * @type {Set<Signal>}
      */
-    static A: Set<import("../class/Signal.mjs").Signal<any>>;
+    static activeSignal: Set<import("../class/Signal.mjs").Signal<any>>;
     /**
-     * isRegistering
      * @type {boolean}
      */
-    static R: boolean;
+    static isRegistering: boolean;
     /**
-     * @param {$["effect"]} effect
+     * @param {(arg:{remove$:$["remove$"]})=>void} effect
      */
-    constructor(effect: $["effect"]);
+    constructor(effect: (arg: {
+        remove$: $["remove$"];
+    }) => void);
     /**
      * @returns {void}
      */
     remove$: () => void;
     /**
-     * @type {()=>void}
+     * @type {(arg:{remove$:$["remove$"]})=>void};
      */
-    effect: () => void;
+    effect: (arg: {
+        remove$: $["remove$"];
+    }) => void;
 }

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

@@ -1,8 +1,19 @@
 /**
  * @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
@@ -10,8 +21,11 @@
  */
 export class Derived<V> extends Signal<V> {
     /**
-     * @param {()=>V} derivedFunction
+     * @param {(arg:{remove$:$["remove$"]})=>V} derivedFunction
      */
-    constructor(derivedFunction: () => V);
+    constructor(derivedFunction: (arg: {
+        remove$: $["remove$"];
+    }) => V);
 }
 import { Signal } from './Signal.mjs';
+import { $ } from './$.mjs';

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

@@ -0,0 +1,57 @@
+/**
+ * @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 "__#3@#queue": queueFIFODetails[];
+    /**
+     * @type {boolean}
+     */
+    static "__#3@#isRunning": boolean;
+    /**
+     * @param {queueFIFODetails} _queue
+     */
+    static "__#3@#push": (_queue: queueFIFODetails) => void;
+    static "__#3@#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)];

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

@@ -0,0 +1,48 @@
+/**
+ * @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: Map<any, [() => Promise<void>, number]>) => typeof PingUnique;
+    /**
+     * @type {Map<any, [()=>Promise<void>,number]>}
+     */
+    static "__#4@#queue": Map<any, [() => Promise<void>, number]>;
+    /**
+     * @type {boolean}
+     */
+    static "__#4@#isRunning": boolean;
+    /**
+     * @param {any} id
+     * @param {()=>Promise<void>} callback
+     * @param {number} debounceMS
+     */
+    static "__#4@#push": (id: any, callback: () => Promise<void>, debounceMS: number) => void;
+    static "__#4@#run": () => Promise<void>;
+    /**
+     * @param {any} id
+     * @param {()=>Promise<void>} callback
+     * @param {number} [debounceMS]
+     */
+    constructor(id: any, callback: () => Promise<void>, debounceMS?: number);
+}

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

@@ -23,16 +23,23 @@
  * - 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: Map<any, Promise<any>>) => typeof Q;
+    /**
+     * @typedef {import('../types/AnyButUndefined.type.mjs').AnyButUndefined} anyButUndefined
      */
     /**
-     * @private
      * @type {Promise<void>}
      */
-    private static f;
+    static "__#1@#fifo": Promise<void>;
     /**
      * 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
@@ -43,14 +50,14 @@ export class Q {
     /**
      * @type {Map<any, Promise<any>>}
      */
-    static u: Map<any, Promise<any>>;
+    static "__#1@#unique": Map<any, Promise<any>>;
     /**
      * 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: (id: import("../types/anyButUndefined.type.mjs").anyButUndefined) => Promise<{
+    static unique: (id: import("../types/AnyButUndefined.type.mjs").AnyButUndefined) => Promise<{
         resume: () => void;
     }>;
 }

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

@@ -1,8 +1,19 @@
 /**
  * @description
  * - 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
+ * 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);
+ * });
+ * signal.value = 1;
+ * ```
  */
 /**
  * @template Value
@@ -13,19 +24,13 @@ export class Signal<Value> {
      */
     constructor(value: Value);
     /**
-     * subscribed
      * @protected
      */
-    protected get S(): Set<$>;
+    protected get subscribed(): Set<$>;
     /**
      * destroy all props
      */
     unRef: () => void;
-    /**
-     * @private
-     * @type {Value}
-     */
-    private V;
     /**
      * remove all effects
      * @return {void}
@@ -37,11 +42,6 @@ export class Signal<Value> {
      * @return {void}
      */
     remove$: ($_: $) => void;
-    /**
-     * @private
-     * @type {Value}
-     */
-    private P;
     get prev(): Value;
     /**
      * @type {Value}
@@ -59,5 +59,6 @@ export class Signal<Value> {
      * @returns {void}
      */
     call$: () => void;
+    #private;
 }
 import { $ } from './$.mjs';

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

@@ -0,0 +1 @@
+export function NewQBlock(asyncCallaback: () => Promise<void>, objectReferenceID?: any): void;

package/types/src/function/{tryAsync.export.d.mts → TryAsync.d.mts}

@@ -1 +1 @@
-export function tryAsync<ResultType>(asyncFunction_: () => Promise<ResultType>): Promise<[ResultType | undefined, Error | undefined]>;
+export function TryAsync<ResultType>(asyncFunction_: () => Promise<ResultType>): Promise<[ResultType | undefined, Error | undefined]>;

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

@@ -0,0 +1 @@
+export function TrySync<ResultType>(function_: () => ResultType): [ResultType | undefined, Error | undefined];

package/types/src/types/AnyButUndefined.type.d.mts

@@ -0,0 +1 @@
+export type AnyButUndefined = {} | null | number | string | boolean | symbol | bigint | Function;

package/src/function/New$.mjs

@@ -1,28 +0,0 @@
-// @ts-check
-
-import { $ } from '../class/$.mjs';
-
-/**
- * @description
- *  - function to create `autosubscriber`;
- *  - syntatic sugar for [$](#$);
- * ```js
- * import { New$, NewDerived, NewSignal } from 'vivth';
- * const signal = NewSignal(0);
- * const derived = NewDerived(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;
- * ```
- */
-/**
- * @param {()=>void} effect subscriber
- * @returns {$} instance of `$`
- */
-export const New$ = (effect) => new $(effect);

package/src/function/NewDerived.mjs

@@ -1,28 +0,0 @@
-// @ts-check
-
-import { Derived } from '../class/Derived.mjs';
-
-/**
- * @description
- *  - function to create `signal` that its value are derived from another `signal`;
- *  - syntatic sugar for [Derived](#derived);
- * ```js
- * import { New$, NewDerived, NewSignal } from 'vivth';
- * const signal = NewSignal(0);
- * const derived = NewDerived(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
- * @param {()=>(V)} derivedFunction
- * @returns {Derived<V>}
- */
-export const NewDerived = (derivedFunction) => new Derived(derivedFunction);