vivth 1.1.2 → 1.2.0

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

@@ -5,22 +5,23 @@ export const setOFSignals: Set<Signal<any>>;
 /**
  * @description
  * - a class for creating effect to signals;
- * @template Value
+ * @template VALUE
  */
-export class Signal<Value> {
+export class Signal<VALUE> {
     /**
      * @param {Set<Effect>} setOfSubscribers
      */
     static #notify: (setOfSubscribers: Set<Effect>) => void;
     /**
      * @description
-     * @param {Value} value
+     * - create a `Signal`;
+     * @param {VALUE} value
      * @example
      * import { Signal, Effect } from  'vivth';
      *
      * const count = new Signal(0);
      */
-    constructor(value: Value);
+    constructor(value: VALUE);
     /**
      * @description
      * - subsrcibers reference of this instance;
@@ -37,17 +38,17 @@ export class Signal<Value> {
          * @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';
@@ -55,10 +56,42 @@ export class Signal<Value> {
          * });
          */
         notify: (callback?: (options: {
-            signalInstance: Signal<Value>;
+            signalInstance: Signal<VALUE>;
         }) => Promise<void>) => void;
     } & {
-        "vivth:unwrapLazy;": string;
+        "vivth:unwrapLazy;": () => {
+            /**
+             * @instance subscribers
+             * @description
+             * - subscribedEffects
+             * @type {Set<Effect>}
+             */
+            setOf: Set<Effect>;
+            /**
+             * @instance subscribers
+             * @description
+             * - manually notify on non primitive value or value that have depths;
+             * @param {(options:{signalInstance:Signal<VALUE>})=>Promise<void>} [callback]
+             * @returns {void}
+             * @example
+             * 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';
+             * 	signalInstance.value['d'] = 'testd';
+             * });
+             */
+            notify: (callback?: (options: {
+                signalInstance: Signal<VALUE>;
+            }) => Promise<void>) => void;
+        };
     };
     /**
      * @description
@@ -88,18 +121,41 @@ export class Signal<Value> {
          */
         ref: () => void;
     } & {
-        "vivth:unwrapLazy;": string;
+        "vivth:unwrapLazy;": () => {
+            /**
+             * @instance remove
+             * @description
+             * - remove effect subscriber to react from this instance value changes;
+             * @param {Effect} effectInstance
+             * @returns {void}
+             */
+            subscriber: (effectInstance: Effect) => void;
+            /**
+             * @instance remove
+             * @description
+             * - remove all effect subscribers to react from this instance value changes;
+             * @type {()=>void}
+             */
+            allSubscribers: () => void;
+            /**
+             * @instance remove
+             * @description
+             * - remove this instance from `vivth` reactivity engine, and nullify it's own value;
+             * @type {()=>void}
+             */
+            ref: () => void;
+        };
     };
     /**
      * @description
      * - value before change;
-     * @type {Value}
+     * @returns {VALUE}
      */
-    get prev(): Value;
+    get prev(): VALUE;
     /**
      * @description
      * - assign new value then automatically notify all subscribers;
-     * @type {Value}
+     * @type {VALUE}
      * @example
      * import { Signal } from  'vivth';
      *
@@ -108,11 +164,11 @@ export class Signal<Value> {
      * // OR
      * count.value = 9;
      */
-    set value(newValue: Value);
+    set value(newValue: VALUE);
     /**
      * @description
      * - value after change;
-     * @type {Value}
+     * @returns {VALUE}
      * @example
      * import { Signal, Effect, Derived } from  'vivth';
      *
@@ -122,11 +178,11 @@ export class Signal<Value> {
      * 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
      * })
      */
-    get value(): Value;
+    get value(): VALUE;
     #private;
 }
 import { Effect } from './Effect.mjs';

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

