vivth 1.4.9 → 1.5.0

package/generated/types/src/function/IsInstanceOf.d.mts

@@ -0,0 +1,25 @@
+/**
+ * @description
+ * A type-safe `instanceof` helper.
+ * @template OBJ
+ * @param {unknown} obj - The object to test
+ * @param {new (...args: any[]) => OBJ} classRef - A constructor reference for T
+ * @returns {obj is OBJ}
+ * @example
+ * import { IsInstanceOf, Signal, Effect } from 'vivth/neutral';
+ *
+ * const a = new Signal(0);
+ * IsInstanceOf(a, Signal); // true
+ * IsInstanceOf(a, Effect); // false
+ *
+ * // but why not
+ * if(!(a instanceof Signal)){
+ *  //
+ * };
+ *
+ * // here's why
+ * if(!IsInstanceOf(a, Signal)){
+ *  //
+ * };
+ */
+export function IsInstanceOf<OBJ>(obj: unknown, classRef: new (...args: any[]) => OBJ): obj is OBJ;

package/generated/types/src/function/IsSameFile.d.mts

@@ -0,0 +1,16 @@
+/**
+ * @description
+ * - check if two path is the same file;
+ * @param {string} pathA
+ * @param {string} pathB
+ * @returns {boolean}
+ * @example
+ * // `D://myFile.mjs` cwd at `D://`
+ * import { IsSameFile } from "vivth/node";
+ *
+ * IsSameFile('D:\\mFile.mjs', 'D://mFile.mjs') // true;
+ * IsSameFile('//mFile.mjs', 'D://mFile.mjs') // true;
+ * // both path are auto resolved to Paths.root;
+ * IsSameFile('D:\\mFile.mjs', 'D:\\notmfile.mjs') // false;
+ */
+export function IsSameFile(pathA: string, pathB: string): boolean;

package/generated/types/src/function/IsStringLooksLikeAPath.d.mts

@@ -0,0 +1,16 @@
+/**
+ * @description
+ * - check if string lookslike a path;
+ * @param {string} spec
+ * @returns {boolean}
+ * @example
+ * import { IsStringLooksLikeAPath } from 'vivth/neutral';
+ *
+ * looksLikePath("./foo.mjs"); // true
+ * looksLikePath("../bar.ts"); // true
+ * looksLikePath("/usr/lib.js"); // true
+ * looksLikePath("C:\\lib\\mod"); // true
+ * looksLikePath("react"); // false
+ * looksLikePath("node:path"); // false
+ */
+export function IsStringLooksLikeAPath(spec: string): boolean;

package/generated/types/src/function/IsTypeOf.d.mts

@@ -0,0 +1,25 @@
+/**
+ * Map of 'typeof' string results to their actual TypeScript types.
+ * Using a constant object allows for type-safe extraction without
+ * manual conditional mapping.
+ */
+export declare const TypeMap: {
+    string: string;
+    number: number;
+    boolean: boolean;
+    object: {};
+    function: () => void;
+    undefined: undefined;
+    symbol: symbol;
+    bigint: bigint;
+};
+/**
+ * @preserve
+ * @description
+ * A type-safe `typeof` helper.
+ * @template {keyof typeof TypeMap} K
+ * @param {unknown} object - The value to check.
+ * @param {K} type - The type string to compare against.
+ * @returns {object is typeof TypeMap[K]} - Returns true if the type matches, narrowing the type.
+ */
+export declare function IsTypeOf<K extends keyof typeof TypeMap>(object: unknown, type: K): object is (typeof TypeMap)[K];

package/{types → generated/types}/src/function/LazyFactory.d.mts

