vivth 1.1.0 → 1.1.2

package/README.md

@@ -846,9 +846,18 @@ npm i vivth
 /**
  * @param {Object} options 	 
  * @param {string} options.root 	 
- * - browser: location.origin 	 
- * - node/bun compatible: process?.env?.INIT_CWD ?? process?.cwd(); 	 
- * - deno: Deno.env.get("INIT_CWD") ?? Deno.cwd(); need for `deno run --allow-env --allow-read your_script.ts` 	 
+ * - browser: 	 
+ * ```js 	 
+ * location.origin 	 
+ * ``` 	 
+ * - node/bun compatible: 	 
+ * ```js 	 
+ * process?.env?.INIT_CWD ?? process?.cwd() 	 
+ * ``` 	 
+ * - deno: need for `deno run --allow-env --allow-read your_script.ts`: 	 
+ * ```js 	 
+ * Deno.env.get("INIT_CWD") ?? Deno.cwd() 	 
+ * ``` 	 
  * - other: you need to check your JSRuntime for the rootPath reference; 	 
  */
 ```
@@ -1031,7 +1040,7 @@ npm i vivth
 
 ```js
 /**
- * @template {[string, ...string[]]} ExitEventNames
+ * @template {[string, ...string[]]} eventNames
  */
 ```
 
@@ -1050,8 +1059,8 @@ npm i vivth
 ```js
 /**
  * @param {Object} options 	 
- * @param {ExitEventNames} options.exitEventNames 	 
- * @param {()=>void} options.exitCallback 	 
+ * @param {eventNames} options.eventNames 	 
+ * @param {()=>void} options.terminator 	 
  * - standard node/bun: 	 
  * ```js 	 
  * () => process.exit(0), 	 
@@ -1060,7 +1069,7 @@ npm i vivth
  * ```js 	 
  * () => Deno.exit(0), 	 
  * ``` 	 
- * @param {(eventName:string)=>void} [options.exitCallbackListeners] 	 
+ * @param {(eventName:string)=>void} [options.listener] 	 
  * - default value 	 
  * ```js 	 
  * (eventName) => { 	 
@@ -1078,12 +1087,12 @@ npm i vivth
  import { SafeExit, Console } from 'vivth'; 	 
  	 
  new SafeExit({ 	 
- 	// exitEventNames are blank by default, you need to manually name them all; 	 
+ 	// eventNames are blank by default, you need to manually name them all; 	 
  	// 'exit' will be omited, as it might cause async callbacks failed to execute; 	 
- 	exitEventNames: ['SIGINT', 'SIGTERM', ...otherExitEventNames], 	 
- 	exitCallback = () => process.exit(0), // OR on deno () => Deno.exit(0), 	 
+ 	eventNames: ['SIGINT', 'SIGTERM', ...eventNames], 	 
+ 	terminator = () => process.exit(0), // OR on deno () => Deno.exit(0), 	 
  	// optional deno example 	 
- 	exitCallbackListeners = (eventName) => { 	 
+ 	listener = (eventName) => { 	 
  		const sig = Deno.signal(eventName); 	 
  			for await (const _ of sig) { 	 
  				exiting.correction(true); 	 
@@ -1142,15 +1151,17 @@ npm i vivth
  import { Setup, Console } from 'vivth'; 	 
  	 
  new Setup.safeExit({ 	 
- 	// exitEventNames are blank by default, you need to manually name them all; 	 
- 	exitEventNames: ['SIGINT', 'SIGTERM', ...otherExitEventNames], 	 
+ 	// eventNames are blank by default, you need to manually name them all; 	 
+ 	// 'exit' will be omited, as it might cause async callbacks failed to execute; 	 
+ 	eventNames: ['SIGINT', 'SIGTERM', ...eventNames], 	 
+ 	terminator = () => process.exit(0), // OR on deno () => Deno.exit(0), 	 
  	// optional deno example 	 
- 	exitCallbackListeners = (eventName) => { 	 
+ 	listener = (eventName) => { 	 
  		const sig = Deno.signal(eventName); 	 
  			for await (const _ of sig) { 	 
- 				SafeExit.instance.exiting.correction(true); 	 
+ 				exiting.correction(true); 	 
  				sig.dispose(); 	 
- 				Console.info(`safe exit via "${eventName}"`); 	 
+ 				Console.log(`safe exit via "${eventName}"`); 	 
  			} 	 
  	} 	 
  });
@@ -1199,7 +1210,7 @@ npm i vivth
 ```js  
  import { Setup } from 'vivth'; 	 
  	 
- Setup.workerThread({ parentPort: async () => await import('node:worker_threads') }); 	 
+ Setup.workerThread({ 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;
  
@@ -1380,12 +1391,18 @@ npm i vivth
 /**
  * @param {Object} param0 	 
  * @param {typeof WorkerMainThread["workerClass"]} param0.workerClass 	 
+ * - example: 	 
+ * ```js 	 
+ * async () => await (import('worker_threads')).Worker 	 
+ * ``` 	 
  * @param {typeof WorkerMainThread["pathValidator"]} param0.pathValidator 	 
+ * - example: 	 
  * ```js 	 
- *	async(relativePath) => { 	 
- *		// verify whether relativePath exist, then return the full path 	 
- *		// use fetch | fs, chained with Paths.instance.root + WorkerMainThread.basePath; 	 
- *	} 	 
+ * async (workerPath, root, base) => { 	 
+ * 	const res = await fetch(`${root}/${base}/${workerPath}`); 	 
+ * 	// might also check wheter it need base or not 	 
+ * 	return await res.ok; 	 
+ * } 	 
  * ``` 	 
  * @param {typeof WorkerMainThread["basePath"]} [param0.basePath] 	 
  * - additonal realtivePath from rootPath; 	 
@@ -1573,7 +1590,10 @@ npm i vivth
  * @template Receive_ 	 
  * @template Post_ 	 
  * @param {{parentPort:()=>Promise<any>}} parentPortRef 	 
- * - correct parentPort reference; 	 
+ * - correct parentPort reference, example: 	 
+ * ```js 	 
+ * async () => (await import('node:worker_threads')).parentPort 	 
+ * ``` 	 
  * @returns {typeof WorkerThread<Receive_, Post_>} 	 
  */
 ```
@@ -1581,7 +1601,7 @@ npm i vivth
 ```js  
  import { WorkerThread } from 'vivth'; 	 
  	 