@@ -1,16 +1,21 @@
 /**
- * @template A
- * @typedef {import('./WorkerResult.mjs').WorkerResult<A>} WorkerResult
+ * @template POST
+ * @typedef {import('./WorkerResult.mjs').WorkerResult<POST>} WorkerResult
  */
 /**
  * @typedef {import('./WorkerThread.mjs').WorkerThread} WorkerThread
+ * @typedef {import('../common/lazie.mjs').unwrapLazy} unwrapLazy
  */
 /**
  * @description
  * - class helper to create `Worker` instance;
+ * - before any `Worker` functionaily to be used, you need to setup it with `WorkerThread.setup` and `WorkerMainThread.setup` before runing anytyhing;
  * @template {WorkerThread} WT
  */
 export class WorkerMainThread<WT extends WorkerThread> {
+    /**
+     * @type {boolean}
+     */
     static #isRegistered: boolean;
     /**
      * @description
@@ -19,13 +24,14 @@ export class WorkerMainThread<WT extends WorkerThread> {
      * @param {typeof WorkerMainThread["workerClass"]} param0.workerClass
      * - example:
      * ```js
-     * async () => await (import('worker_threads')).Worker
+     * import { Worker } from 'node:worker_threads';
      * ```
      * @param {typeof WorkerMainThread["pathValidator"]} param0.pathValidator
      * - example:
      * ```js
      * async (workerPath, root, base) => {
-     * 	const res = await fetch(`${root}/${base}/${workerPath}`);
+     *  const truePathCheck = `${root}/${base}/${workerPath}`;
+     * 	const res = await fetch(truePathCheck);
      * 	// might also check wheter it need base or not
      * 	return await res.ok;
      * }
@@ -34,10 +40,11 @@ export class WorkerMainThread<WT extends WorkerThread> {
      * - additonal realtivePath from rootPath;
      * - default: '';
      * @example
+     * import { Worker } from 'node:worker_threads';
      * import { WorkerMainThread } from 'vivth';
      *
      * WorkerMainThread.setup({
-     * 	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}`);
@@ -55,9 +62,9 @@ export class WorkerMainThread<WT extends WorkerThread> {
      * @description
      * - reference for `Worker` class;
      * - edit via `setup`;
-     * @type {()=>Promise<typeof Worker|typeof import('worker_threads').Worker>}
+     * @type {typeof Worker|typeof import('worker_threads').Worker}
      */
-    static workerClass: () => Promise<typeof Worker | typeof import("worker_threads").Worker>;
+    static workerClass: typeof Worker | typeof import("worker_threads").Worker;
     /**
      * @description
      * - reference for worker file `basePath`;
@@ -79,44 +86,38 @@ export class WorkerMainThread<WT extends WorkerThread> {
     static #options: import("worker_threads").WorkerOptions & {
         type?: "module";
     };
+    /**
+     * @template {WorkerThread} WT
+     * @description
+     * - create Worker_instance;
+     * @param {string} handler
+     * @param {Omit<WorkerOptions|import('worker_threads').WorkerOptions, 'eval'|'type'>} [options]
+     * @returns {WorkerMainThread<WT>}
+     * @example
+     * import { WorkerMainThread } from 'vivth';
+     *
+     * export const myDoubleWorker = WorkerMainThread.newVivthWorker('./doubleWorkerThread.mjs');
+     */
+    static newVivthWorker: (handler: string, options?: Omit<WorkerOptions | import("worker_threads").WorkerOptions, "eval" | "type">) => WorkerMainThread<WT_1>;
     /**
      * @param {string} handler
      * @param { WorkerOptions
      * | import('worker_threads').WorkerOptions} options
      * @param {WorkerMainThread} worker
      * @param {(any:any)=>void} listener
-     * @param {boolean} isInline
      * @returns {Promise<void>}
      */
-    static #workerFilehandler: (handler: string, options: WorkerOptions | import("worker_threads").WorkerOptions, worker: WorkerMainThread<any>, listener: (any: any) => void, isInline: boolean) => Promise<void>;
+    static #workerFilehandler: (handler: string, options: WorkerOptions | import("worker_threads").WorkerOptions, worker: WorkerMainThread<any>, listener: (any: any) => void) => Promise<void>;
     /**
-     * @type {boolean}
-     */
-    static #isBrowser: boolean;
-    /**
-     * @description
-     * - check whether js run in browser
-     * @type {boolean}
-     */
-    static get isBrowser(): boolean;
-    /**
-     * @description
-     * - create Worker_instance;
-     * @param {string} handler
-     * - if `isInline` === `false`, `handler` should be:
-     * >- pointing to worker thread file; WHICH
-     * >- the path must be relative to `projectRoot`;
-     * - if `isInline` === `true`, `handler` should be
-     * >- string literal of prebundled worker thread script; OR
-     * >- manually made string literal of worker thread script;
-     * @param {Omit<WorkerOptions|import('worker_threads').WorkerOptions, 'eval'|'type'>} [options]
-     * @param {boolean} [isInline]
+     * @private
+     * @param {Parameters<typeof WorkerMainThread<WT>["newVivthWorker"]>[0]} handler
+     * @param {Parameters<typeof WorkerMainThread<WT>["newVivthWorker"]>[1]} [options]
      * @example
      * import { WorkerMainThread } from 'vivth';
      *
-     * export const myDoubleWorker = new WorkerMainThread('./doubleWorkerThread.mjs');
+     * export const myDoubleWorker = WorkerMainThread.newVivthWorker('./doubleWorkerThread.mjs');
      */
-    constructor(handler: string, options?: Omit<WorkerOptions | import("worker_threads").WorkerOptions, "eval" | "type">, isInline?: boolean);
+    private constructor();
     /**
      * @description
      * - terminate all signals that are used on this instance;
@@ -126,7 +127,7 @@ export class WorkerMainThread<WT extends WorkerThread> {
     /**
      * @description
      * - result signal of the processed message;
-     * @type {Derived<WorkerResult<WT["Post"]>>}
+     * @type {Derived<WorkerResult<WT["POST"]>>}
      * @example
      * import { Effect } from 'vivth';
      * import { myDoubleWorker } from './myDoubleWorker.mjs';
@@ -137,19 +138,20 @@ export class WorkerMainThread<WT extends WorkerThread> {
      * 	// code
      * })
      */
-    receiverSignal: Derived<WorkerResult<WT["Post"]>>;
+    receiverSignal: Derived<WorkerResult<WT["POST"]>>;
     /**
      * @description
      * - callback to send message to the worker thread;
-     * @type {(event: WT["Receive"])=>void}
+     * @type {(event: WT["RECEIVE"])=>void}
      * @example
      * import { myDoubleWorker } from './myDoubleWorker.mjs';
      *
      * myDoubleWorker.postMessage(90);
      */
-    postMessage: (event: WT["Receive"]) => void;
+    postMessage: (event: WT["RECEIVE"]) => void;
     #private;
 }