@@ -4,12 +4,14 @@
  * >- 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;`;
+ * @returns {FACTORY & {[FactoryKey]: FACTORY}}
+ * - the FactoryKey prop can be accessed to force instatiation/call;
+ * - usefull for Object that has different accessor behaviour when being get via Proxy, including but not limited too:
+ * >- `Set<any>`;
+ * >- `Map<any, any>`;
+ * >- non referenced object, like `Effect`;
  * @example
- * import { LazyFactory } from  'vivth';
+ * import { LazyFactory, FactoryKey } from 'vivth/neutral';
  *
  * class MyClass{
  *    constructor() {
@@ -29,9 +31,6 @@
  * const a = myInstance; // not yet initiated;
  * const b = a.myProp // imediately initiated;
  * // OR
- * myInstance["vivth:unwrapLazy;"]() // forcefully call factory generator;
+ * myInstance[FactoryKey] // forcefully call factory generator;
  */
-export function LazyFactory<FACTORY>(factory: () => FACTORY): FACTORY & {
-    [unwrapLazy]: () => FACTORY;
-};
-import { unwrapLazy } from '../common/lazie.mjs';
+export function LazyFactory<FACTORY>(factory: () => FACTORY): FACTORY & {};

package/generated/types/src/function/MonkeyPatch.d.mts

@@ -0,0 +1,33 @@
+/**
+ * @import {MonkeyPatchedType} from '../typehints/MonkeyPatchedType.mjs'
+ */
+/**
+ * Monkey‑patch an environmental API by replacing a property on a parent object
+ * with a new function or class. This allows you to intercept or override
+ * browser/Node globals (e.g. `XMLHttpRequest`, `Worker`, `fetch`) without
+ * modifying the rest of your application code.
+ *
+ * ## Notes
+ * - Run this before other code that consumes the patched API.
+ * - Existing instances created before patching are unaffected.
+ * - If the property is non‑writable, assignment will throw.
+ * - For classes, always call `super(...args)` in your constructor.
+ * - For functions, preserve the call signature to avoid type errors.
+ *
+ * @template {Object} PAR
+ * @template {keyof PAR} KEY
+ * @param {PAR} parent - The parent object holding the property (e.g. `window`).
+ * @param {KEY} key - The property name on the parent to replace.
+ * @param {(
+ *    arg0:{originalObject:PAR[KEY]}
+ *  ) => MonkeyPatchedType<PAR[KEY]>
+ * } newObjectGenerator
+ *   - Function that receives the original object and returns the patched version.
+ *   - For classes: extend `originalObject` and override methods.
+ *   - For functions: spread arguments(and when necessary, delegate to `originalObject`).
+ * @returns {void}
+ */
+export function MonkeyPatch<PAR extends Object, KEY extends keyof PAR>(parent: PAR, key: KEY, newObjectGenerator: (arg0: {
+    originalObject: PAR[KEY];
+}) => MonkeyPatchedType<PAR[KEY]>): void;
+import type { MonkeyPatchedType } from '../typehints/MonkeyPatchedType.mjs';

package/generated/types/src/function/NewAnimationTimeline.d.mts

@@ -0,0 +1,24 @@
+/**
+ * @description
+ * - create animation timeline helper;
+ * @param {Object} options
+ * @param {number} options.fps
+ * - frame per second;
+ * @param {{seconds:number}|{frames:number}} options.duration
+ * @param {(frame:{index:number, total:number, percentage:number})=>void} callback
+ * - called every frame until duration ends;
+ * @returns {()=>void}
+ * - early clearInterval callback;
+ */
+export function NewAnimationTimeline({ fps, duration }: {
+    fps: number;
+    duration: {
+        seconds: number;
+    } | {
+        frames: number;
+    };
+}, callback: (frame: {
+    index: number;
+    total: number;
+    percentage: number;
+}) => void): () => void;

package/generated/types/src/function/NewChainable.d.mts

@@ -0,0 +1,35 @@
+/**
+ * @description
+ * - Wraps a target object in a chainable;
+ * - example:
+ * ```html
+ * <canvas id="myCanvas" width="400" height="400"></canvas>
+ * ```
+ * - chain call are synchronous without awaiting;
+ * >- if the method are async, it could cause race condition;
+ * @template {object} OBJ
+ * @param {OBJ} ctx
+ * @returns {import("../typehints/ChainableType.mjs").ChainableType<OBJ>}
+ * @example
+ * import { NewChainable, TrySync } from 'vivth/neutral';
+ *
+ * TrySync(()=>{
+ * const canvas = document.getElementById('myCanvas');
+ * if (!canvas) {
+ * 	return;
+ * }
+ *
+ * const ctx2D = canvas.getContext('2d');
+ *
+ * // instead of repeating call method from `ctx2D`, you can:
+ * NewChainable(ctx2D)
+ * 	.beginPath()
+ * 	.moveTo(50, 50)
+ * 	.lineTo(200, 50)
+ * 	.lineTo(200, 200)
+ * 	.closePath()
+ * 	.stroke();
+ * 	// .this to get ctx2D reference;
+ * })
+ */
+export function NewChainable<OBJ extends object>(ctx: OBJ): import("../typehints/ChainableType.mjs").ChainableType<OBJ>;

package/generated/types/src/function/NewDynamicsExport.d.mts

@@ -0,0 +1,49 @@
+/**
+ * @description
+ * generate generator watcher to `Dynamics`;
+ * 1) `./dynamics`: directory;
+ * 2) `./dynamics/**[blank]/*`(except 3)): watched source for 3);
+ * 3) `./dynamics/Dynamics.mjs`: collection of `modules`|`css`|`commonFile`(with `mimeTypes`);
+ * - this module assumes [Paths](#paths) to be already instantiated;
+ * @param {Object} options
+ * @param {string} options.rootPath
+ * - relative path to pseudo root;
+ * @param {number} [options.debounce]
+ * @param {boolean} [options.useFetchForAssets]
+ * - default: `true`;
+ * >- non js file will be `fetch`ed;
+ * - `false`;
+ * >- will use `import` instead;
+ * >- useful for vite Plugin;
+ * @param {import('chokidar').ChokidarOptions} [options.chokidarOptions]
+ * @param {(normalizedPath:string)=>boolean} [options.eachFilter]
+ * @returns {ReturnType<typeof TryAsync<FSDirArchWatcher<{ handler: string; mime: string | false; lastEditedUnixValue: number; }>>>}
+ */
+export function NewDynamicsExport({ rootPath, useFetchForAssets, debounce, chokidarOptions, eachFilter }: {
+    rootPath: string;
+    debounce?: number | undefined;
+    useFetchForAssets?: boolean | undefined;
+    chokidarOptions?: 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<import("chokidar").AWF>;
+    }> | undefined;
+    eachFilter?: ((normalizedPath: string) => boolean) | undefined;
+}): ReturnType<typeof TryAsync<FSDirArchWatcher<{
+    handler: string;
+    mime: string | false;
+    lastEditedUnixValue: number;
+}>>>;
+import { TryAsync } from './TryAsync.mjs';
+import { FSDirArchWatcher } from '../class/FSDirArchWatcher.mjs';

