vivth 1.1.2 → 1.2.1

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

@@ -1,40 +1,71 @@
 /**
  * @description
- * - class with static methods to print to standard console with added style;
+ * - class with static methods to print to standard console with bare minimum ANSI styles;
  */
 export class Console {
+    static #ansi: {
+        reset: string;
+        bold: string;
+        colors: {
+            log: string;
+            info: string;
+            warn: string;
+            error: string;
+        };
+    };
     /**
      * @param {string} prefix
      * @param {'log'|'info'|'error'|'warn'} mode
-     * - Console method to use
      * @param {any} data
-     * @param {string} color
-     * @param {string} bgcolor
      * @returns {void}
      */
-    static #call: (prefix: string, mode: "log" | "info" | "error" | "warn", data: any, color: string, bgcolor: string) => void;
+    static #call: (prefix: string, mode: "log" | "info" | "error" | "warn", data: any) => void;
     /**
      * @description
      * @param {any} data
      * @returns {void}
+     * @example
+     * import { Console } from 'vivth';
+     *
+     * Console.log({
+     * 	hello: 'world!!',
+     * });
      */
     static log: (data: any) => void;
     /**
      * @description
      * @param {any} data
      * @returns {void}
+     * @example
+     * import { Console } from 'vivth';
+     *
+     * Console.info({
+     * 	hello: 'world!!',
+     * });
      */
     static info: (data: any) => void;
     /**
      * @description
      * @param {any} data
      * @returns {void}
+     * @example
+     * import { Console } from 'vivth';
+     *
+     * Console.warn({
+     * 	hello: 'world!!',
+     * });
      */
     static warn: (data: any) => void;
     /**
      * @description
      * @param {any} data
      * @returns {void}
+     * @example
+     * import { Console } from 'vivth';
+     *
+     * Console.error({
+     * 	hello: 'world!!',
+     * });
      */
     static error: (data: any) => void;
 }

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

@@ -1,14 +1,16 @@
 /**
  * @description
  * - a class for creating derived version of [Signal](#signal);
- * @template V
- * @extends Signal<V>
+ * @template VALUE
+ * @extends Signal<VALUE>
  */
