vivth 1.4.9 → 1.5.0

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

@@ -1,103 +0,0 @@
-/**
- * @type {Set<()=>Promise<void>>}
- */
-export const safeCleanUpCBs: Set<() => Promise<void>>;
-/**
- * @description
- * - class helper for describing how to Safely Response on exit events
- * - singleton;
- * - most of functionality might need to access `SafeExit.instance.exiting`, if you get warning, you can instantiate `SafeExit` before running anything;
- */
-export class SafeExit {
-    /**
-     * @description
-     * - only accessible after instantiation;
-     * @type {SafeExit|undefined}
-     */
-    static instance: SafeExit | undefined;
-    /**
-     * @description
-     * @param {Object} options
-     * @param {[string, ...string[]]} options.eventNames
-     * - 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;
-     * - example:
-     * ```js
-     *  ['SIGINT', 'SIGTERM']
-     * ```
-     * @param {()=>void} options.terminator
-     * - standard, process must be imported statically from 'node:process':
-     * ```js
-     * () => process.exit(0),
-     * ```
-     * @param {(eventName:string)=>void} [options.listener]
-     * - default value
-     * ```js
-     * (eventName) => {
-     * 	process.once(eventName, function () {
-     * 		SafeExit.instance.exiting.correction(true);
-     * 		Console.log(`safe exit via "${eventName}"`);
-     * 	});
-     * }
-     * ```
-     * - if your exit callback doesn't uses `process` global object you need to input on the SafeExit instantiation
-     * @example
-     * import process from 'node:process';
-     * import { SafeExit, Console } from 'vivth';
-     *
-     * new SafeExit({
-     * 	eventNames: ['SIGINT', 'SIGTERM', ...eventNames],
-     * 	terminator : () => process.exit(0),
-     * 	listener : (eventName) => {
-     * 			process.once(eventName, function () {
-     * 				SafeExit.instance?.exiting.correction(true);
-     * 				Console.log(`safe exit via "${eventName}"`);
-     * 			});
-     * 	}
-     * });
-     */
-    constructor({ eventNames, terminator, listener }: {
-        eventNames: [string, ...string[]];
-        terminator: () => void;
-        listener?: ((eventName: string) => void) | undefined;
-    });
-    /**
-     * @description
-     * - optional exit event registration, by listening to it inside an `Effect`;
-     * - when the value is `true`, meaning program is exitting;
-     * @type {EnvSignal<boolean>}
-     */
-    exiting: EnvSignal<boolean>;
-    /**
-     * @description
-     * - optional exit event registration;
-     * - the callbacks will be called when exiting;
-     * @param {()=>(Promise<void>)} cb
-     * @example
-     * import { SafeExit } from 'vivth';
-     *
-     * const exitCallback () => {
-     * 	// code
-     * }
-     * SafeExit.instance.addCallback(exitCallback);
-     */
-    addCallback: (cb: () => (Promise<void>)) => void;
-    /**
-     * @description
-     * - optional exit event removal;
-     * - the callbacks will be removed from registered via `addCallback` exiting;
-     * @param {()=>(Promise<void>)} cb
-     * @example
-     * import { SafeExit } from 'vivth';
-     *
-     * const exitCallback () => {
-     * 	// code
-     * }
-     * SafeExit.instance.addCallback(exitCallback);
-     * // somewhere else
-     * SafeExit.instance.removeCallback(exitCallback);
-     */
-    removeCallback: (cb: () => (Promise<void>)) => void;
-    #private;
-}
-import { EnvSignal } from './EnvSignal.mjs';

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

