vivth 1.1.2 → 1.2.0

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

@@ -25,6 +25,7 @@ export class parsedFile {
      * @param {BufferEncoding} [encoding]
      */
     constructor(path__: string, encoding?: BufferEncoding);
+    parse: () => Promise<void>;
     documented: {
         typedef: () => Promise<{
             module: string;
@@ -49,7 +50,30 @@ export class parsedFile {
             reference: string;
         }>;
     } & {
-        "vivth:unwrapLazy;": string;
+        "vivth:unwrapLazy;": () => {
+            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;
+            }>;
+        };
     };
     /**
      * @type {undefined|{module:string, readme:string}}
@@ -69,45 +93,63 @@ export class parsedFile {
     isDirectory: () => Promise<boolean>;
     baseName: {
         /**
-         * @type {string}
+         * @returns {string}
          */
         readonly withExt: string;
         /**
-         * @type {string}
+         * @returns {string}
          */
         readonly noExt: string;
     } & {
-        "vivth:unwrapLazy;": string;
+        "vivth:unwrapLazy;": () => {
+            /**
+             * @returns {string}
+             */
+            readonly withExt: string;
+            /**
+             * @returns {string}
+             */
+            readonly noExt: string;
+        };
     };
     path: {
         /**
-         * @type {string}
+         * @returns {string}
          */
         readonly relative: string;
         /**
-         * @type {string}
+         * @returns {string}
          */
         readonly full: string;
     } & {
-        "vivth:unwrapLazy;": string;
+        "vivth:unwrapLazy;": () => {
+            /**
+             * @returns {string}
+             */
+            readonly relative: string;
+            /**
+             * @returns {string}
+             */
+            readonly full: string;
+        };
     };
     get dirName(): {
         /**
-         * @type {string}
+         * @returns {string}
          */
         readonly relative: string;
         /**
-         * @type {string}
+         * @returns {string}
          */
         readonly full: string;
     };
     get ext(): {
         /**
-         * @type {string|undefined}
+         * @returns {string|undefined}
          */
         readonly withDot: string | undefined;
         /**
-         * @type {string|undefined}
+         * @returns {string|undefined}
          */
         readonly noDot: string | undefined;
     };