package/generated/types/src/function/NewObjectWrapper.d.mts

@@ -0,0 +1,10 @@
+/**
+ * @description
+ * - object creation mapper;
+ * @template {Object} OBJ
+ * @template {any} MODIFIED
+ * @param {OBJ} object
+ * @param {(obj:OBJ)=>MODIFIED} callback
+ * @returns {MODIFIED}
+ */
+export function NewObjectWrapper<OBJ extends Object, MODIFIED extends unknown>(object: OBJ, callback: (obj: OBJ) => MODIFIED): MODIFIED;

package/generated/types/src/function/ObjectRegistrar.d.mts

@@ -0,0 +1,17 @@
+/**
+ * @description
+ * - function helper to object registrar;
+ * @template {any[]} ARGS
+ * @template {any} OBJ
+ * @param {(...args:ARGS)=>OBJ} registrarCallback
+ * @returns {Parameters<typeof ObjectRegistrar<ARGS, OBJ>>[0]}
+ * @example
+ * import { ObjectRegistrar, Signal, ForOfSync } from 'vivth/neutral';
+ *
+ * const autoCleanedUpSignal = ObjectRegistrar(()=>{
+ *
+ * })
+ *
+ * const mySignal = autoCleanedUpSignal(1);
+ */
+export function ObjectRegistrar<ARGS extends any[], OBJ extends unknown>(registrarCallback: (...args: ARGS) => OBJ): Parameters<typeof ObjectRegistrar<ARGS, OBJ>>[0];

package/generated/types/src/function/ParseSQLFile.d.mts

@@ -0,0 +1,25 @@
+/**
+ * @description
+ * - parse then generate file right next to said sql file;
+ * - this function assume `Paths` already instantiated;s
+ * @param {string} path
+ * @param {(
+ *  arg0:{input:Record<string, string>,output:Record<string, string>, sqlString:string}
+ * )=>
+ *  {ext:string, content:string}
+ * } [fileGenerator]
+ * - file string generator;
+ * - the default will generate mjs callback type, and sql string;
+ * >- `callback` type: basename + 'CBType';
+ * >- `sql` string: basename + 'SQL';
+ * @returns {ReturnType<typeof TryAsync<boolean>>}
+ */
+export function ParseSQLFile(path: string, fileGenerator?: (arg0: {
+    input: Record<string, string>;
+    output: Record<string, string>;
+    sqlString: string;
+}) => {
+    ext: string;
+    content: string;
+}): ReturnType<typeof TryAsync<boolean>>;
+import { TryAsync } from './TryAsync.mjs';

package/generated/types/src/function/PipeAsync.d.mts