- WorkerThread.setup({ parentPort: async () => await import('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;
  

package/dev/index.mjs

@@ -11,9 +11,9 @@ new paths({
 });
 
 new safeExit({
-	exitEventNames: ['SIGINT', 'SIGTERM', 'exit'],
-	exitCallback: () => process.exit(0),
-	exitCallbackListeners: (eventName) => {
+	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}"`);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "vivth",
-	"version": "1.1.0",
+	"version": "1.1.2",
 	"description": "extremely simple signal as library primitives",
 	"main": "index.mjs",
 	"types": "./types/index.d.mts",

package/src/class/Paths.mjs

@@ -16,9 +16,18 @@ export class Paths {
 	 * @description
 	 * @param {Object} options
 	 * @param {string} options.root
-	 * - browser: location.origin
-	 * - node/bun compatible: process?.env?.INIT_CWD ?? process?.cwd();
-	 * - deno: Deno.env.get("INIT_CWD") ?? Deno.cwd(); need for `deno run --allow-env --allow-read your_script.ts`
+	 * - browser:
+	 * ```js
+	 * location.origin
+	 * ```
+	 * - node/bun compatible:
+	 * ```js
+	 * process?.env?.INIT_CWD ?? process?.cwd()
+	 * ```
+	 * - deno: need for `deno run --allow-env --allow-read your_script.ts`:
+	 * ```js
+	 * Deno.env.get("INIT_CWD") ?? Deno.cwd()
+	 * ```
 	 * - other: you need to check your JSRuntime for the rootPath reference;
 	 * @example
 	 * import { Paths } from 'vivth';

package/src/class/SafeExit.mjs

@@ -15,7 +15,7 @@ export const safeCleanUpCBs = new Set();
  * @description
  * - class helper for describing how to Safely Response on exit events
  * - singleton;
- * @template {[string, ...string[]]} ExitEventNames
+ * @template {[string, ...string[]]} eventNames
  */
 export class SafeExit {
 	/**
@@ -27,8 +27,8 @@ export class SafeExit {
 	/**
 	 * @description
 	 * @param {Object} options
-	 * @param {ExitEventNames} options.exitEventNames
-	 * @param {()=>void} options.exitCallback
+	 * @param {eventNames} options.eventNames
+	 * @param {()=>void} options.terminator
 	 * - standard node/bun:
 	 * ```js
 	 * () => process.exit(0),
@@ -37,7 +37,7 @@ export class SafeExit {
 	 * ```js
 	 * () => Deno.exit(0),
 	 * ```
-	 * @param {(eventName:string)=>void} [options.exitCallbackListeners]
+	 * @param {(eventName:string)=>void} [options.listener]
 	 * - default value
 	 * ```js
 	 * (eventName) => {
@@ -52,12 +52,12 @@ export class SafeExit {
 	 * import { SafeExit, Console } from 'vivth';
 	 *
 	 * new SafeExit({
-	 * 	// exitEventNames are blank by default, you need to manually name them all;
+	 * 	// eventNames are blank by default, you need to manually name them all;
 	 * 	// 'exit' will be omited, as it might cause async callbacks failed to execute;
-	 * 	exitEventNames: ['SIGINT', 'SIGTERM', ...otherExitEventNames],
-	 * 	exitCallback = () => process.exit(0), // OR on deno () => Deno.exit(0),
+	 * 	eventNames: ['SIGINT', 'SIGTERM', ...eventNames],
+	 * 	terminator = () => process.exit(0), // OR on deno () => Deno.exit(0),
 	 * 	// optional deno example
-	 * 	exitCallbackListeners = (eventName) => {
+	 * 	listener = (eventName) => {
 	 * 		const sig = Deno.signal(eventName);
 	 * 			for await (const _ of sig) {
 	 * 				exiting.correction(true);
@@ -67,16 +67,16 @@ export class SafeExit {
 	 * 	}
 	 * });
 	 */
-	constructor({ exitEventNames, exitCallback, exitCallbackListeners = undefined }) {
+	constructor({ eventNames, terminator, listener = undefined }) {
 		if (SafeExit.instance) {
 			return SafeExit.instance;
 		}
 		SafeExit.instance = this;
-		this.#exit = exitCallback;
-		if (exitCallbackListeners) {
-			this.#exitCallbackListeners = exitCallbackListeners;
+		this.#exit = terminator;
+		if (listener) {
+			this.#listener = listener;
 		}
-		this.#register(exitEventNames);
+		this.#register(eventNames);
 	}
 	/**
 	 * @description
@@ -86,21 +86,21 @@ export class SafeExit {
 	 */
 	exiting = new EnvSignal(false);
 	/**
-	 * @param {ExitEventNames} exitEventNames
+	 * @param {eventNames} eventNames
 	 * @returns {void}
 	 */
-	#register = (exitEventNames) => {
-		exitEventNames.forEach((eventName) => {
+	#register = (eventNames) => {
+		eventNames.forEach((eventName) => {
 			if (eventName == 'exit') {
 				return;
 			}
-			this.#exitCallbackListeners(eventName);
+			this.#listener(eventName);
 		});
 	};
 	/**
 	 * @type {(eventName:string)=>void}
 	 */
-	#exitCallbackListeners = (eventName) => {
+	#listener = (eventName) => {
 		SafeExit.instance.exiting.env.value;
 		process.once(eventName, function () {
 			Console.log(`safe exit via "${eventName}"`);

package/src/class/Setup.mjs

@@ -17,15 +17,17 @@ export class Setup {
 	 * import { Setup, Console } from 'vivth';
 	 *
 	 * new Setup.safeExit({
-	 * 	// exitEventNames are blank by default, you need to manually name them all;
-	 * 	exitEventNames: ['SIGINT', 'SIGTERM', ...otherExitEventNames],
+	 * 	// eventNames are blank by default, you need to manually name them all;
+	 * 	// 'exit' will be omited, as it might cause async callbacks failed to execute;
+	 * 	eventNames: ['SIGINT', 'SIGTERM', ...eventNames],
+	 * 	terminator = () => process.exit(0), // OR on deno () => Deno.exit(0),
 	 * 	// optional deno example
-	 * 	exitCallbackListeners = (eventName) => {
+	 * 	listener = (eventName) => {
 	 * 		const sig = Deno.signal(eventName);
 	 * 			for await (const _ of sig) {
-	 * 				SafeExit.instance.exiting.correction(true);
+	 * 				exiting.correction(true);
 	 * 				sig.dispose();
-	 * 				Console.info(`safe exit via "${eventName}"`);
+	 * 				Console.log(`safe exit via "${eventName}"`);
 	 * 			}
 	 * 	}
 	 * });
@@ -65,7 +67,7 @@ export class Setup {
 	 * @example
 	 * import { Setup } from 'vivth';
 	 *
-	 * Setup.workerThread({ parentPort: async () => await import('node:worker_threads') });
+	 * Setup.workerThread({ 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;
 	 */

package/src/class/WorkerMainThread.mjs

@@ -31,12 +31,18 @@ export class WorkerMainThread {
 	 * - need to be called first, before any `WorkerMainThread` instantiation:
 	 * @param {Object} param0
 	 * @param {typeof WorkerMainThread["workerClass"]} param0.workerClass
+	 * - example:
+	 * ```js
+	 * async () => await (import('worker_threads')).Worker
+	 * ```
 	 * @param {typeof WorkerMainThread["pathValidator"]} param0.pathValidator
+	 * - example:
 	 * ```js
-	 *	async(relativePath) => {
-	 *		// verify whether relativePath exist, then return the full path
-	 *		// use fetch | fs, chained with Paths.instance.root + WorkerMainThread.basePath;
-	 *	}
+	 * async (workerPath, root, base) => {
+	 * 	const res = await fetch(`${root}/${base}/${workerPath}`);
+	 * 	// might also check wheter it need base or not
+	 * 	return await res.ok;
+	 * }
 	 * ```
 	 * @param {typeof WorkerMainThread["basePath"]} [param0.basePath]
 	 * - additonal realtivePath from rootPath;

package/src/class/WorkerThread.mjs

@@ -28,12 +28,15 @@ export class WorkerThread {
 	 * @template Receive_
 	 * @template Post_
 	 * @param {{parentPort:()=>Promise<any>}} parentPortRef
-	 * - correct parentPort reference;
+	 * - correct parentPort reference, example:
+	 * ```js
+	 * async () => (await import('node:worker_threads')).parentPort
+	 * ```
 	 * @returns {typeof WorkerThread<Receive_, Post_>}
 	 * @example
 	 * import { WorkerThread } from 'vivth';
 	 *
-	 * WorkerThread.setup({ parentPort: async () => await import('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;
 	 */

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

@@ -32,9 +32,18 @@ export class Paths {
      * @description
      * @param {Object} options
      * @param {string} options.root
-     * - browser: location.origin
-     * - node/bun compatible: process?.env?.INIT_CWD ?? process?.cwd();
-     * - deno: Deno.env.get("INIT_CWD") ?? Deno.cwd(); need for `deno run --allow-env --allow-read your_script.ts`
+     * - browser:
+     * ```js
+     * location.origin
+     * ```
+     * - node/bun compatible:
+     * ```js
+     * process?.env?.INIT_CWD ?? process?.cwd()
+     * ```
+     * - deno: need for `deno run --allow-env --allow-read your_script.ts`:
+     * ```js
+     * Deno.env.get("INIT_CWD") ?? Deno.cwd()
+     * ```
      * - other: you need to check your JSRuntime for the rootPath reference;
      * @example
      * import { Paths } from 'vivth';

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

@@ -6,9 +6,9 @@ export const safeCleanUpCBs: Set<() => Promise<void>>;
  * @description
  * - class helper for describing how to Safely Response on exit events
  * - singleton;
- * @template {[string, ...string[]]} ExitEventNames
+ * @template {[string, ...string[]]} eventNames
  */
-export class SafeExit<ExitEventNames extends [string, ...string[]]> {
+export class SafeExit<eventNames extends [string, ...string[]]> {
     /**
      * @description
      * - only accessible after instantiation;
@@ -18,8 +18,8 @@ export class SafeExit<ExitEventNames extends [string, ...string[]]> {
     /**
      * @description
      * @param {Object} options
-     * @param {ExitEventNames} options.exitEventNames
-     * @param {()=>void} options.exitCallback
+     * @param {eventNames} options.eventNames
+     * @param {()=>void} options.terminator
      * - standard node/bun:
      * ```js
      * () => process.exit(0),
@@ -28,7 +28,7 @@ export class SafeExit<ExitEventNames extends [string, ...string[]]> {
      * ```js
      * () => Deno.exit(0),
      * ```
-     * @param {(eventName:string)=>void} [options.exitCallbackListeners]
+     * @param {(eventName:string)=>void} [options.listener]
      * - default value
      * ```js
      * (eventName) => {
@@ -43,12 +43,12 @@ export class SafeExit<ExitEventNames extends [string, ...string[]]> {
      * import { SafeExit, Console } from 'vivth';
      *
      * new SafeExit({
-     * 	// exitEventNames are blank by default, you need to manually name them all;
+     * 	// eventNames are blank by default, you need to manually name them all;
      * 	// 'exit' will be omited, as it might cause async callbacks failed to execute;
-     * 	exitEventNames: ['SIGINT', 'SIGTERM', ...otherExitEventNames],
-     * 	exitCallback = () => process.exit(0), // OR on deno () => Deno.exit(0),
+     * 	eventNames: ['SIGINT', 'SIGTERM', ...eventNames],
+     * 	terminator = () => process.exit(0), // OR on deno () => Deno.exit(0),
      * 	// optional deno example
-     * 	exitCallbackListeners = (eventName) => {
+     * 	listener = (eventName) => {
      * 		const sig = Deno.signal(eventName);
      * 			for await (const _ of sig) {
      * 				exiting.correction(true);
@@ -58,10 +58,10 @@ export class SafeExit<ExitEventNames extends [string, ...string[]]> {
      * 	}
      * });
      */
-    constructor({ exitEventNames, exitCallback, exitCallbackListeners }: {
-        exitEventNames: ExitEventNames;
-        exitCallback: () => void;
-        exitCallbackListeners?: (eventName: string) => void;
+    constructor({ eventNames, terminator, listener }: {
+        eventNames: eventNames;
+        terminator: () => void;
+        listener?: (eventName: string) => void;
     });
     /**
      * @description

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

@@ -10,15 +10,17 @@ export class Setup {
      * import { Setup, Console } from 'vivth';
      *
      * new Setup.safeExit({
-     * 	// exitEventNames are blank by default, you need to manually name them all;
-     * 	exitEventNames: ['SIGINT', 'SIGTERM', ...otherExitEventNames],
+     * 	// eventNames are blank by default, you need to manually name them all;
+     * 	// 'exit' will be omited, as it might cause async callbacks failed to execute;
+     * 	eventNames: ['SIGINT', 'SIGTERM', ...eventNames],
+     * 	terminator = () => process.exit(0), // OR on deno () => Deno.exit(0),
      * 	// optional deno example
-     * 	exitCallbackListeners = (eventName) => {
+     * 	listener = (eventName) => {
      * 		const sig = Deno.signal(eventName);
      * 			for await (const _ of sig) {
-     * 				SafeExit.instance.exiting.correction(true);
+     * 				exiting.correction(true);
      * 				sig.dispose();
-     * 				Console.info(`safe exit via "${eventName}"`);
+     * 				Console.log(`safe exit via "${eventName}"`);
      * 			}
      * 	}
      * });
@@ -62,7 +64,7 @@ export class Setup {
      * @example
      * import { Setup } from 'vivth';
      *
-     * Setup.workerThread({ parentPort: async () => await import('node:worker_threads') });
+     * Setup.workerThread({ 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;
      */

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

@@ -17,12 +17,18 @@ export class WorkerMainThread<WT extends WorkerThread> {
      * - need to be called first, before any `WorkerMainThread` instantiation:
      * @param {Object} param0
      * @param {typeof WorkerMainThread["workerClass"]} param0.workerClass
+     * - example:
+     * ```js
+     * async () => await (import('worker_threads')).Worker
+     * ```
      * @param {typeof WorkerMainThread["pathValidator"]} param0.pathValidator
+     * - example:
      * ```js
-     *	async(relativePath) => {
-     *		// verify whether relativePath exist, then return the full path
-     *		// use fetch | fs, chained with Paths.instance.root + WorkerMainThread.basePath;
-     *	}
+     * async (workerPath, root, base) => {
+     * 	const res = await fetch(`${root}/${base}/${workerPath}`);
+     * 	// might also check wheter it need base or not
+     * 	return await res.ok;
+     * }
      * ```
      * @param {typeof WorkerMainThread["basePath"]} [param0.basePath]
      * - additonal realtivePath from rootPath;

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

@@ -17,12 +17,15 @@ export class WorkerThread<Receive, Post> {
      * @template Receive_
      * @template Post_
      * @param {{parentPort:()=>Promise<any>}} parentPortRef
-     * - correct parentPort reference;
+     * - correct parentPort reference, example:
+     * ```js
+     * async () => (await import('node:worker_threads')).parentPort
+     * ```
      * @returns {typeof WorkerThread<Receive_, Post_>}
      * @example
      * import { WorkerThread } from 'vivth';
      *
-     * WorkerThread.setup({ parentPort: async () => await import('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;
      */