@@ -1,83 +0,0 @@
-/**
- * @template POST
- * @typedef {import('./WorkerResult.mjs').WorkerResult<POST>} WorkerResult
- */
-/**
- * @template RECEIVE
- * @template POST
- * @typedef {import('./WorkerThread.mjs').WorkerThread<RECEIVE, POST>} WorkerThread
- */
-/**
- * @typedef {import('../common/lazie.mjs').unwrapLazy} unwrapLazy
- */
-/**
- * @template {WorkerThread<any, any>} WT
- */
-export class WorkerMainThread<WT extends WorkerThread<any, any>> {
-    /**
-     * @type {boolean}
-     */
-    static "__#private@#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 "__#private@#options": import("node:worker_threads").WorkerOptions & {
-        type?: "module";
-    };
-    /**
-     * @template {WorkerThread<any, any>} WT
-     * @param {string} handler
-     * @param {Omit<WorkerOptions|import('node:worker_threads').WorkerOptions, 'eval'|'type'>} [options]
-     * @returns {WorkerMainThread<WT>}
-     */
-    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
-     * @param { WorkerOptions
-     * | import('node:worker_threads').WorkerOptions} options
-     * @param {WorkerMainThread<WT>} worker
-     * @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>;
-    /**
-     * @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]);
-    /**
-     * @return {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<RECEIVE, POST> = import("./WorkerThread.mjs").WorkerThread<RECEIVE, POST>;
-export type unwrapLazy = "vivth:unwrapLazy;";
-import { Derived } from './Derived.mjs';

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

@@ -1,16 +0,0 @@
-/**
- * @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<string>}
- * @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<string>;

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

@@ -1,68 +0,0 @@
-/**
- * @typedef {import("../types/VivthDevCodeBlockStringType.mjs").VivthDevCodeBlockStringType} VivthDevCodeBlockStringType
- * @typedef {import('../types/DevTestCB.mjs').DevTestCB} DevTestCB
- */
-/**
- * @description
- * - class helper for `devTime` only code block;
- */
-export class Dev {
-    /**
-     * @description
-     * - persistent variable(during `devTime` and `bundled`);
-     * - can be used as `condition` for checking whether it is in `devTime` or `bundled`;
-     * @type {boolean}
-     * @example
-     * import { Dev } from 'vivth';
-     *
-     * if (Dev.isDev) {
-     * 	// this code block will presist even on `bundled`;
-     * }
-     */
-    static isDev: boolean;
-    /**
-     * @type {Signal<Map<string,Awaited<ReturnType<typeof TryAsync<boolean>>>>>}
-     */
-    static "__#private@#notifications": Signal<Map<string, Awaited<ReturnType<typeof TryAsync<boolean>>>>>;
-    /**
-     * @type {DevTestCB}
-     */
-    static "__#private@#test": DevTestCB;
-    static "__#private@#effectForCheck": Effect & {
-        "vivth:unwrapLazy;": () => Effect;
-    };
-    /**
-     * @description
-     * - to wrap `devTime` only code block;
-     * - when bundled uses `EsBundler` or esbuild with `ToBundledJSPlugin` plugin, the code block will be removed on the bundled version;
-     * @param {(options:{test:DevTestCB})=>Promise<void>} callback
-     * - also provide `test` method for inline testing:
-     * >- which is wrapped in `TryAsync`, throwed errors will automatically return `false`;
-     * @param {VivthDevCodeBlockStringType} _closing
-     * - it is needed to detect the code block closing;
-     * - should use single or double quote and not back tick;
-     * @returns {Promise<void>}
-     * @example
-     * import { Dev, Signal } from 'vivth';
-     *
-     * Dev.vivthDevCodeBlock(async function () {
-     * 	// this code block will be removed on `bundled` version;
-     * }, 'vivthDevCodeBlock');
-     *
-     * const numberSignal = new Signal(0);
-     * Dev.vivthDevCodeBlock(async ({ test }) => {
-     * 	// this code block will be removed on `bundled` version;
-     * 	const [{ removeId: removeTest }] = await Promise.all([
-     * 		test(async () => numberSignal.value === 0)
-     * 	])
-     * }, 'vivthDevCodeBlock');
-     */
-    static vivthDevCodeBlock: (callback: (options: {
-        test: DevTestCB;
-    }) => Promise<void>, _closing: VivthDevCodeBlockStringType) => Promise<void>;
-}
-export type VivthDevCodeBlockStringType = import("../types/VivthDevCodeBlockStringType.mjs").VivthDevCodeBlockStringType;
-export type DevTestCB = import("../types/DevTestCB.mjs").DevTestCB;
-import { Signal } from '../class/Signal.mjs';
-import { TryAsync } from '../function/TryAsync.mjs';
-import { Effect } from '../class/Effect.mjs';

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

@@ -1,3 +0,0 @@
-export class Dev {
-    static isDev: boolean;
-}

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

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

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