-export type WorkerResult<A> = import("./WorkerResult.mjs").WorkerResult<A>;
+export type WorkerResult<POST> = import("./WorkerResult.mjs").WorkerResult<POST>;
 export type WorkerThread = import("./WorkerThread.mjs").WorkerThread<any, any>;
+export type unwrapLazy = "vivth:unwrapLazy;";
 import { Derived } from './Derived.mjs';

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

@@ -0,0 +1,85 @@
+/**
+ * @template POST
+ * @typedef {import('./WorkerResult.mjs').WorkerResult<POST>} WorkerResult
+ */
+/**
+ * @typedef {import('./WorkerThread.mjs').WorkerThread} WorkerThread
+ * @typedef {import('../common/lazie.mjs').unwrapLazy} unwrapLazy
+ */
+/**
+ * @template {WorkerThread} WT
+ */
+export class WorkerMainThread<WT extends WorkerThread> {
+    /**
+     * @type {boolean}
+     */
+    static #isRegistered: boolean;
+    /**
+     * @param {Object} param0
+     * @param {typeof WorkerMainThread["workerClass"]} param0.workerClass
+     * @param {typeof WorkerMainThread["pathValidator"]} param0.pathValidator
+     * @param {typeof WorkerMainThread["basePath"]} [param0.basePath]
+     */
+    static setup: ({ workerClass, pathValidator, basePath }: {
+        workerClass: (typeof WorkerMainThread)["workerClass"];
+        pathValidator: (typeof WorkerMainThread)["pathValidator"];
+        basePath?: (typeof WorkerMainThread)["basePath"];
+    }) => void;
+    /**
+     * @type {typeof Worker|typeof import('worker_threads').Worker}
+     */
+    static workerClass: typeof Worker | typeof import("worker_threads").Worker;
+    /**
+     * @type {string}
+     */
+    static basePath: string;
+    /**
+     * @type {(paths:{worker: string, root:string, base: string})=>Promise<string>}
+     */
+    static pathValidator: (paths: {
+        worker: string;
+        root: string;
+        base: string;
+    }) => Promise<string>;
+    static #options: import("worker_threads").WorkerOptions & {
+        type?: "module";
+    };
+    /**
+     * @template {WorkerThread} WT
+     * @param {string} handler
+     * @param {Omit<WorkerOptions|import('worker_threads').WorkerOptions, 'eval'|'type'>} [options]
+     * @returns {WorkerMainThread<WT>}
+     */
+    static newVivthWorker: (handler: string, options?: Omit<WorkerOptions | import("worker_threads").WorkerOptions, "eval" | "type">) => WorkerMainThread<WT_1>;
+    /**
+     * @param {string} handler
+     * @param { WorkerOptions
+     * | import('worker_threads').WorkerOptions} options
+     * @param {WorkerMainThread} worker
+     * @param {(any:any)=>void} listener
+     * @returns {Promise<void>}
+     */
+    static #workerFilehandler: (handler: string, options: WorkerOptions | import("worker_threads").WorkerOptions, worker: WorkerMainThread<any>, listener: (any: any) => void) => Promise<void>;
+    /**
+     * @param {Parameters<typeof WorkerMainThread<WT>["newVivthWorker"]>[0]} handler
+     * @param {Parameters<typeof WorkerMainThread<WT>["newVivthWorker"]>[1]} [options]
+     */
+    constructor(handler: Parameters<(typeof WorkerMainThread<WT>)["newVivthWorker"]>[0], options?: Parameters<(typeof WorkerMainThread<WT>)["newVivthWorker"]>[1]);
+    /**
+     * @type {()=>void}
+     */
+    terminate: () => void;
+    /**
+     * @type {Derived<WorkerResult<WT["POST"]>>}
+     */
+    receiverSignal: Derived<WorkerResult<WT["POST"]>>;
+    /**
+     * @type {(event: WT["RECEIVE"])=>void}
+     */
+    postMessage: (event: WT["RECEIVE"]) => void;
+    #private;
+}
+export type WorkerResult<POST> = import("./WorkerResult.mjs").WorkerResult<POST>;
+export type WorkerThread = import("./WorkerThread.mjs").WorkerThread<any, any>;
+export type unwrapLazy = "vivth:unwrapLazy;";
+import { Derived } from './Derived.mjs';

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