@@ -0,0 +1,19 @@
+/**
+ * @description
+ * - create an async pipeline starting from an initial value;
+ * - every step must return the same type (VALUE), but may be sync or async.
+ * @template {any} VALUE
+ * @param {VALUE} intialValue
+ * @param {...((currentvalue:VALUE)=>VALUE|Promise<VALUE>)} pipeFunctions
+ * @returns {Promise<VALUE>}
+ * @example
+ * import { PipeAsync } from 'vivth/neutral';
+ *
+ * const res = await PipeAsync(
+ *  'intialValue', // res: Promise<"intialValue">
+ *  (val) => `${val}:1`, // res: Promise<"intialValue:1">
+ *  async (val) => `${val}:2`, // res: Promise<"intialValue:1:2">
+ *  (val) => `${val}:3` // res: Promise<"intialValue:1:2:3">
+ * );
+ */
+export function PipeAsync<VALUE extends unknown>(intialValue: VALUE, ...pipeFunctions: ((currentvalue: VALUE) => VALUE | Promise<VALUE>)[]): Promise<VALUE>;

package/generated/types/src/function/PipeSync.d.mts

@@ -0,0 +1,17 @@
+/**
+ * @description
+ * @template {any} VALUE
+ * @param {VALUE} intialValue
+ * @param {...((currentvalue:VALUE)=>VALUE)} pipeFunctions
+ * @returns {VALUE}
+ * @example
+ * import { PipeSync } from 'vivth/neutral';
+ *
+ * const res = PipeSync(
+ *  'intialValue', // res: "intialValue"
+ *  (val) => `${val}:1`, // res: "intialValue:1"
+ *  (val) => `${val}:2`, // res: "intialValue:1:2"
+ *  (val) => `${val}:3` // res: "intialValue:1:2:3"
+ * );
+ */
+export function PipeSync<VALUE extends unknown>(intialValue: VALUE, ...pipeFunctions: ((currentvalue: VALUE) => VALUE)[]): VALUE;

package/generated/types/src/function/SafeImport.d.mts

@@ -0,0 +1,21 @@
+/**
+ * @description
+ * - import while imediately call clearing require caches;
+ * - `usecases`:
+ * >- long running process that need to prevent memory leak from uncleanable `cached import`;
+ * >- to simply import fresh everytime;
+ * - the imported module can then just be treated like any other variable, to only lived and tracked by variable reference only;
+ * - due to how `vivth/node.ClearRequireCache` works, parallel await (like using Promise.all, or not awaited until later) will be done squentially(if targetting the same path);
+ * @template { any } T
+ * - put the type
+ * @param {string} path
+ * - either absolute `diskAbsolutepath` or from `Paths.root`;
+ * @returns {ReturnType<typeof import('./TryAsync.mjs').TryAsync<T>>}
+ * @example
+ * // Paths.root/myscript.mjs
+ * import { SafeImport } from 'vivth/node';
+ *
+ * // add type with: import('vivth/neutral').SafeImportReturnType<import('./something.mjs')>
+ * const [importedModule, errorSafeImport] = await SafeImport('/absolute/path/from/Paths.root/something.mjs');
+ */
+export function SafeImport<T extends unknown>(path: string): ReturnType<typeof import("./TryAsync.mjs").TryAsync<T>>;

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

@@ -0,0 +1,23 @@
+/**
+ * @description
+ * - function helper to create template literal with valueHandler to handle each values;
+ * @template {any} INPUTTYPE
+ * @template {string|Promise<string>} RET
+ * @param {import('../typehints/TemplateLiteralValueHandler.mjs').TemplateLiteralValueHandler<INPUTTYPE>} valueHandler
+ * @param {(result:string)=>(RET)} [postProcess]
+ * @returns {(strings:TemplateStringsArray,
+ * ...values:(INPUTTYPE)[])=>
+ * RET}
+ * @example
+ * import { TemplateLiteral } from 'vivth/neutral';
+ *
+ * export const html = TemplateLiteral(
+ *  ({ ...datas }) => `my string`,
+ *  // 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<INPUTTYPE extends unknown, RET extends string | Promise<string>>(valueHandler: import("../typehints/TemplateLiteralValueHandler.mjs").TemplateLiteralValueHandler<INPUTTYPE>, postProcess?: (result: string) => (RET)): (strings: TemplateStringsArray, ...values: (INPUTTYPE)[]) => RET;

package/{types → generated/types}/src/function/Timeout.d.mts

@@ -5,7 +5,7 @@
  * - in miliseconds;
  * @returns {Promise<void>}
  * @example
- * import { Timeout } from 'vivth';
+ * import { Timeout } from 'vivth/neutral';
  *
  * const test = async () => {
  *   // code0

package/{types → generated/types}/src/function/Tries.d.mts

@@ -14,12 +14,12 @@
  * @param {RecordTryType} tryRecord
  * @returns {Promise<
  * 	[[keyof RecordTryType, RETURNTYPE], undefined]
- * 	| [[undefined, undefined], Error|undefined]
+ * 	| [[undefined, undefined], Set<Error>]
  * >}
  * @example
- * import { Tries } from 'vivth';
+ * import { Tries } from 'vivth/neutral';
  *
- * const [[key, result], error] = await Tries({
+ * const [[key, result], setOfError] = await Tries({
  * 	someRuntime: async ({ prevError }) => {
  * 		// asuming on this one doesn't naturally throw error,
  * 		// yet you need to continue to next key,
@@ -49,4 +49,4 @@
  */
 export function Tries<KEY extends string, RETURNTYPE, RecordTryType extends Record<KEY, (err: {
     prevError: undefined | Error;
-}) => Promise<RETURNTYPE>>>(tryRecord: RecordTryType): Promise<[[keyof RecordTryType, RETURNTYPE], undefined] | [[undefined, undefined], Error | undefined]>;
+}) => Promise<RETURNTYPE>>>(tryRecord: RecordTryType): Promise<[[keyof RecordTryType, RETURNTYPE], undefined] | [[undefined, undefined], Set<Error>]>;