@@ -1,83 +0,0 @@
-/**
- * @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:
- * >- auto export must follows the following rules;
- * >1) add `"at"noautodoc` on self closing jsdoc comment to opt out from generating documentation on said file;
- * >2) will (generate) export all named exported 'const'|'function'|'async function'|'class', alphanumeric name, started with Capital letter, same name with fileName on `options.paths.file`;
- * >3) will (generate) 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.paths.file`;
- * >4) will (generate) create `README.md` based on, `options.paths.dir` and `README.src.md`;
- * >5) 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` documentation/generation results;
- * >6) this types of arrow functions will be converted to regullar function, for concise type emition, includes:
- * >>- validly exported function;
- * >>- static/instance method with generic template;
- * >7) transpile `.ts` and `.mts` to `.mjs` with same name and directory;
- * >>- use `"at"preserve` to preserve tsdoc comment section;
- */
-export class JSautoDOC {
-    /**
-     * @type {JSautoDOC|undefined}
-     */
-    static "__#private@#instance": JSautoDOC | undefined;
-    /**
-     * @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 { JSautoDOC } from 'vivth';
-     *
-     *  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;
-        } | undefined;
-        copyright?: string | undefined;
-        tableOfContentTitle?: string | undefined;
-        option?: Partial<{
-            persistent: boolean;
-            ignoreInitial: boolean;
-            followSymlinks: boolean;
-            cwd?: string;
-            usePolling: boolean;
-            interval: number;
-            binaryInterval: number;
-            alwaysStat?: boolean;
-            depth?: number;
-            ignorePermissionErrors: boolean;
-            atomic: boolean | number;
-        } & {
-            ignored: import("chokidar").Matcher | import("chokidar").Matcher[];
-            awaitWriteFinish: boolean | Partial<{
-                stabilityThreshold: number;
-                pollInterval: number;
-            }>;
-        }> | undefined;
-    });
-    #private;
-}
-export type Stats = import("fs").Stats;

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

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

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

@@ -1,22 +0,0 @@
-/**
- * @description
- * - function helper to create template literal with VALUEhandler to handle each values;
- * @template {(input:any)=>string|Promise<string>} VALUEHANDLER
- * @param {VALUEHANDLER} valueHandler
- * @param {(result:string)=>string} [postProcess]
- * @returns {(strings:TemplateStringsArray,
- * ...values:(Parameters<VALUEHANDLER>[0])[])=>
- * ReturnType<VALUEHANDLER>}
- * @example
- * import { TemplateLiteral } form 'vivth';
- *
- * export const html = TemplateLiteral(
- *  (val) => val,
- *  // optional
- *  (res) => return window.body.innerHTML = res
- * );
- *
- * html`<div>${`<button>innerButton</button>`}</div>`;
- * // this will set innerHTML of body to '<div><button>innerButton</button></div>'
- */
-export function TemplateLiteral<VALUEHANDLER extends (input: any) => string | Promise<string>>(valueHandler: VALUEHANDLER, postProcess?: (result: string) => string): (strings: TemplateStringsArray, ...values: (Parameters<VALUEHANDLER>[0])[]) => ReturnType<VALUEHANDLER>;

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

@@ -1,23 +0,0 @@
-/**
- * @description
- * - turn `.mts`||`.ts` file into `.mjs`, no bundling, just traspilation;
- * - on certain circumstance where `.mjs` result needed to be typed, you need to manually add `jsdoc`;
- * >- uses `"at"preserve` to register `jsdoc`;
- * @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';
- *
- * await TsToMjs('./myFile.mts', { encoding: 'utf-8', overrideDir: './other/dir' });
- */
-export function TsToMjs(path_: string, { overrideDir, encoding }?: {
-    overrideDir?: string | undefined;
-    encoding?: BufferEncoding | undefined;
-}): Promise<void>;

package/types/src/types/IsListSignal.d.mts

@@ -1,4 +0,0 @@
-/**
- * - `EnvSignal.get` argument whether signal need to be a list or not;
- */
-export type IsListSignal = boolean;

package/types/src/types/ListArg.d.mts

@@ -1,4 +0,0 @@
-/**
- * - ListSignal argument type;
- */
-export type ListArg = Record<string, string>;

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

@@ -1,4 +0,0 @@
-/**
- * - for popular runtimes check;
- */
-export type Runtime = "node" | "bun" | "deno" | "browser" | "unknown";

package/types/src/types/VivthDevCodeBlockStringType.d.mts

@@ -1,4 +0,0 @@
-/**
- * - closing helper for `Dev.vivthDevCodeBlock`;
- */
-export type VivthDevCodeBlockStringType = "vivthDevCodeBlock";