vivth 1.4.9 → 1.5.0

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

@@ -0,0 +1,83 @@
+/**
+ * it supposed to be able to call on browser too
+ * ```js
+ * import { SafeExit } from './SafeExit.mjs';
+ * ```
+ * need to add cleaner for SafeExit.instance?.addCallback
+ */
+/**
+ * @typedef {import('../typehints/VivthCleanup.mjs').VivthCleanup} VivthCleanup
+ */
+/**
+ * @template {WorkerThread<any, any>} WT
+ * @implements {VivthCleanup}
+ */
+export class WorkerMainThread<WT extends import("./WorkerThread.mjs").WorkerThread<any, any>> implements VivthCleanup {
+    /**
+     * @template POST
+     * @typedef {import('./WorkerResult.mjs').WorkerResult<POST>} WorkerResult
+     */
+    /**
+     * @template RECEIVE
+     * @template POST
+     * @typedef {import('./WorkerThread.mjs').WorkerThread<RECEIVE, POST>} WorkerThread
+     */
+    /**
+     * @type {boolean}
+     */
+    static #isRegistered: boolean;
+    /**
+     * @param {Object} param0
+     * @param {typeof WorkerMainThread["workerClass"]} param0.workerClass
+     * @param {typeof WorkerMainThread["pathValidator"]} param0.pathValidator
+     */
+    static setup: ({ workerClass, pathValidator }: {
+        workerClass: (typeof WorkerMainThread)["workerClass"];
+        pathValidator: (typeof WorkerMainThread)["pathValidator"];
+    }) => void;
+    /**
+     * @type {typeof Worker|typeof import('node:worker_threads').Worker}
+     */
+    static workerClass: typeof Worker | typeof import("node:worker_threads").Worker;
+    /**
+     * @type {(paths:{worker: string, root:string})=>Promise<string>}
+     */
+    static pathValidator: (paths: {
+        worker: string;
+        root: string;
+    }) => Promise<string>;
+    static #options: import("node:worker_threads").WorkerOptions & {
+        type?: "module";
+    };
+    /**
+     * @template {WorkerThread<any, any>} WT
+     * @param {string} handler
+     * @param { WorkerOptions
+     * | import('node:worker_threads').WorkerOptions} options
+     * @param {WorkerMainThread<WT>} worker
+     * @param {(any:any)=>void} listener
+     * @returns {Promise<void>}
+     */
+    static #workerFilehandler<WT_1 extends import("./WorkerThread.mjs").WorkerThread<any, any>>(handler: string, options: WorkerOptions | import("node:worker_threads").WorkerOptions, worker: WorkerMainThread<WT_1>, listener: (any: any) => void): Promise<void>;
+    /**
+     * @param {PathFSFile} handler
+     * @param {Omit<WorkerOptions|import('node:worker_threads').WorkerOptions, 'eval'|'type'>} options
+     */
+    constructor(handler: PathFSFile, options?: Omit<WorkerOptions | import("node:worker_threads").WorkerOptions, "eval" | "type">);
+    /**
+     * @return {Promise<void>}
+     */
+    vivthCleanup: () => Promise<void>;
+    /**
+     * @type {Derived<WorkerResult<WT["POST"]>>}
+     */
+    receiverSignal: Derived<import("./WorkerResult.mjs").WorkerResult<WT["POST"]>>;
+    /**
+     * @type {(event: WT["RECEIVE"])=>void}
+     */
+    postMessage: (event: WT["RECEIVE"]) => void;
+    #private;
+}
+export type VivthCleanup = import("../typehints/VivthCleanup.mjs").VivthCleanup;
+import { Derived } from './Derived.mjs';
+import { PathFSFile } from '../bundler/adds/PathFSFile.mjs';

package/{types → generated/types}/src/class/WorkerMainThread.d.mts

@@ -1,26 +1,34 @@
 /**
- * @template POST
- * @typedef {import('./WorkerResult.mjs').WorkerResult<POST>} WorkerResult
+ * it supposed to be able to call on browser too
+ * ```js
+ * import { SafeExit } from './SafeExit.mjs';
+ * ```
+ * need to add cleaner for SafeExit.instance?.addCallback
  */
 /**
- * @template RECEIVE
- * @template POST
- * @typedef {import('./WorkerThread.mjs').WorkerThread<RECEIVE, POST>} WorkerThread
- */
-/**
- * @typedef {import('../common/lazie.mjs').unwrapLazy} unwrapLazy
+ * @typedef {import('../typehints/VivthCleanup.mjs').VivthCleanup} VivthCleanup
  */
 /**
  * @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<any, any>} WT
+ * @implements {VivthCleanup}
  */