@@ -144,10 +186,27 @@ export class parsedFile {
             error: undefined;
         }>;
     } & {
-        "vivth:unwrapLazy;": string;
+        "vivth:unwrapLazy;": () => {
+            /**
+             * @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;
+            }>;
+        };
     };
     /**
-     * @type {[Promise<any>, undefined]|[undefined, Error]}
+     * @returns {[Promise<any>, undefined]|[undefined, Error]}
      */
     get importAsModuleJS(): [Promise<any>, undefined] | [undefined, Error];
     #private;

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

@@ -1,3 +1,28 @@
-export function CreateImmutable<P extends unknown, O extends unknown>(parent: P, keyName: string, object: (this: P) => O, { lazy }?: {
+/**
+ * @description
+ * - function for create immutable object;
+ * - usefull for binding immutable object to global for shared object:
+ * >- e.g. to window object in browser;
+ * @template {Object} PARENT
+ * @template {Object} OBJECT
+ * @param {string} keyName
+ * @param {PARENT} parent
+ * @param {(this:PARENT)=>OBJECT} object
+ * @param {Object} [options]
+ * @param {boolean} [options.lazy]
+ * @return {OBJECT}
+ * @example
+ * import { CreateImmutable } from 'vivth';
+ *
+ * const mappedObject = new Map();
+ *
+ * CreateImmutable(window, 'mySharedObject', {
+ * 	setMap(name_, value) => {
+ * 		mappedObject.set(name_, value)
+ * 	},
+ * 	getMap(name_) => mappedObject.get(name_),
+ * })
+ */
+export function CreateImmutable<PARENT extends unknown, OBJECT extends unknown>(parent: PARENT, keyName: string, object: (this: PARENT) => OBJECT, { lazy }?: {
     lazy?: boolean;
-}): O;
+}): OBJECT;

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

@@ -1,2 +1,17 @@
+/**
+ * @description
+ * - simple validation function for [EventObject](#eventobject), for multiple context, eg: `mainThread` <-> `workerThread`;
+ * @param {any} object
+ * @param {Record<typeof EventNameSpace, string>} eventObject
+ * @returns {boolean}
+ * @example
+ * import { EventCheck } from 'vivth';
+ * import { incomingMessage } from './some/where.mjs';
+ *
+ * const eventObjectPayload = EventObject('worker:exit');
+ * // assuming `incomingMessage`, also created using EventObject('worker:exit');
+ * // or manually {[EventNameSpace]:'worker:exit'};
+ * // which either will result true;
+ */
 export function EventCheck(object: any, eventObject: Record<typeof EventNameSpace, string>): boolean;
 import { EventNameSpace } from '../common/EventNameSpace.mjs';

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

@@ -1,4 +1,19 @@
-export function EventObject<N extends string>(name: N): {
-    [EventNameSpace]: N;
+/**
+ * @description
+ * - simple object generation function helper for [EventCheck](#eventcheck), for multiple context, eg: `mainThread` <-> `workerThread`;
+ * @template {string} NAME
+ * @param {NAME} name
+ * @returns {{[EventNameSpace]: NAME}}
+ * @example
+ * import { EventCheck } from 'vivth';
+ * import { incomingMessage } from './some/where.mjs';
+ *
+ * const eventObjectPayload = EventObject('worker:exit');
+ * // assuming `incomingMessage`, also created using EventObject('worker:exit');
+ * // or manually {[EventNameSpace]:'worker:exit'};
+ * // which either will result true;
+ */
+export function EventObject<NAME extends string>(name: NAME): {
+    [EventNameSpace]: NAME;
 };
 import { EventNameSpace } from '../common/EventNameSpace.mjs';

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

@@ -0,0 +1,2 @@
+export function GetRuntime(): Runtime;
+export type Runtime = import("../types/Runtime.mjs").Runtime;

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

@@ -1 +1,19 @@
+/**
+ * @description
+ * - function helper for checking whether `functionReference` is async;
+ * @param {(...any:any)=>(any|Promise<any>)} functionReference
+ * @returns {boolean}
+ * @example
+ * import { IsAsync } from 'vivth';
+ *
+ * const a = function (params) {
+ * 	// code
+ * }
+ * const b = async () => {
+ * 	// code
+ * }
+ *
+ * IsAsync(a); // false
+ * IsAsync(b); // true
+ */
 export function IsAsync(functionReference: (...any: any) => (any | Promise<any>)): boolean;

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

@@ -1,4 +1,37 @@
-export function LazyFactory<T>(factory: () => T): T & {
-    [unwrapLazy]: string;
+/**
+ * @description
+ * - function helper for creating lazyObject:
+ * >- usefull for lazily instantiating an object, since instance naturally have props/methods;
+ * @template FACTORY
+ * @param {() => FACTORY} factory
+ * @returns {FACTORY & {[unwrapLazy]: ()=> FACTORY}}
+ * - the unwrapLazy prop can be accessed to force instatiation/call;
+ * >- `unwrapLazy` prop name can be checked by checking the list of possible prop, from your ide;
+ * >- as of version `1.0.0`, value is `vivth:unwrapLazy;`;
+ * @example
+ * import { LazyFactory } from  'vivth';
+ *
+ * class MyClass{
+ *    constructor() {
+ *      this.myProp = 1; // will only available when accessed;
+ *    }
+ * }
+ *
+ * export const myInstance = LazyFactory(() => {
+ *		// the instance of MyClass will only be available when,
+ *		// it's prop, or method is accessed/reassign;
+ *		return new MyClass();
+ * });
+ *
+ * // on other file
+ * import { myInstance } from './myInstance.mjs';
+ *
+ * const a = myInstance; // not yet initiated;
+ * const b = a.myProp // imediately initiated;
+ * // OR
+ * myInstance["vivth:unwrapLazy;"]() // forcefully call the callback;
+ */
+export function LazyFactory<FACTORY>(factory: () => FACTORY): FACTORY & {
+    [unwrapLazy]: () => FACTORY;
 };
 import { unwrapLazy } from '../common/lazie.mjs';

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

@@ -1 +1,17 @@
+/**
+ * @description
+ * - function helper to temporarily block the code in async context;
+ * @param {number} timeMS
+ * - in miliseconds;
+ * @returns {Promise<void>}
+ * @example
+ * import { Timeout } from 'vivth';
+ *
+ * const test = async () => {
+ *   // code0
+ *   await Timeout(1000);
+ *   // code1
+ * }
+ * test();
+ */
 export function Timeout(timeMS: number): Promise<void>;

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

@@ -1 +1,52 @@
-export function Try<Key extends string, ReturnType_, RecordTryType extends Record<Key, () => Promise<ReturnType_>>>(tryRecord: RecordTryType): Promise<[[keyof RecordTryType, ReturnType_], undefined] | [[undefined, undefined], Error]>;
+/**
+ * @description
+ * - function for error as value for chained operations;
+ * - utility function to brute force which key is able to run;
+ * - usefull to flatten indentation for error handlings;
+ * - caveat:
+ * >- run in sequence, awaiting each key bofore running next key;
+ * @template {string} KEY
+ * @template RETURNTYPE
+ * @template {Record<
+ * 	KEY,
+ * 	(err:{prevError:undefined|Error}) => Promise<RETURNTYPE>
+ * >} RecordTryType
+ * @param {RecordTryType} tryRecord
+ * @returns {Promise<
+ * 	[[keyof RecordTryType, RETURNTYPE], undefined]
+ * 	| [[undefined, undefined], Error]
+ * >}
+ * @example
+ * import { Try } from 'vivth';
+ *
+ * const [[key, result], error] = await Try({
+ * 	someRuntime: async ( prevError ) => {
+ * 		// asuming on this one doesn't naturally throw error,
+ * 		// yet you need to continue to next key,
+ * 		// instead of returning,
+ * 		// you should throw new Error(something);
+ * 	},
+ * 	browser: async ( prevError ) => {
+ * 		return location?.origin;
+ * 		// if no error, stop other key function from running;
+ * 		// key = 'browser'
+ * 		// result = location?.origin;
+ * 		// error = undefined;
+ * 		// if error;
+ * 		// run nodeOrBun;
+ * 	},
+ * 	nodeOrBun: async ( prevError ) => {
+ * 		return process?.env?.INIT_CWD ?? process?.cwd();
+ * 		// if no error;
+ * 		// key = 'nodeOrBun'
+ * 		// result =  process?.env?.INIT_CWD ?? process?.cwd();
+ * 		// if error;
+ * 		// key = undefined;
+ * 		// result = undefined;
+ * 		// error = new Error('unable to run any key');
+ * 	},
+ * });
+ */
+export function Try<KEY extends string, RETURNTYPE, RecordTryType extends Record<KEY, (err: {
+    prevError: undefined | Error;
+}) => Promise<RETURNTYPE>>>(tryRecord: RecordTryType): Promise<[[keyof RecordTryType, RETURNTYPE], undefined] | [[undefined, undefined], Error]>;

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

@@ -1 +1,22 @@
-export function TryAsync<ResultType>(asyncFunction_: () => Promise<ResultType>): Promise<[ResultType | undefined, Error | undefined]>;
+/**
+ * @description
+ * - function for error as value for asynchronous operation;
+ * - usefull to flatten indentation for error handlings;
+ * @template RESULT
+ * @param {()=>Promise<RESULT>} asyncFunction_
+ * @returns {Promise<[RESULT|undefined, Error|undefined]>}
+ * @example
+ * import { TryAsync } from 'vivth';
+ *
+ * let [res, error] = await TryAsync(async () => {
+ * 	return await fetch('./someAPI/Path');
+ * });
+ *
+ * [res, error] = await TryAsync(async () => {
+ * 	if(!res.ok) {
+ * 		throw new Error(404);
+ * 	}
+ * 	return await res.json();
+ * })
+ */
+export function TryAsync<RESULT>(asyncFunction_: () => Promise<RESULT>): Promise<[RESULT | undefined, Error | undefined]>;

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

@@ -1 +1,16 @@
-export function TrySync<ResultType>(function_: () => ResultType): [ResultType | undefined, Error | undefined];
+/**
+ * @description
+ * - function for error as value for synchronous operation;
+ * - usefull to flatten indentation for error handlings;
+ * @template RESULT
+ * @param {()=>RESULT} function_
+ * @returns {[RESULT|undefined, Error|undefined]}
+ * @example
+ * import { readFileSync } from 'fs';
+ * import { TrySync } from './yourModule.js';
+ *
+ * const [data, error] = TrySync(() => {
+ * 	return readFileSync('./some/file.txt', 'utf-8');
+ * });
+ */
+export function TrySync<RESULT>(function_: () => RESULT): [RESULT | undefined, Error | undefined];

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

@@ -1,3 +1,22 @@
+/**
+ * @description
+ * - turn `.mts`||`.ts` file into `.mjs`, no bundling, just translation;
+ * - on certain circumstance where `.mjs` result needed to be typed, you need to manually add `jsdoc`;
+ * >- uses `"at"preserve` to register `jsdoc` inline;
+ * @param {string} path_
+ * - path from `Paths.root`;
+ * @param {Object} [options]
+ * @param {string} [options.overrideDir]
+ * - default: write conversion to same directory;
+ * - path are relative to project root;
+ * @param {BufferEncoding} [options.encoding]
+ * - default: `utf-8`;
+ * @returns {Promise<void>}
+ * @example
+ * import { TsToMjs } from 'vivth';
+ *
+ * TsToMjs('./myFile.mts', { encoding: 'utf-8', overrideDir: './other/dir' });
+ */
 export function TsToMjs(path_: string, { overrideDir, encoding }?: {
     overrideDir?: string;
     encoding?: BufferEncoding;

package/types/src/types/LitExpKeyType.d.mts

@@ -0,0 +1 @@
+export type LitExpKeyType = Record<string, RegExp | false>;

package/types/src/types/QCBReturn.d.mts

@@ -3,5 +3,5 @@
  */
 export type QCBReturn = {
     resume: () => void;
-    isLastOnQ: boolean;
+    isLastOnQ: () => boolean;
 };

package/types/src/types/Runtime.d.mts

@@ -0,0 +1 @@
+export type Runtime = "node" | "bun" | "deno" | "browser" | "unknown";

package/dev/index.mjs

@@ -1,28 +0,0 @@
-// @ts-check
-
-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({
-	eventNames: ['SIGINT', 'SIGTERM', 'exit'],
-	terminator: () => process.exit(0),
-	listener: (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',
-});

package/src/bundler/CompileMJS.mjs

@@ -1,110 +0,0 @@
-// @ts-check
-
-import { readFile } from 'node:fs/promises';
-import { join, extname } from 'node:path';
-
-import { Paths } from '../class/Paths.mjs';
-import { EsBundler } from './EsBundler.mjs';
-import { Console } from '../class/Console.mjs';
-import { WriteFileSafe } from '../function/WriteFileSafe.mjs';
-
-/**
- * @description
- * - function to bundle to single mjs file, including the workerThread;
- * @param {Object} options
- * @param {string} options.entryPoint
- * @param {string} options.outputNoExt
- * - no extention needed, result will always be '.mjs';
- * @param {BufferEncoding} options.encoding
- * @param {boolean} [options.minify]
- * - default false;
- * @param {boolean} [options.asBinary]
- * - default false;
- * @returns {Promise<ReturnType<typeof WriteFileSafe>>}
- * @example
- * import { Paths, CompileMJS } from 'vivth';
- *
- * new Paths({
- * 	root: process?.env?.INIT_CWD ?? process?.cwd(),
- * });
- *
- * CompileMJS({
- * 	entryPoint: '/index.mjs',
- * 	encoding: 'utf-8',
- * 	outputNoExt: '/test/compiled',
- * 	minify: false,
- * 	asBinary: true,
- * });
- */
-export const CompileMJS = async ({
-	entryPoint,
-	encoding,
-	outputNoExt,
-	minify = false,
-	asBinary = false,
-}) => {
-	const rootPath = Paths.root;
-	const fullpathEntry = join(rootPath, entryPoint);
-	const fulloutput = join(rootPath, `${outputNoExt}.mjs`);
-	const mainext = extname(fullpathEntry);
-	const [content, error] = await EsBundler(
-		{
-			content: await readFile(fullpathEntry, { encoding }),
-			extension: mainext,
-			asBinary: false,
-		},
-		{
-			minify: false,
-			keepNames: true,
-		}
-	);
-	if (error) {
-		Console.error(error);
-		return;
-	}
-	let strippedComment = content.replace(/\/\*\*[\s\S]*?\*\//gm, '');
-	const workersMatched = strippedComment
-		.matchAll(
-			/new\s(WorkerMainThread\w*?)\(['"]([\s\S]*?\.worker\.[\s\S]*?)['"][\s\S]*?(?:{([\s\S]*?)}|)[\s\S]*?\)/gm
-		)
-		.toArray();
-	/**
-	 * @type {Set<string>}
-	 */
-	const fileNames = new Set();
-	for (const [string, className, path_, options] of workersMatched) {
-		fileNames.add(path_);
-		const newComment = `new ${className}(vivthWorkerFilesObject["${path_}"], {${
-			options ?? ''
-		}}, true)`;
-		strippedComment = strippedComment.replace(string, newComment);
-	}
-	const vivthWorkerFilesObject = {};
-	for await (const path_ of fileNames) {
-		const workerFullPath = join(rootPath, path_);
-		const content = await readFile(workerFullPath, { encoding });
-		const [bundle, _] = await EsBundler(
-			{
-				content,
-				extension: extname(workerFullPath),
-			},
-			{
-				minify: true,
-			}
-		);
-		vivthWorkerFilesObject[path_] = bundle;
-	}
-	const [finalContent] = await EsBundler(
-		{
-			content: `const vivthWorkerFilesObject = ${JSON.stringify(
-				vivthWorkerFilesObject
-			)};\n${strippedComment}`,
-			extension: mainext,
-			asBinary,
-		},
-		{ minify }
-	);
-	return await WriteFileSafe(fulloutput, finalContent, {
-		encoding,
-	});
-};

package/src/function/WriteFileSafe.mjs

@@ -1,37 +0,0 @@
-// @ts-check
-
-import { writeFile, mkdir } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
-
-import { TryAsync } from './TryAsync.mjs';
-import { Paths } from '../class/Paths.mjs';
-
-/**
- * @description
- * - function to create file by recursively mkdir the dirname of the outFile;
- * - also returing promise of result & error as value;
- * @param {string} outFile
- * @param {string} content
- * @param {import('node:fs').WriteFileOptions} options
- * @returns {Promise<ReturnType<typeof TryAsync<void>>>}
- * @example
- * import { WriteFileSafe } from 'vivth';
- *
- * const [_, writeError] = await TryAsync(async () => {
- * 	return await WriteFileSafe(
- * 		'/some/path.mjs',
- * 		'console.log("hello-world!!");',
- * 		{ encoding: 'utf-8' }
- * 	);
- * });
- */
-export const WriteFileSafe = async (outFile, content, options) => {
-	return await TryAsync(async () => {
-		const rootPath = Paths.normalize(Paths.root);
-		if (!Paths.normalize(outFile).startsWith(rootPath)) {
-			outFile = join(rootPath, outFile);
-		}
-		await mkdir(dirname(outFile), { recursive: true });
-		return writeFile(outFile, content, options);
-	});
-};

package/types/src/bundler/A.d.mts

@@ -1 +0,0 @@
-export function A(entryPoint: string, encoding: BufferEncoding, output: string, minify?: boolean): Promise<void>;

package/types/src/bundler/CompileMJS.d.mts

@@ -1,8 +0,0 @@
-export function CompileMJS({ entryPoint, encoding, outputNoExt, minify, asBinary, }: {
-    entryPoint: string;
-    outputNoExt: string;
-    encoding: BufferEncoding;
-    minify?: boolean;
-    asBinary?: boolean;
-}): Promise<ReturnType<typeof WriteFileSafe>>;
-import { WriteFileSafe } from '../function/WriteFileSafe.mjs';

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

@@ -1,2 +0,0 @@
-export function WriteFileSafe(outFile: string, content: string, options: import("node:fs").WriteFileOptions): Promise<ReturnType<typeof TryAsync<void>>>;
-import { TryAsync } from './TryAsync.mjs';