-export class Derived<V> extends Signal<V> {
+export class Derived<VALUE> extends Signal<VALUE> {
     /**
      * @description
      * - Derived used [Signal](#signal) and [Effect](#effect) under the hood;
-     * @param {(effectInstanceOptions:Effect["options"])=>Promise<V>} derivedFunction
+     * @param {(effectInstanceOptions:Omit<Effect["options"] &
+     * Derived["options"], unwrapLazy>) =>
+     * Promise<VALUE>} derivedFunction
      * @example
      * import { Signal, Derived } from  'vivth';
      *
@@ -25,7 +27,132 @@ export class Derived<V> extends Signal<V> {
      *
      * count.value++;
      */
-    constructor(derivedFunction: (effectInstanceOptions: Effect["options"]) => Promise<V>);
+    constructor(derivedFunction: (effectInstanceOptions: Omit<Effect["options"] & ({
+        /**
+         * @instance options
+         * @description
+         * - return this value tandem with `isLastCalled`, to not to update the value of this instance, even when returning early;
+         * @type {Object}
+         * @example
+         * import { Signal, Derived } from  'vivth';
+         *
+         * const count = new Signal(0);
+         * const double = new Derived(async({
+         * 		subscribe,
+         * 		dontUpdate,
+         * 		isLastCalled,
+         * 	}) => {
+         * 		const currentValue = subscribe(count).value;
+         * 		if (!(await isLastCalled(10))) {
+         *			return dontUpdate;
+         * 		}
+         * 		const res = await fetch(`some/path/${curentValue.toString()}`);
+         * 		if (!(await isLastCalled())) {
+         *			return dontUpdate; // this will prevent race condition, even if the earlier fetch return late;
+         * 		}
+         * 		return res;
+         * });
+         *
+         * count.value++;
+         */
+        dontUpdate: any;
+    } & {
+        "vivth:unwrapLazy;": () => {
+            /**
+             * @instance options
+             * @description
+             * - return this value tandem with `isLastCalled`, to not to update the value of this instance, even when returning early;
+             * @type {Object}
+             * @example
+             * import { Signal, Derived } from  'vivth';
+             *
+             * const count = new Signal(0);
+             * const double = new Derived(async({
+             * 		subscribe,
+             * 		dontUpdate,
+             * 		isLastCalled,
+             * 	}) => {
+             * 		const currentValue = subscribe(count).value;
+             * 		if (!(await isLastCalled(10))) {
+             *			return dontUpdate;
+             * 		}
+             * 		const res = await fetch(`some/path/${curentValue.toString()}`);
+             * 		if (!(await isLastCalled())) {
+             *			return dontUpdate; // this will prevent race condition, even if the earlier fetch return late;
+             * 		}
+             * 		return res;
+             * });
+             *
+             * count.value++;
+             */
+            dontUpdate: any;
+        };
+    }), "vivth:unwrapLazy;">) => Promise<VALUE>);
+    /**
+     * @description
+     * - additional helper to be accessed on effect;
+     */
+    options: {
+        /**
+         * @instance options
+         * @description
+         * - return this value tandem with `isLastCalled`, to not to update the value of this instance, even when returning early;
+         * @type {Object}
+         * @example
+         * import { Signal, Derived } from  'vivth';
+         *
+         * const count = new Signal(0);
+         * const double = new Derived(async({
+         * 		subscribe,
+         * 		dontUpdate,
+         * 		isLastCalled,
+         * 	}) => {
+         * 		const currentValue = subscribe(count).value;
+         * 		if (!(await isLastCalled(10))) {
+         *			return dontUpdate;
+         * 		}
+         * 		const res = await fetch(`some/path/${curentValue.toString()}`);
+         * 		if (!(await isLastCalled())) {
+         *			return dontUpdate; // this will prevent race condition, even if the earlier fetch return late;
+         * 		}
+         * 		return res;
+         * });
+         *
+         * count.value++;
+         */
+        dontUpdate: any;
+    } & {
+        "vivth:unwrapLazy;": () => {
+            /**
+             * @instance options
+             * @description
+             * - return this value tandem with `isLastCalled`, to not to update the value of this instance, even when returning early;
+             * @type {Object}
+             * @example
+             * import { Signal, Derived } from  'vivth';
+             *
+             * const count = new Signal(0);
+             * const double = new Derived(async({
+             * 		subscribe,
+             * 		dontUpdate,
+             * 		isLastCalled,
+             * 	}) => {
+             * 		const currentValue = subscribe(count).value;
+             * 		if (!(await isLastCalled(10))) {
+             *			return dontUpdate;
+             * 		}
+             * 		const res = await fetch(`some/path/${curentValue.toString()}`);
+             * 		if (!(await isLastCalled())) {
+             *			return dontUpdate; // this will prevent race condition, even if the earlier fetch return late;
+             * 		}
+             * 		return res;
+             * });
+             *
+             * count.value++;
+             */
+            dontUpdate: any;
+        };
+    };
 }
 import { Signal } from './Signal.mjs';
 import { Effect } from './Effect.mjs';

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

@@ -14,7 +14,10 @@ export const setOfEffects: Set<Effect>;
 export class Effect {
     /**
      * @description
-     * @param {(arg0:Effect["options"])=>Promise<void>} effect
+     * @param {( arg0:
+     * Omit<Effect["options"], typeof unwrapLazy>
+     * ) =>
+     * Promise<void>} effect
      * @example
      * import { Signal, Derived, Effect, Console } from  'vivth';
      *
@@ -23,6 +26,7 @@ export class Effect {
      * new Effect(async ({
      * 			subscribe, // : registrar callback for this effect instance, immediately return the signal instance
      * 			removeEffect, // : disable this effect instance from reacting to dependency changes;
+     * 			isLastCalled, // : check whether this callback run is this instant last called effect;
      * 		}) => {
      * 			Console.log(subscribe(double).value); // effect listen to double changes
      * 			const a = double.value; //  no need to wrap double twice with $
@@ -30,28 +34,63 @@ export class Effect {
      *
      * count.value++;
      */
-    constructor(effect: (arg0: Effect["options"]) => Promise<void>);
+    constructor(effect: (arg0: Omit<Effect["options"], typeof unwrapLazy>) => Promise<void>);
+    /**
+     * @typedef {import('../common/lazie.mjs').unwrapLazy} unwrapLazy
+     */
+    /**
+     * @description
+     * - collections of lazy methods to handle effect calls of this instance;
+     */
     options: {
+        /**
+         * @instance options
+         * @description
+         * @returns {(timeoutMS?:number)=>Promise<boolean>}
+         * - timeoutMS only necessary if the operation doesn't naturally await;
+         * - if it's operation such as `fetch`, you can just leave it blank;
+         * @example
+         *
+         * import { Effect } from 'vivth';
+         *
+         * const effect = new Effect(async ({ isLastCalled }) => {
+         * 	if (!(await isLastCalled(100))) {
+         * 		return;
+         * 	}
+         * 	// OR
+         * 	const res = await fetch('some/path');
+         * 	if (!(await isLastCalled(
+         * 		// no need to add timeoutMS argument, as fetch are naturally add delay;
+         * 	))) {
+         * 		return;
+         * 	}
+         * })
+         */
+        readonly isLastCalled: (timeoutMS?: number) => Promise<boolean>;
         /**
          * @instance options
          * @description
          * - normally it's passed as argument to constructor, however it is also accessible from `options` property;
-         * @template {Signal} S
-         * @param {S} signal
-         * @returns {S}
+         * @template {Signal} SIGNAL
+         * @param {SIGNAL} signal
+         * @returns {SIGNAL}
          * @example
+         * import { Effect } from 'vivth';
+         *
          * const effect = new Effect(async () => {
          * 	// code
          * })
          * effect.options.subscribe(signalInstance);
          */
-        subscribe: <S extends Signal<any>>(signal: S) => S;
+        subscribe: <SIGNAL extends Signal<any>>(signal: SIGNAL) => SIGNAL;
         /**
          * @instance options
          * @description
          * - normally it's passed as argument to constructor, however it is also accessible from `options` property;
          * @type {()=>void}
          * @example
+         * import { Effect } from 'vivth';
+         *
          * const effect = new Effect(async () => {
          * 	// code
          * })
@@ -59,13 +98,70 @@ export class Effect {
          */
         removeEffect: () => void;
     } & {
-        "vivth:unwrapLazy;": string;
+        "vivth:unwrapLazy;": () => {
+            /**
+             * @instance options
+             * @description
+             * @returns {(timeoutMS?:number)=>Promise<boolean>}
+             * - timeoutMS only necessary if the operation doesn't naturally await;
+             * - if it's operation such as `fetch`, you can just leave it blank;
+             * @example
+             *
+             * import { Effect } from 'vivth';
+             *
+             * const effect = new Effect(async ({ isLastCalled }) => {
+             * 	if (!(await isLastCalled(100))) {
+             * 		return;
+             * 	}
+             * 	// OR
+             * 	const res = await fetch('some/path');
+             * 	if (!(await isLastCalled(
+             * 		// no need to add timeoutMS argument, as fetch are naturally add delay;
+             * 	))) {
+             * 		return;
+             * 	}
+             * })
+             */
+            readonly isLastCalled: (timeoutMS?: number) => Promise<boolean>;
+            /**
+             * @instance options
+             * @description
+             * - normally it's passed as argument to constructor, however it is also accessible from `options` property;
+             * @template {Signal} SIGNAL
+             * @param {SIGNAL} signal
+             * @returns {SIGNAL}
+             * @example
+             * import { Effect } from 'vivth';
+             *
+             * const effect = new Effect(async () => {
+             * 	// code
+             * })
+             * effect.options.subscribe(signalInstance);
+             */
+            subscribe: <SIGNAL extends Signal<any>>(signal: SIGNAL) => SIGNAL;
+            /**
+             * @instance options
+             * @description
+             * - normally it's passed as argument to constructor, however it is also accessible from `options` property;
+             * @type {()=>void}
+             * @example
+             * import { Effect } from 'vivth';
+             *
+             * const effect = new Effect(async () => {
+             * 	// code
+             * })
+             * effect.options.removeEffect();
+             */
+            removeEffect: () => void;
+        };
     };
     /**
      * @description
      * - normally is to let to be automatically run when dependency signals changes, however it's also accessible as instance method;
      * @returns {void}
      * @example
+     * import { Effect } from 'vivth';
+     *
      * const effect = new Effect(async ()=>{
      * 	// code
      * })
@@ -75,3 +171,6 @@ export class Effect {
     #private;
 }
 import { Signal } from './Signal.mjs';
+type unwrapLazy = "vivth:unwrapLazy;";
+import { unwrapLazy } from '../common/lazie.mjs';
+export {};

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

@@ -2,19 +2,19 @@
  * @description
  * - non browser API;
  * - uses [Signal](#signal) and [Derived](#derived) under the hood;
- * @template V
+ * @template VALUE
  */
-export class EnvSignal<V> {
+export class EnvSignal<VALUE> {
     /**
      * @description
      * - create `EnvSignal` instance;
-     * @param {V} initialValue
+     * @param {VALUE} initialValue
      */
-    constructor(initialValue: V);
+    constructor(initialValue: VALUE);
     /**
      * @description
      * - exposed property to listen to;
-     * @type {Derived<V>}
+     * @type {Derived<VALUE>}
      * @example
      * import { EnvSignal, Effect } from 'vivth';
      *
@@ -24,12 +24,12 @@ export class EnvSignal<V> {
      * 	// code
      * })
      */
-    env: Derived<V>;
+    env: Derived<VALUE>;
     /**
      * @description
      * - call to correct the value of previously declared value;
      * - can only be called once;
-     * @param {V} correctedValue
+     * @param {VALUE} correctedValue
      * @returns {void}
      * @example
      * import { EnvSignal } from 'vivth';
@@ -41,7 +41,7 @@ export class EnvSignal<V> {
      *
      * myEnv.correction(false); // this will notify all subscribers;
      */
-    correction: (correctedValue: V) => void;
+    correction: (correctedValue: VALUE) => void;
     #private;
 }
 import { Derived } from './Derived.mjs';

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

@@ -1,10 +1,11 @@
 /**
  * @description
  * - Signal implementation for `CustomEvent`, to dispatch and listen;
- * @template {IsListSignal} isList
+ * - it's based on string as key, so it can be listened/dispatched even without direct instance reference;
+ * @template {IsListSignal} ISLIST
  * - boolean;
  */
-export class EventSignal<isList extends boolean> {
+export class EventSignal<ISLIST extends boolean> {
     /**
      * @typedef {import('../types/IsListSignal.mjs').IsListSignal} IsListSignal
      */
@@ -48,7 +49,7 @@ export class EventSignal<isList extends boolean> {
          * @example
          * import { EventSignal } from 'vivth';
          *
-         * EventSignal.remove.subscriber('yourEventSignalName', yourEffectInstance);
+         * EventSignal.remove.subscriber('yourEventSignalName', myEffectInstance);
          */
         subscriber: (name: string, effect: import("./Effect.mjs").Effect) => void;
         /**
@@ -76,12 +77,50 @@ export class EventSignal<isList extends boolean> {
          */
         refs: (name: string) => void;
     } & {
-        "vivth:unwrapLazy;": string;
+        "vivth:unwrapLazy;": () => {
+            /**
+             * @static remove
+             * @description
+             * - remove subscriber from the named `EventSignal_instance`;
+             * @param {string} name
+             * @param {import('./Effect.mjs').Effect} effect
+             * @returns {void}
+             * @example
+             * import { EventSignal } from 'vivth';
+             *
+             * EventSignal.remove.subscriber('yourEventSignalName', myEffectInstance);
+             */
+            subscriber: (name: string, effect: import("./Effect.mjs").Effect) => void;
+            /**
+             * @static remove
+             * @description
+             * - remove all subscribers from the named `EventSignal_instance`;
+             * @param {string} name
+             * @returns {void}
+             * @example
+             * import { EventSignal } from 'vivth';
+             *
+             * EventSignal.remove.allSubscribers('yourEventSignalName');
+             */
+            allSubscribers: (name: string) => void;
+            /**
+             * @static remove
+             * @description
+             * - remove reference of the `proxySignals` of the named `EventSignal_instance`;
+             * @param {string} name
+             * @returns {void}
+             * @example
+             * import { EventSignal } from 'vivth';
+             *
+             * EventSignal.remove.refs('yourEventSignalName');
+             */
+            refs: (name: string) => void;
+        };
     };
     /**
      * @private
      * @param {string} name
-     * @param {isList} [isList]
+     * @param {ISLIST} [isList]
      */
     private constructor();
     /**
@@ -94,6 +133,17 @@ export class EventSignal<isList extends boolean> {
      * - if needed to pass along the messages, it can be used as `dispatcher` and `listener` at the same time;
      * - is `lazily` created;
      * @type {Signal|ListSignal}
+     * @example
+     * import { EventSignal, Effect, Console } from 'vivth';
+     *
+     * const myEventSignal = await EventSignal.get('dataEvent', false);
+     *
+     * new Effect(({ subscribe })=>{
+     * 	const listenValue = subscribe(myEventSignal.dispatch).value;
+     * 	// dispatch can be used as two way communication;
+     * 	Console.log({ listenValue });
+     * })
+     * myEventSignal.dispatch.value = 'hey';
      */
     dispatch: Signal<any> | ListSignal<any>;
     /**
@@ -102,6 +152,17 @@ export class EventSignal<isList extends boolean> {
      * - can be used as listener when passed down value shouldn't be modified manually;
      * - is `lazily` created along with `dispatch`, if `listen` is accessed first, then `dispatch` will also be created automatically;
      * @type {Derived|ListDerived}
+     * @example
+     * import { EventSignal, Effect, Console } from 'vivth';
+     *
+     * const myEventSignal = await EventSignal.get('dataEvent', false);
+     *
+     * new Effect(({ subscribe })=>{
+     * 	const listenValue = subscribe(myEventSignal.listen).value;
+     * 	// listen can be used only as listener for one way communication;
+     * 	Console.log({ listenValue });
+     * })
+     * myEventSignal.dispatch.value = 'hey';
      */
     listen: Derived<any> | ListDerived<any>;
     remove: {
@@ -112,7 +173,16 @@ export class EventSignal<isList extends boolean> {
          * @param {import('./Effect.mjs').Effect} effect
          * @returns {void}
          * @example
-         * eventSignal_instance.remove.subscriber(yourEffectInstance);
+         * import { EventSignal, Effect, Console } from 'vivth';
+         *
+         * const myEventSignal = await EventSignal.get('dataEvent', false);
+         *
+         * const myEffectInstance = new Effect(({ subscribe })=>{
+         * 	const listenValue = subscribe(myEventSignal.dispatch).value;
+         * 	Console.log({ listenValue });
+         * })
+         * myEventSignal.dispatch.value = 'hey';
+         * eventSignal_instance.remove.subscriber(myEffectInstance);
          */
         subscriber: (effect: import("./Effect.mjs").Effect) => void;
         /**
@@ -121,6 +191,15 @@ export class EventSignal<isList extends boolean> {
          * - remove allSubscribers from the `EventSignal_instance`;
          * @type  {()=>void}
          * @example
+         * import { EventSignal, Effect, Console } from 'vivth';
+         *
+         * const myEventSignal = await EventSignal.get('dataEvent', false);
+         *
+         * const myEffectInstance = new Effect(({ subscribe })=>{
+         * 	const listenValue = subscribe(myEventSignal.dispatch).value;
+         * 	Console.log({ listenValue });
+         * })
+         * myEventSignal.dispatch.value = 'hey';
          * eventSignal_instance.remove.allSubscribers();
          */
         allSubscribers: () => void;
@@ -130,11 +209,76 @@ export class EventSignal<isList extends boolean> {
          * - remove reference of the `proxySignals` of the `EventSignal_instance`;
          * @type {()=>void}
          * @example
+         * import { EventSignal, Effect, Console } from 'vivth';
+         *
+         * const myEventSignal = await EventSignal.get('dataEvent', false);
+         *
+         * const myEffectInstance = new Effect(({ subscribe })=>{
+         * 	const listenValue = subscribe(myEventSignal.dispatch).value;
+         * 	Console.log({ listenValue });
+         * });
+         *
          * eventSignal_instance.remove.ref();
          */
         ref: () => void;
     } & {
-        "vivth:unwrapLazy;": string;
+        "vivth:unwrapLazy;": () => {
+            /**
+             * @instance remove
+             * @description
+             * - remove subscriber from the `EventSignal_instance`;
+             * @param {import('./Effect.mjs').Effect} effect
+             * @returns {void}
+             * @example
+             * import { EventSignal, Effect, Console } from 'vivth';
+             *
+             * const myEventSignal = await EventSignal.get('dataEvent', false);
+             *
+             * const myEffectInstance = new Effect(({ subscribe })=>{
+             * 	const listenValue = subscribe(myEventSignal.dispatch).value;
+             * 	Console.log({ listenValue });
+             * })
+             * myEventSignal.dispatch.value = 'hey';
+             * eventSignal_instance.remove.subscriber(myEffectInstance);
+             */
+            subscriber: (effect: import("./Effect.mjs").Effect) => void;
+            /**
+             * @instance remove
+             * @description
+             * - remove allSubscribers from the `EventSignal_instance`;
+             * @type  {()=>void}
+             * @example
+             * import { EventSignal, Effect, Console } from 'vivth';
+             *
+             * const myEventSignal = await EventSignal.get('dataEvent', false);
+             *
+             * const myEffectInstance = new Effect(({ subscribe })=>{
+             * 	const listenValue = subscribe(myEventSignal.dispatch).value;
+             * 	Console.log({ listenValue });
+             * })
+             * myEventSignal.dispatch.value = 'hey';
+             * eventSignal_instance.remove.allSubscribers();
+             */
+            allSubscribers: () => void;
+            /**
+             * @instance remove
+             * @description
+             * - remove reference of the `proxySignals` of the `EventSignal_instance`;
+             * @type {()=>void}
+             * @example
+             * import { EventSignal, Effect, Console } from 'vivth';
+             *
+             * const myEventSignal = await EventSignal.get('dataEvent', false);
+             *
+             * const myEffectInstance = new Effect(({ subscribe })=>{
+             * 	const listenValue = subscribe(myEventSignal.dispatch).value;
+             * 	Console.log({ listenValue });
+             * });
+             *
+             * eventSignal_instance.remove.ref();
+             */
+            ref: () => void;
+        };
     };
     #private;
 }