-export class WorkerMainThread<WT extends WorkerThread<any, any>> {
+export class WorkerMainThread<WT extends import("./WorkerThread.mjs").WorkerThread<any, any>> implements VivthCleanup {
+    /**
+     * @template POST
+     * @typedef {import('./WorkerResult.mjs').WorkerResult<POST>} WorkerResult
+     */
+    /**
+     * @template RECEIVE
+     * @template POST
+     * @typedef {import('./WorkerThread.mjs').WorkerThread<RECEIVE, POST>} WorkerThread
+     */
     /**
      * @type {boolean}
      */
-    static "__#private@#isRegistered": boolean;
+    static #isRegistered: boolean;
     /**
      * @description
      * - need to be called first, before any `WorkerMainThread` instantiation:
@@ -42,7 +50,7 @@ export class WorkerMainThread<WT extends WorkerThread<any, any>> {
      * ```
      * @example
      * import { Worker } from 'node:worker_threads';
-     * import { WorkerMainThread } from 'vivth';
+     * import { WorkerMainThread } from 'vivth/neutral';
      *
      * WorkerMainThread.setup({
      * 	workerClass: Worker,
@@ -79,22 +87,9 @@ export class WorkerMainThread<WT extends WorkerThread<any, any>> {
         worker: string;
         root: string;
     }) => Promise<string>;
-    static "__#private@#options": import("node:worker_threads").WorkerOptions & {
+    static #options: import("node:worker_threads").WorkerOptions & {
         type?: "module";
     };
-    /**
-     * @template {WorkerThread<any, any>} WT
-     * @description
-     * - create Worker_instance;
-     * @param {string} handler
-     * @param {Omit<WorkerOptions|import('node:worker_threads').WorkerOptions, 'eval'|'type'>} [options]
-     * @returns {WorkerMainThread<WT>}
-     * @example
-     * import { WorkerMainThread } from 'vivth';
-     *
-     * export const myDoubleWorker = WorkerMainThread.newVivthWorker('./doubleWorkerThread.mjs');
-     */
-    static newVivthWorker<WT_1 extends WorkerThread<any, any>>(handler: string, options?: Omit<WorkerOptions | import("node:worker_threads").WorkerOptions, "eval" | "type">): WorkerMainThread<WT_1>;
     /**
      * @template {WorkerThread<any, any>} WT
      * @param {string} handler
@@ -104,29 +99,30 @@ export class WorkerMainThread<WT extends WorkerThread<any, any>> {
      * @param {(any:any)=>void} listener
      * @returns {Promise<void>}
      */
-    static "__#private@#workerFilehandler"<WT_1 extends WorkerThread<any, any>>(handler: string, options: WorkerOptions | import("node:worker_threads").WorkerOptions, worker: WorkerMainThread<WT_1>, listener: (any: any) => void): Promise<void>;
+    static #workerFilehandler<WT_1 extends import("./WorkerThread.mjs").WorkerThread<any, any>>(handler: string, options: WorkerOptions | import("node:worker_threads").WorkerOptions, worker: WorkerMainThread<WT_1>, listener: (any: any) => void): Promise<void>;
     /**
-     * @private
-     * @param {Parameters<typeof WorkerMainThread<WT>["newVivthWorker"]>[0]} handler
-     * @param {Parameters<typeof WorkerMainThread<WT>["newVivthWorker"]>[1]} [options]
+     * @description
+     * - create Worker_instance;
+     * @param {import('../bundler/adds/PathFSBundles.mjs').PathFSBundles} handler
+     * @param {Omit<WorkerOptions|import('node:worker_threads').WorkerOptions, 'eval'|'type'>} options
      * @example
-     * import { WorkerMainThread } from 'vivth';
+     * import { WorkerMainThread } from 'vivth/neutral';
      *
-     * export const myDoubleWorker = WorkerMainThread.newVivthWorker('./doubleWorkerThread.mjs');
+     * export const myDoubleWorker = new WorkerMainThread(PathFSBundles.vivthBundles('./doubleWorkerThread.mjs'));
      */
-    private constructor();
+    constructor(handler: import("../bundler/adds/PathFSBundles.mjs").PathFSBundles, options?: Omit<WorkerOptions | import("node:worker_threads").WorkerOptions, "eval" | "type">);
     /**
      * @description
      * - terminate all signals that are used on this instance;
-     * @return {void}
+     * @return {Promise<void>}
      */
-    terminate: () => void;
+    vivthCleanup: () => Promise<void>;
     /**
      * @description
      * - result signal of the processed message;
      * @type {Derived<WorkerResult<WT["POST"]>>}
      * @example
-     * import { Effect } from 'vivth';
+     * import { Effect } from 'vivth/neutral';
      * import { myDoubleWorker } from './myDoubleWorker.mjs';
      *
      * const doubleReceiverSignal = myDoubleWorker.receiverSignal;
@@ -135,7 +131,7 @@ export class WorkerMainThread<WT extends WorkerThread<any, any>> {
      * 	// code
      * })
      */
-    receiverSignal: Derived<WorkerResult<WT["POST"]>>;
+    receiverSignal: Derived<import("./WorkerResult.mjs").WorkerResult<WT["POST"]>>;
     /**
      * @description
      * - callback to send message to the worker thread;
@@ -148,7 +144,5 @@ export class WorkerMainThread<WT extends WorkerThread<any, any>> {
     postMessage: (event: WT["RECEIVE"]) => void;
     #private;
 }
-export type WorkerResult<POST> = import("./WorkerResult.mjs").WorkerResult<POST>;
-export type WorkerThread<RECEIVE, POST> = import("./WorkerThread.mjs").WorkerThread<RECEIVE, POST>;
-export type unwrapLazy = "vivth:unwrapLazy;";
+export type VivthCleanup = import("../typehints/VivthCleanup.mjs").VivthCleanup;
 import { Derived } from './Derived.mjs';

package/{types → generated/types}/src/class/WorkerThread.d.mts

@@ -1,18 +1,22 @@
+/**
+ * @typedef { import('../typehints/VivthCleanup.mjs').VivthCleanup } VivthCleanup
+ */
 /**
  * @description
  * - class helper for `WorkerThread` creation;
  * - 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
+ * @implements {VivthCleanup}
  */
-export class WorkerThread<RECEIVE, POST> {
+export class WorkerThread<RECEIVE, POST> implements VivthCleanup {
     /**
-     * @typedef {import('../types/QCBReturn.mjs').QCBReturn} QCBReturn
+     * @typedef {import('../typehints/QCBReturn.mjs').QCBReturn} QCBReturn
      */
     /**
      * @type {Parameters<typeof WorkerThread["setup"]>[0]|undefined}
      */
-    static "__#private@#refs": Parameters<(typeof WorkerThread)["setup"]>[0] | undefined;
+    static #refs: Parameters<(typeof WorkerThread)["setup"]>[0] | undefined;
     /**
      * @description
      * - need to be called and exported as new `WorkerThread` class reference;
@@ -25,8 +29,8 @@ export class WorkerThread<RECEIVE, POST> {
      * ```
      * @returns {typeof WorkerThread<RECEIVE, POST>}
      * @example
-     * import { WorkerThread } from 'vivth';
      * import { parentPort } from 'node:worker_threads';
+     * import { WorkerThread } from 'vivth/neutral';
      *
      * export const MyWorkerThreadRef = WorkerThread.setup({ parentPort });
      */
@@ -36,7 +40,7 @@ export class WorkerThread<RECEIVE, POST> {
     /**
      * @param {any} ev
      */
-    static "__#private@#isCloseWorkerEvent": (ev: any) => boolean;
+    static #isCloseWorkerEvent: (ev: any) => boolean;
     /**
      * @description
      * - instantiate via created class from `setup` static method;
@@ -57,6 +61,7 @@ export class WorkerThread<RECEIVE, POST> {
      * new MyWorkerThread(handler);
      */
     constructor(handler: WorkerThread<RECEIVE, POST>["handler"]);
+    vivthCleanup: () => Promise<void>;
     /**
      * @description
      * - type helper;
@@ -77,3 +82,4 @@ export class WorkerThread<RECEIVE, POST> {
     POST: POST;
     #private;
 }
+export type VivthCleanup = import("../typehints/VivthCleanup.mjs").VivthCleanup;

package/{types → generated/types}/src/common/Base64URL.d.mts

@@ -15,7 +15,8 @@
  * ```
  * @returns {string}
  * @example
- * import { Base64URL } from 'vivth'
+ * import { Base64URL } from 'vivth/neutral';
+ *
  * import fileString from './fileString.mjs';
  *
  * // example for browser;

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

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

package/generated/types/src/common/BundledV.bundled.d.mts

@@ -0,0 +1,3 @@
+export class BundledV {
+    static get isBundled(): boolean;
+}

package/generated/types/src/common/BundledV.d.mts

@@ -0,0 +1,36 @@
+/**
+ * @description
+ * - class helper for `vivth` `Bundled` values;
+ */
+export class BundledV {
+    static #isBundled: boolean;
+    /**
+     * @description
+     * - readonly value of whether the script run after being bundled with `vivth` or not;
+     * @readonly
+     * @type {boolean}
+     * @example
+     * import { BundledV } from 'vivth/neutral';
+     *
+     * if(BundledV.isBundled){
+     * 	// code
+     * }
+     */
+    static readonly get isBundled(): boolean;
+    /**
+     * @description
+     * - to create `unbundled` only codeBlock;
+     * >- when properly bundled via `vivth` bundling mechanism, this code block will be removed;
+     * @param {()=>void} callback
+     * @param {import('./VivthUnBundledCodeBlock.mjs').VivthUnBundledCodeBlock} _closing
+     * - must be filled for regexp detection;
+     * @returns {void}
+     * @example
+     * import { BundledV } from 'vivth/neutral';
+     *
+     * BundledV.vivthUnBundledCodeBlock(() => {
+     * 	// code
+     * }, 'vivthUnBundledCodeBlock')
+     */
+    static vivthUnBundledCodeBlock: (callback: () => void, _closing: "vivthUnBundledCodeBlock") => void;
+}

package/{types → generated/types}/src/common/CreateStringID.d.mts

@@ -4,17 +4,18 @@
  * - the asynchrounous nature is to prevent race condition that might resulting same Id being generated;
  * >- queued using QChannel;
  * @param {string} [prefix]
+ * @param {string} [suffix]
  * @returns {ReturnType<typeof TryAsync<string>>}
  * @example
- * import { CreateStringID } from 'vivth';
+ * import { CreateStringID } from 'vivth/neutral';
  *
  * (async () => {
- * 	const [myUniqueID, errorCreatingUniqueID] = await CreateStringID('myPrefix');
+ * 	const [myUniqueID, errorCreatingUniqueID] = await CreateStringID('myPrefix', 'mySuffix');
  * 	if(errorCreatingUniqueID) {
  * 		return;
  * 	}
- * 	Console.log(myUniqueID); // `myPrefix${Date.now()}`
+ * 	Console.log(myUniqueID); // `myPrefix${Date.now()}mySuffix`
  * })()
  */
-export function CreateStringID(prefix?: string): ReturnType<typeof TryAsync<string>>;
+export function CreateStringID(prefix?: string, suffix?: string): ReturnType<typeof TryAsync<string>>;
 import { TryAsync } from '../function/TryAsync.mjs';

package/generated/types/src/common/EnvMode.d.mts

@@ -0,0 +1,79 @@
+/**
+ * @typedef {import('../typehints/EnvModeType.mjs').EnvModeType} EnvModeType
+ * @typedef {import('../typehints/DevTestCB.mjs').DevTestCB} DevTestCB
+ */
+/**
+ * @description
+ * - class helper for determining environtment mode to be `developement` or `production`;
+ */
+export class EnvMode {
+    /**
+     * @type {Signal<EnvModeType>}
+     */
+    static #mode: Signal<EnvModeType>;
+    /**
+     * @description
+     * - `Derived` wrapper of whether is in `dev` mode or `prod` not;
+     * >- for listener only;
+     * @type {Derived<EnvModeType>}
+     * @example
+     * import { EnvMode, Effect } from 'vivth/neutral';
+     *
+     * console.log(EnvMode.mode.value); // default: 'dev'
+     *
+     * // listeneing to changes;
+     * new Effect(async({ subscribe }) => {
+     * 	const mode = subscribe(EnvMode.mode).value;
+     * 	// code
+     * })
+     */
+    static mode: Derived<EnvModeType>;
+    /**
+     * @description
+     * - enforce development or production mode;
+     * - DO NOT EXPOSE THIS API TO UNSECURED ACCESS, DIRECTLY NOR INDIRECTLY;
+     * @param {EnvModeType} mode
+     * @returns {void}
+     * @example
+     * import { EnvMode } from 'vivth/neutral';
+     *
+     * EnvMode.enforce('dev'); // OR
+     * EnvMode.enforce('prod');
+     */
+    static enforce: (mode: EnvModeType) => void;
+    /**
+     * @type {Signal<Map<string,Awaited<ReturnType<typeof TryAsync<boolean>>>>>}
+     */
+    static #notifications: Signal<Map<string, Awaited<ReturnType<typeof TryAsync<boolean>>>>>;
+    /**
+     * @type {DevTestCB}
+     */
+    static #test: DevTestCB;
+    static #effectForCheck: Effect & {
+        [FactoryKey]: FACTORY;
+    };
+    /**
+     * @description
+     * @param {(options:{devTest:DevTestCB}|
+     * {devTest:undefined})=>Promise<void>
+     * } callback
+     * - when on `dev` mode also provide `test` method for inline testing:
+     * >- which is wrapped in `TryAsync`, throwed errors will automatically return `false`;
+     * - for smaller bundle size, you can wrap the `devTest` with `BundleV.vivthUnBundledCodeBlock`;
+     * @param {Effect["options"]["subscribe"]} [subscribe]
+     * - optional whether to scope the callback into an `Effect`;
+     * @returns {Promise<void>}
+     */
+    static codeBlock(callback: (options: {
+        devTest: DevTestCB;
+    } | {
+        devTest: undefined;
+    }) => Promise<void>, subscribe?: Effect["options"]["subscribe"]): Promise<void>;
+}
+export type EnvModeType = import("../typehints/EnvModeType.mjs").EnvModeType;
+export type DevTestCB = import("../typehints/DevTestCB.mjs").DevTestCB;
+import { Signal } from '../class/Signal.mjs';
+import { Derived } from '../class/Derived.mjs';
+import { TryAsync } from '../function/TryAsync.mjs';
+import { Effect } from '../class/Effect.mjs';
+import { FactoryKey } from './FactoryKey.mjs';

package/generated/types/src/common/FactoryKey.d.mts

@@ -0,0 +1,9 @@
+/**
+ * @description
+ * - key symbol to imediately generate object wrapped by `LazyFactory`;
+ * - usefull for Object that has different accessor behaviour when being get via Proxy, like:
+ * >- `Set<any>`;
+ * >- `Map<any, any>`;
+ * @type {symbol}
+ */
+export const FactoryKey: symbol;

package/generated/types/src/common/Preferrence.d.mts

@@ -0,0 +1,25 @@
+/**
+ * @description
+ * - class wrapper for `vivth` innerworking preferrences;
+ */
+export class Preferrence {
+    /**
+     * @description
+     * - default `vivth` innerworking encoding;
+     * @type {BufferEncoding}
+     */
+    static encoding: BufferEncoding;
+    /**
+     * @description
+     * - setup `vivth `preffered encoding;
+     * @param {Object} arg0
+     * @param {typeof Preferrence["encoding"]} arg0.encoding
+     * @example
+     * import { Preferrence } from 'vivth/neutral';
+     *
+     * Preferrence.setup({ encoding: 'utf-8' });
+     */
+    static setup: ({ encoding }: {
+        encoding: (typeof Preferrence)["encoding"];
+    }) => void;
+}

package/{types → generated/types}/src/common/Trace.d.mts

@@ -7,7 +7,7 @@
  * @param {number} traceIndex
  * @returns {string}
  * @example
- * import { Trace, Console } from 'vivth';
+ * import { Trace, Console } from 'vivth/neutral';
  *
  * Console.log(Trace(3)); // "D://test.mjs:3:13"
  */

package/{types → generated/types}/src/common/TracePath.d.mts

@@ -11,7 +11,7 @@
  * - if return false, continue to check the stacks;
  * @returns {string|undefined}
  * @example
- * import { TracePath, Console } from 'vivth';
+ * import { TracePath, Console } from 'vivth/neutral';
  *
  * Console.log(
  * 	TracePath((stackString) => {

package/generated/types/src/common/VivthUnBundledCodeBlock.d.mts

@@ -0,0 +1,6 @@
+/**
+ * @description
+ * - string typehinting value for unbundled only code;
+ * @type {'vivthUnBundledCodeBlock'}
+ */
+export const VivthUnBundledCodeBlock: "vivthUnBundledCodeBlock";