vivth 0.11.1 → 1.0.0

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

@@ -1,53 +1,132 @@
 /**
- * @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;
+ * @type {Set<Signal>}
  */
+export const setOFSignals: Set<Signal<any>>;
 /**
+ * @description
+ * - a class for creating effect to signals;
  * @template Value
  */
 export class Signal<Value> {
     /**
-     * @param {Value} value
-     */
-    constructor(value: Value);
-    /**
-     * @protected
+     * @param {Set<Effect>} setOfSubscribers
      */
-    protected get subscribed(): Set<$>;
+    static "__#13628@#notify": (setOfSubscribers: Set<Effect>) => void;
     /**
-     * destroy all props
+     * @description
+     * @param {Value} value
+     * @example
+     * import { Signal, Effect } from  'vivth';
+     *
+     * const count = new Signal(0);
      */
-    unRef: () => void;
+    constructor(value: Value);
     /**
-     * remove all effects
-     * @return {void}
+     * @description
+     * - subsrcibers reference of this instance;
      */
-    removeAll$: () => void;
+    subscribers: {
+        /**
+         * @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
+         * // 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;
+    } & {
+        "vivth:unwrapLazy;": string;
+    };
     /**
-     * remove effect
-     * @param {$} $_
-     * @return {void}
+     * @description
+     * - collection of remove methods
      */
-    remove$: ($_: $) => void;
-    get prev(): Value;
+    remove: {
+        /**
+         * @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;
+    } & {
+        "vivth:unwrapLazy;": string;
+    };
     /**
+     * @description
+     * - value before change;
      * @type {Value}
      */
-    get nonReactiveValue(): Value;
+    get prev(): Value;
     /**
+     * @description
+     * - assign new value then automatically notify all subscribers;
      * @type {Value}
+     * @example
+     * import { Signal } from  'vivth';
+     *
+     * const count = new Signal(0);
+     * count.value++;
+     * // OR
+     * count.value = 9;
      */
     set value(newValue: Value);
     /**
+     * @description
+     * - value after change;
      * @type {Value}
+     * @example
+     * import { Signal, Effect, Derived } from  'vivth';
+     *
+     * const count = new Signal(0);
+     * count.value; // not reactive
+     *
+     * new Effect(async ({ subscribe }) =>{
+     * 	const countValue = subscribe(count).value; // reactive
+     * })
+     * const oneMoreThanCount = new Effect(async ({ subscribe }) =>{
+     * 	return subscribe(count).value + 1; // reactive
+     * })
      */
     get value(): Value;
-    /**
-     * @returns {void}
-     */
-    call$: () => void;
     #private;
 }
-import { $ } from './$.mjs';
+import { Effect } from './Effect.mjs';

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

@@ -0,0 +1,149 @@
+/**
+ * @template A
+ * @typedef {import('./WorkerResult.mjs').WorkerResult<A>} WorkerResult
+ */
+/**
+ * @typedef {import('./WorkerThread.mjs').WorkerThread} WorkerThread
+ */
+/**
+ * @description
+ * - class helper to create `Worker` instance;
+ * @template {WorkerThread} WT
+ */
+export class WorkerMainThread<WT extends WorkerThread> {
+    static "__#18619@#isRegistered": boolean;
+    /**
+     * @description
+     * - need to be called first, before any `WorkerMainThread` instantiation:
+     * @param {Object} param0
+     * @param {typeof WorkerMainThread["workerClass"]} param0.workerClass
+     * @param {typeof WorkerMainThread["pathValidator"]} param0.pathValidator
+     * ```js
+     *	async(relativePath) => {
+     *		// verify whether relativePath exist, then return the full path
+     *		// use fetch | fs, chained with Paths.instance.root + WorkerMainThread.basePath;
+     *	}
+     * ```
+     * @param {typeof WorkerMainThread["basePath"]} [param0.basePath]
+     * - additonal realtivePath from rootPath;
+     * - default: '';
+     * @example
+     * import { WorkerMainThread } from 'vivth';
+     *
+     * WorkerMainThread.setup({
+     * 	workerClass: async () => await (import('worker_threads')).Worker,
+     * 	basePath: 'public/assets/js/workers',
+     * 	pathValidator: async (workerPath, root, base) => {
+     * 		const res = await fetch(`${root}/${base}/${workerPath}`);
+     * 		// might also check wheter it need base or not
+     * 		return await res.ok;
+     * 	},
+     * });
+     */
+    static setup: ({ workerClass, pathValidator, basePath }: {
+        workerClass: (typeof WorkerMainThread)["workerClass"];
+        pathValidator: (typeof WorkerMainThread)["pathValidator"];
+        basePath?: (typeof WorkerMainThread)["basePath"];
+    }) => void;
+    /**
+     * @description
+     * - reference for `Worker` class;
+     * - edit via `setup`;
+     * @type {()=>Promise<typeof Worker|typeof import('worker_threads').Worker>}
+     */
+    static workerClass: () => Promise<typeof Worker | typeof import("worker_threads").Worker>;
+    /**
+     * @description
+     * - reference for worker file `basePath`;
+     * - edit via `setup`;
+     * @type {string}
+     */
+    static basePath: string;
+    /**
+     * @description
+     * - reference for validating path;
+     * - edit via `setup`;
+     * @type {(paths:{worker: string, root:string, base: string})=>Promise<string>}
+     */
+    static pathValidator: (paths: {
+        worker: string;
+        root: string;
+        base: string;
+    }) => Promise<string>;
+    static "__#18619@#options": import("worker_threads").WorkerOptions & {
+        type?: "module";
+    };
+    /**
+     * @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 "__#18619@#workerFilehandler": (handler: string, options: WorkerOptions | import("worker_threads").WorkerOptions, worker: WorkerMainThread<any>, listener: (any: any) => void, isInline: boolean) => Promise<void>;
+    /**
+     * @type {boolean}
+     */
+    static "__#18619@#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]
+     * @example
+     * import { WorkerMainThread } from 'vivth';
+     *
+     * export const myDoubleWorker = new WorkerMainThread('./doubleWorkerThread.mjs');
+     */
+    constructor(handler: string, options?: Omit<WorkerOptions | import("worker_threads").WorkerOptions, "eval" | "type">, isInline?: boolean);
+    /**
+     * @description
+     * - terminate all signals that are used on this instance;
+     * @type {()=>void}
+     */
+    terminate: () => void;
+    /**
+     * @description
+     * - result signal of the processed message;
+     * @type {Derived<WorkerResult<WT["Post"]>>}
+     * @example
+     * import { Effect } from 'vivth';
+     * import { myDoubleWorker } from './myDoubleWorker.mjs';
+     *
+     * const doubleReceiverSignal = myDoubleWorker.receiverSignal;
+     * new Effect(async({ subscribe }) => {
+     * 	const value = subscribe(doubleReceiverSignal).value;
+     * 	// code
+     * })
+     */
+    receiverSignal: Derived<WorkerResult<WT["Post"]>>;
+    /**
+     * @description
+     * - callback to send message to the worker thread;
+     * @type {(event: WT["Receive"])=>void}
+     * @example
+     * import { myDoubleWorker } from './myDoubleWorker.mjs';
+     *
+     * myDoubleWorker.postMessage(90);
+     */
+    postMessage: (event: WT["Receive"]) => void;
+    #private;
+}
+export type WorkerResult<A> = import("./WorkerResult.mjs").WorkerResult<A>;
+export type WorkerThread = import("./WorkerThread.mjs").WorkerThread<any, any>;
+import { Derived } from './Derived.mjs';

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

@@ -0,0 +1,25 @@
+/**
+ * @description
+ * - typeHelper for `Worker` message passing;
+ * - uses error as value instead;
+ * @template POST
+ */
+export class WorkerResult<POST> {
+    /**
+     * @param {POST} data
+     * @param {Error|string|undefined} error
+     */
+    constructor(data: POST, error: Error | string | undefined);
+    /**
+     * @description
+     * - result value;
+     * @type {POST}
+     */
+    data: POST;
+    /**
+     * @description
+     * - error value;
+     * @type {Error|string|undefined}
+     */
+    error: Error | string | undefined;
+}

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

@@ -0,0 +1,70 @@
+/**
+ * @description
+ * - class helper for `WorkerThread` creation;
+ * @template Receive
+ * @template Post
+ */
+export class WorkerThread<Receive, Post> {
+    /**
+     * @type {{parentPort:()=>Promise<any>}}
+     */
+    static "__#16626@#parentPortRef": {
+        parentPort: () => Promise<any>;
+    };
+    /**
+     * @description
+     * - need to be called and exported as new `WorkerThread` class reference;
+     * @template Receive_
+     * @template Post_
+     * @param {{parentPort:()=>Promise<any>}} parentPortRef
+     * - correct parentPort reference;
+     * @returns {typeof WorkerThread<Receive_, Post_>}
+     * @example
+     * import { WorkerThread } from 'vivth';
+     *
+     * WorkerThread.setup({ parentPort: async () => await import('node:worker_threads') });
+     * // that is the default value, if your parentPort/equivalent API is not that;
+     * // you need to call this method;
+     */
+    static setup: (parentPortRef: {
+        parentPort: () => Promise<any>;
+    }) => typeof WorkerThread<Receive_, Post_>;
+    /**
+     * @param {any} ev
+     */
+    static "__#16626@#isCloseWorkerEvent": (ev: any) => boolean;
+    /**
+     * @description
+     * - instantiate via created class from `setup` static method;
+     * @param {WorkerThread["handler"]} handler
+     * @example
+     * import { MyWorkerThread } from './MyWorkerThread.mjs';
+     *
+     * const doubleWorker = new MyWorkerThread((ev, isLastOnQ) => {
+     * 	// if(!isLastOnQ) {
+     * 	// 	return null; // can be used for imperative debouncing;
+     * 	// }
+     * 	return ev = ev \* 2;
+     * });
+     */
+    constructor(handler: (ev: any, isLastOnQ: boolean) => any);
+    /**
+     * @description
+     * - type helper;
+     * @type {(ev: Receive, isLastOnQ:boolean) => Post}
+     */
+    handler: (ev: Receive, isLastOnQ: boolean) => Post;
+    /**
+     * @description
+     * - helper type, hold no actual value;
+     * @type {Receive}
+     */
+    Receive: Receive;
+    /**
+     * @description
+     * - helper type, hold no actual value;
+     * @type {Post}
+     */
+    Post: Post;
+    #private;
+}

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

@@ -0,0 +1 @@
+export function Base64URL(fileString: string, mimeType: string, btoaFunction: (string: string) => string): string;

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

@@ -0,0 +1,6 @@
+/**
+ * @description
+ * - namespacing for event, string as ID, related API;
+ * @type {'vivthEvent'}
+ */
+export const EventNameSpace: "vivthEvent";

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

@@ -0,0 +1,3 @@
+export const closeWorkerThreadEventObject: {
+    vivthEvent: "worker:terminate";
+};

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

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

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

@@ -0,0 +1,76 @@
+/**
+ * @description
+ * - class for auto documenting mjs package/project, using jsdoc;
+ * - this autodocumenter uses [chokidar](https://npmjs.com/package/chokidar) under the hood;
+ * - this class also is used to generate this `README.md`;
+ * - behaviours:
+ * >1) export all named exported 'const'|'function'|'async function'|'class', alphanumeric name, started with Capital letter, same name with fileName on `options.pahts.file`;
+ * >2) declare typedef of existing typedef with alphanumeric name, started with Capital letter, same name with fileName, and have no valid export like on point <sup>1</sup> on `options.pahts.file`;
+ * >3) create `README.md` based on, `options.paths.dir` and `README.src.md`;
+ * >4) extract `"at"description` jsdoc:
+ * >>- on static/prop that have depths, all of children should have `"at"static`/`"at"instance` `nameOfImmediateParent`, same block but before `"at"description` comment line;
+ * >>- `"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;
+ */
+export class JSautoDOC {
+    /**
+     * @type {JSautoDOC}
+     */
+    static "__#17292@#instance": JSautoDOC;
+    /**
+     * @description
+     * @param {Object} [options]
+     * @param {Object} [options.paths]
+     * @param {string} [options.paths.file]
+     * - entry point;
+     * @param {string} [options.paths.readMe]
+     * - readme target;
+     * @param {string} [options.paths.dir]
+     * - source directory;
+     * @param {string} [options.copyright]
+     * @param {string} [options.tableOfContentTitle]
+     * @param {import('chokidar').ChokidarOptions} [options.option]
+     * - ChokidarOptions;
+     * @example
+     * import { Console } from '../src/class/Console.mjs';
+     * import { Setup } from '../src/class/Setup.mjs';
+     * import { JSautoDOC } from '../src/doc/JSautoDOC.mjs';
+     *
+     * 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({
+     * 	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',
+     * });
+     *
+     */
+    constructor({ paths, tableOfContentTitle, copyright, option, }?: {
+        paths?: {
+            file?: string;
+            readMe?: string;
+            dir?: string;
+        };
+        copyright?: string;
+        tableOfContentTitle?: string;
+        option?: import("chokidar").ChokidarOptions;
+    });
+    #private;
+}
+export type Stats = import("fs").Stats;

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

@@ -0,0 +1,154 @@
+export class parsedFile {
+    /**
+     * @param {string} exportName
+     * @returns {boolean}
+     */
+    static "__#12@#isExportNameValid": (exportName: string) => boolean;
+    /**
+     * @param {string} content
+     * @returns { RegExpExecArray[] }
+     */
+    static getDescription: (content: string) => RegExpExecArray[];
+    /**
+     * @typedef {{
+     *	instanceOrStatic:{parent:string, type:string},
+     *	fullDescription:string,
+     *	parsedFullDescription:{description:string, jsPreview:string},
+     *	isExport:boolean,
+     *	typeOfVar:string,
+     *	namedVar:string,
+     *	reference:string,
+     * }} refType
+     */
+    /**
+     * @param {string} path__
+     * @param {BufferEncoding} [encoding]
+     */
+    constructor(path__: string, encoding?: BufferEncoding);
+    documented: {
+        typedef: () => Promise<{
+            module: string;
+            readme: string;
+        }>;
+        /**
+         * @type {Set<refType>}
+         */
+        readme: Set<{
+            instanceOrStatic: {
+                parent: string;
+                type: string;
+            };
+            fullDescription: string;
+            parsedFullDescription: {
+                description: string;
+                jsPreview: string;
+            };
+            isExport: boolean;
+            typeOfVar: string;
+            namedVar: string;
+            reference: string;
+        }>;
+    } & {
+        "vivth:unwrapLazy;": string;
+    };
+    /**
+     * @type {undefined|{module:string, readme:string}}
+     */
+    parsedType: undefined | {
+        module: string;
+        readme: string;
+    };
+    hasValidExportObject: boolean;
+    /**
+     * @returns {Promise<boolean>}
+     */
+    isFile: () => Promise<boolean>;
+    /**
+     * @returns {Promise<boolean>}
+     */
+    isDirectory: () => Promise<boolean>;
+    baseName: {
+        /**
+         * @type {string}
+         */
+        readonly withExt: string;
+        /**
+         * @type {string}
+         */
+        readonly noExt: string;
+    } & {
+        "vivth:unwrapLazy;": string;
+    };
+    path: {
+        /**
+         * @type {string}
+         */
+        readonly relative: string;
+        /**
+         * @type {string}
+         */
+        readonly full: string;
+    } & {
+        "vivth:unwrapLazy;": string;
+    };
+    get dirName(): {
+        /**
+         * @type {string}
+         */
+        readonly relative: string;
+        /**
+         * @type {string}
+         */
+        readonly full: string;
+    };
+    get ext(): {
+        /**
+         * @type {string|undefined}
+         */
+        readonly withDot: string | undefined;
+        /**
+         * @type {string|undefined}
+         */
+        readonly noDot: string | undefined;
+    };
+    /**
+     * @private
+     * @returns {Promise<Stats>}
+     */
+    private stats;
+    get timeStamp(): {
+        /**
+         * @returns {Promise<number>}
+         */
+        lastModified: () => Promise<number>;
+        /**
+         * @returns {Promise<number>}
+         */
+        createdAt: () => Promise<number>;
+    };
+    content: {
+        /**
+         * @return {Promise<string|undefined>}
+         */
+        string: () => Promise<string | undefined>;
+        parsed: () => Promise<{
+            exportName: undefined;
+            details: undefined;
+            error: {
+                fullpath: string;
+                message: string;
+            };
+        } | {
+            exportName: string | undefined;
+            details: ReturnType<(typeof parsedFile)["getDescription"]>;
+            error: undefined;
+        }>;
+    } & {
+        "vivth:unwrapLazy;": string;
+    };
+    /**
+     * @type {[Promise<any>, undefined]|[undefined, Error]}
+     */
+    get importAsModuleJS(): [Promise<any>, undefined] | [undefined, Error];
+    #private;
+}

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

@@ -0,0 +1,3 @@
+export function CreateImmutable<P extends unknown, O extends unknown>(parent: P, keyName: string, object: (this: P) => O, { lazy }?: {
+    lazy?: boolean;
+}): O;

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

@@ -0,0 +1,2 @@
+export function EventCheck(object: any, eventObject: Record<typeof EventNameSpace, string>): boolean;
+import { EventNameSpace } from '../common/EventNameSpace.mjs';

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

@@ -0,0 +1,4 @@
+export function EventObject<N extends string>(name: N): {
+    [EventNameSpace]: N;
+};
+import { EventNameSpace } from '../common/EventNameSpace.mjs';

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

@@ -0,0 +1 @@
+export function IsAsync(functionReference: (...any: any) => (any | Promise<any>)): boolean;

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

@@ -0,0 +1,4 @@
+export function LazyFactory<T>(factory: () => T): T & {
+    [unwrapLazy]: string;
+};
+import { unwrapLazy } from '../common/lazie.mjs';

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

@@ -0,0 +1 @@
+export function Timeout(timeMS: number): Promise<void>;

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

@@ -0,0 +1 @@
+export function Try<Key extends string, ReturnType_, RecordTryType extends Record<Key, () => Promise<ReturnType_>>>(tryRecord: RecordTryType): Promise<[[keyof RecordTryType, ReturnType_], undefined] | [[undefined, undefined], Error]>;