@@ -1,37 +1,38 @@
 /**
  * @description
  * - class helper for `WorkerThread` creation;
- * @template Receive
- * @template Post
+ * - before any `Worker` functionaily to be used, you need to setup it with `WorkerThread.setup` and `WorkerMainThread.setup` before runing anytyhing;
+ * @template RECEIVE
+ * @template POST
  */
-export class WorkerThread<Receive, Post> {
+export class WorkerThread<RECEIVE, POST> {
     /**
-     * @type {{parentPort:()=>Promise<any>}}
+     * @typedef {import('../types/QCBReturn.mjs').QCBReturn} QCBReturn
      */
-    static #parentPortRef: {
-        parentPort: () => Promise<any>;
-    };
+    /**
+     * @type {Parameters<typeof WorkerThread["setup"]>[0]}
+     */
+    static #refs: Parameters<(typeof WorkerThread)["setup"]>[0];
     /**
      * @description
      * - need to be called and exported as new `WorkerThread` class reference;
-     * @template Receive_
-     * @template Post_
-     * @param {{parentPort:()=>Promise<any>}} parentPortRef
-     * - correct parentPort reference, example:
+     * @template RECEIVE
+     * @template POST
+     * @param {{parentPort:import('worker_threads')["parentPort"]}} refs
+     * -example:
      * ```js
-     * async () => (await import('node:worker_threads')).parentPort
+     * import { parentPort } from 'node:worker_threads';
      * ```
-     * @returns {typeof WorkerThread<Receive_, Post_>}
+     * @returns {typeof WorkerThread<RECEIVE, POST>}
      * @example
      * import { WorkerThread } from 'vivth';
+     * import { parentPort } from 'node:worker_threads';
      *
-     * WorkerThread.setup({ parentPort: async () => (await import('node:worker_threads')).parentPort });
-     * // that is the default value, if your parentPort/equivalent API is not that;
-     * // you need to call this method;
+     * export const MyWorkerThreadRef = WorkerThread.setup({ parentPort });
      */
-    static setup: (parentPortRef: {
-        parentPort: () => Promise<any>;
-    }) => typeof WorkerThread<Receive_, Post_>;
+    static setup<RECEIVE_1, POST_1>(refs: {
+        parentPort: typeof import("worker_threads")["parentPort"];
+    }): typeof WorkerThread<RECEIVE_1, POST_1>;
     /**
      * @param {any} ev
      */
@@ -44,30 +45,34 @@ export class WorkerThread<Receive, Post> {
      * import { MyWorkerThread } from './MyWorkerThread.mjs';
      *
      * const doubleWorker = new MyWorkerThread((ev, isLastOnQ) => {
-     * 	// if(!isLastOnQ) {
+     * 	// if(!isLastOnQ()) {
      * 	// 	return null; // can be used for imperative debouncing;
      * 	// }
+     * 	// await fetch('some/path')
+     * 	// if(!isLastOnQ()) {
+     * 	// 	return;
+     * 	// }
      * 	return ev = ev \* 2;
      * });
      */
-    constructor(handler: (ev: any, isLastOnQ: boolean) => any);
+    constructor(handler: (ev: any, isLastOnQ: () => boolean) => any);
     /**
      * @description
      * - type helper;
-     * @type {(ev: Receive, isLastOnQ:boolean) => Post}
+     * @type {(ev: RECEIVE, isLastOnQ:QCBReturn["isLastOnQ"]) => POST}
      */
-    handler: (ev: Receive, isLastOnQ: boolean) => Post;
+    handler: (ev: RECEIVE, isLastOnQ: () => boolean) => POST;
     /**
      * @description
      * - helper type, hold no actual value;
-     * @type {Receive}
+     * @type {RECEIVE}
      */
-    Receive: Receive;
+    RECEIVE: RECEIVE;
     /**
      * @description
      * - helper type, hold no actual value;
-     * @type {Post}
+     * @type {POST}
      */
-    Post: Post;
+    POST: POST;
     #private;
 }

package/types/src/common/Base64URL.d.mts

@@ -1 +1,22 @@
-export function Base64URL(fileString: string, mimeType: string, btoaFunction: (string: string) => string): string;
+/**
+ * @description
+ * - create inline base64 url;
+ * - usage:
+ * >- can be extremely usefull to display file on desktop app webview, without exposing http server;
+ * @param {string} fileString
+ * @param {string} mimeType
+ * @param {(string:string)=>string} btoaFunction
+ * - check your js runtime `btoa`;
+ * - node compatible:
+ * ```js
+ * (str, prevBufferEncoding) =>
+ * 	Buffer.from(str, prevBufferEncoding).toString('base64')
+ * ```
+ * @returns {Base64URLString}
+ * @example
+ * import { Base64URL } from 'vivth'
+ * import fileString from './fileString.mjs';
+ *
+ * Base64URL(fileString, 'application/javascript', btoa);
+ */
+export function Base64URL(fileString: string, mimeType: string, btoaFunction: (string: string) => string): Base64URLString;

package/types/src/common/Base64URLFromFile.d.mts

@@ -0,0 +1,16 @@
+/**
+ * @description
+ * - create inline base64 url;
+ * - usage:
+ * >- can be extremely usefull to display file on desktop app webview, without exposing http server;
+ * >- when using `FSInline`, use [Base64URL](#base64url) instead;
+ * @param {string} filePath
+ * @returns {Promise<Base64URLString>}
+ * @example
+ * import { join } from 'node:path'
+ *
+ * import { Base64URLFromFile, Paths } from 'vivth'
+ *
+ * await Base64URLFromFile(join(Paths.root, '/path/to/file'));
+ */
+export function Base64URLFromFile(filePath: string): Promise<Base64URLString>;

package/types/src/common/keys.d.mts

@@ -0,0 +1 @@
+export const keys_vivthGenereteDir: ".vivth";

package/types/src/doc/JSautoDOC.d.mts

@@ -14,7 +14,7 @@
  * >>- `"at"description` are treated as plain `markdown`;
  * >>- first `"at"${string}` after `"at"description` until `"at"example` will be treated as `javascript` comment block on the `markdown`;
  * >>- `"at"example` are treated as `javascript` block on the `markdown` file, and should be placed last on the same comment block;
- * >>- you can always look at `vivth/src` files to check how the source, and the `README.md` and `index.mjs` is documentation/generation results;
+ * >>- you can always look at `vivth/src` files to check how the source, and the `README.md` and `index.mjs` documentation/generation results;
  */
 export class JSautoDOC {
     /**
@@ -36,25 +36,9 @@ export class JSautoDOC {
      * @param {import('chokidar').ChokidarOptions} [options.option]
      * - ChokidarOptions;
      * @example
-     * import { Console, Setup, JSautoDOC } from 'vivth';
+     * import { JSautoDOC } from 'vivth';
      *
-     * const { paths, safeExit } = Setup;
-     *
-     * new paths({
-     * 	root: process?.env?.INIT_CWD ?? process?.cwd(),
-     * });
-     *
-     * new safeExit({
-     * 	exitEventNames: ['SIGINT', 'SIGTERM', 'exit'],
-     * 	exitCallbackListeners: (eventName) => {
-     * 		process.once(eventName, function () {
-     * 			safeExit.instance.exiting.correction(true);
-     * 			Console.log(`safe exit via "${eventName}"`);
-     * 		});
-     * 	},
-     * });
-     *
-     * new JSautoDOC({
+     *  new JSautoDOC({
      * 	paths: { dir: 'src', file: 'index.mjs', readMe: 'README.md' },
      * 	copyright: 'this library is made and distributed under MIT license;',
      * 	tableOfContentTitle: 'list of exported API and typehelpers',