package/{types → generated/types}/src/function/TryAsync.d.mts

@@ -6,7 +6,7 @@
  * @param {()=>Promise<RESULT>} asyncFunction_
  * @returns {Promise<[RESULT,undefined]|[undefined,Error]>}
  * @example
- * import { TryAsync } from 'vivth';
+ * import { TryAsync } from 'vivth/neutral';
  *
  * let [res, error] = await TryAsync(async () => {
  * 	return await fetch('./someAPI/Path');
@@ -14,7 +14,7 @@
  *
  * [res, error] = await TryAsync(async () => {
  * 	if(!res.ok) {
- * 		throw new Error(404);
+ * 		throw 404;
  * 	}
  * 	return await res.json();
  * })

package/{types → generated/types}/src/function/TryNew.d.mts

@@ -8,7 +8,7 @@
  * @returns {[InstanceType<CLASSREF>, undefined]|
  * [undefined, Error]}
  * @example
- * import { TryNew } from 'vivth';
+ * import { TryNew } from 'vivth/neutral';
  *
  * const [instance, error] = TryNew(ClassReference, ...classConstructorParameters)
  * if(!error) {

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

@@ -0,0 +1,27 @@
+/**
+ * @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`;
+ * >- at [at]\[blank\]typedef, import itself.mts pointing to the same exported object to fully type it in mjs(which `vivth` used to generate exports);
+ * - auto compile and typehint `.as.ts` to `.wasm`;
+ * @param {string} path
+ * - `relative`(to `Paths.root`) OR `absolute`, both are accepted;
+ * @param {Object} [options]
+ * @param {string} [options.overrideOutputDir]
+ * - default: write conversion to same directory;
+ * - path are relative to project root;
+ * @param {BufferEncoding} [options.encoding]
+ * - default: `utf-8`;
+ * @param {import('../typehints/AutoDocASOptions.mjs').AutoDocASOptions} [options.assemblyScriptOptions]
+ * @returns {Promise<void>}
+ * @example
+ * import { TsToMjs } from 'vivth/node';
+ *
+ * await TsToMjs('./myFile.mts', { encoding: 'utf-8', overrideOutputDir: './other/dir' });
+ */
+export function TsToMjs(path: string, { overrideOutputDir, encoding, assemblyScriptOptions, }?: {
+    overrideOutputDir?: string | undefined;
+    encoding?: BufferEncoding | undefined;
+    assemblyScriptOptions?: import("../typehints/AutoDocASOptions.mjs").AutoDocASOptions | undefined;
+}): Promise<void>;

package/generated/types/src/function/UniqueFSTempName.d.mts

@@ -0,0 +1,9 @@
+/**
+ * @description
+ * - generate unique full path name to temp directory + 'vivth/${uniqueName}.tmp';
+ * - filename length already calibrated for each os;
+ * @param {string} path
+ * @param {string} [fileExtention]
+ * @returns {string}
+ */
+export function UniqueFSTempName(path: string, fileExtention?: string): string;

package/generated/types/src/function/errorToMessage.d.mts

@@ -0,0 +1,5 @@
+/**
+ * @param {Error} err
+ * @returns {import('esbuild').Message}
+ */
+export function errorToMessage(err: Error): import("esbuild").Message;