vivth 0.11.1 → 1.0.0

package/src/function/LazyFactory.mjs

@@ -0,0 +1,71 @@
+// @ts-check
+
+import { unwrapLazy } from '../common/lazie.mjs';
+
+/**
+ * @description
+ * - function helper for creating lazyObject:
+ * >- usefull for lazily instantiating an object, since instance naturally have props/methods;
+ * @template T
+ * @param {() => T} factory
+ * @returns {T & {[unwrapLazy]: string}}
+ * - 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;
+ */
+export const LazyFactory = (factory) => {
+	let instance;
+	// @ts-expect-error
+	return new Proxy(
+		{},
+		{
+			get(_, prop) {
+				if (!instance) {
+					instance = factory();
+				}
+				if (prop === unwrapLazy) {
+					if (!instance) {
+						instance = factory();
+					}
+					return instance;
+				}
+				return instance[prop];
+			},
+			set(_, prop, newValue) {
+				if (prop === unwrapLazy) {
+					instance = factory();
+				}
+				if (!instance) {
+					instance = factory();
+				}
+				instance[prop] = newValue;
+				return true;
+			},
+			apply(_, thisArg, args) {
+				if (!instance) {
+					instance = factory();
+				}
+				return Reflect.apply(instance, thisArg, args);
+			},
+		}
+	);
+};

package/src/function/Timeout.mjs

@@ -0,0 +1,23 @@
+// @ts-check
+
+/**
+ * @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 const Timeout = (timeMS) => {
+	return new Promise((resolve) => {
+		setTimeout(resolve, timeMS);
+	});
+};

package/src/function/Try.mjs

@@ -0,0 +1,64 @@
+// @ts-check
+
+import { TryAsync } from './TryAsync.mjs';
+
+/**
+ * @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,
+ * 	() => 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 () => {
+ * 		// 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 () => {
+ * 		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 () => {
+ * 		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 const Try = async (tryRecord) => {
+	for (const key in tryRecord) {
+		const callback = tryRecord[key];
+		const [result, error] = await TryAsync(callback);
+		if (error) {
+			continue;
+		}
+		return [[key, result], undefined];
+	}
+	return [[undefined, undefined], new Error('unable to run any key')];
+};

package/src/function/TryAsync.mjs

@@ -2,13 +2,24 @@
 
 /**
  * @description
- * - error as value for asynchronous operation
- * returns: Promise<[`ResultType`|`undefined`, `Error`|`undefined`]>
- */
-/**
+ * - function for error as value for asynchronous operation;
+ * - usefull to flatten indentation for error handlings;
  * @template ResultType
  * @param {()=>Promise<ResultType>} asyncFunction_
  * @returns {Promise<[ResultType|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 const TryAsync = async (asyncFunction_) => {
 	try {

package/src/function/TrySync.mjs

@@ -2,13 +2,18 @@
 
 /**
  * @description
- * - error as value for synchronous operation
- * returns: [`ResultType`|`undefined`, `Error`|`undefined`]
- */
-/**
+ * - function for error as value for synchronous operation;
+ * - usefull to flatten indentation for error handlings;
  * @template ResultType
  * @param {()=>ResultType} function_
  * @returns {[ResultType|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 const TrySync = (function_) => {
 	try {

package/src/function/TsToMjs.mjs

@@ -0,0 +1,67 @@
+// @ts-check
+
+import { readFile } from 'node:fs/promises';
+import { basename, dirname, extname, join } from 'node:path';
+
+import { transform } from 'esbuild';
+
+import { Console } from '../class/Console.mjs';
+import { Paths } from '../class/Paths.mjs';
+import { TryAsync } from './TryAsync.mjs';
+import { WriteFileSafe } from './WriteFileSafe.mjs';
+
+/**
+ * @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_
+ * @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 const TsToMjs = async (path_, { overrideDir = undefined, encoding = 'utf-8' } = {}) => {
+	const rootPath = Paths.normalize(Paths.root);
+	if (!Paths.normalize(path_).startsWith(rootPath)) {
+		path_ = Paths.normalize(join(rootPath, path_));
+	}
+	const ext = extname(path_);
+	if (ext !== '.ts' && ext !== '.mts') {
+		return;
+	}
+	const [content, error] = await TryAsync(async () => {
+		return await readFile(path_, { encoding });
+	});
+	if (error) {
+		Console.error(error);
+		return;
+	}
+	const [result, transformError] = await TryAsync(async () => {
+		return await transform(content, {
+			loader: 'ts',
+			format: 'esm',
+			sourcemap: false,
+			target: 'esnext',
+			legalComments: 'inline',
+		});
+	});
+	if (transformError) {
+		Console.error(transformError);
+		return;
+	}
+	const outputDir = overrideDir ? join(rootPath, overrideDir) : dirname(path_);
+	const outputPath = join(outputDir, basename(path_).replace(ext, '.mjs'));
+	const [_, writeError] = await WriteFileSafe(outputPath, result.code, { encoding });
+	if (!writeError) {
+		return;
+	}
+	Console.error(writeError);
+};

package/src/function/WriteFileSafe.mjs

@@ -0,0 +1,37 @@
+// @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/src/types/{AnyButUndefined.type.mjs → AnyButUndefined.mjs}

@@ -1,5 +1,6 @@
 // @ts-check
 
 /**
+ * - type helper for ID or objects;
  * @typedef {{}|null|number|string|boolean|symbol|bigint|function} AnyButUndefined
  */

package/src/types/ExtnameType.mjs

@@ -0,0 +1,6 @@
+// @ts-check
+
+/**
+ * - jsRuntime extention naming convention;
+ * @typedef {`.${string}`} ExtnameType
+ */

package/src/types/IsListSignal.mjs

@@ -0,0 +1,6 @@
+// @ts-check
+
+/**
+ * - `EnvSignal.get` argument whether signal need to be a list or not;
+ * @typedef {boolean} IsListSignal
+ */

package/src/types/ListArg.mjs

@@ -0,0 +1,6 @@
+// @ts-check
+
+/**
+ * - ListSignal argument type;
+ * @typedef {Record<string, string>} ListArg
+ */

package/src/types/MutationType.mjs

@@ -0,0 +1,8 @@
+// @ts-check
+
+/**
+ * - `ListSignal` mutation type;
+ * @typedef {'push'|'unshift'|'splice'|'swap'|'modify'|'shift'|'remove'} MutationType
+ * - instance method: serves as helper to mutate, and notify for `effects`;
+ * > - `slice` uses `splice` in the background, you don't need to manually reindex when using it;
+ */

package/src/types/QCBFIFOReturn.mjs

@@ -0,0 +1,6 @@
+// @ts-check
+
+/**
+ * - return type of Q callback fifo;
+ * @typedef {Omit<import("./QCBReturn.mjs").QCBReturn, "isLastOnQ">} QCBFIFOReturn
+ */

package/src/types/QCBReturn.mjs

@@ -0,0 +1,6 @@
+// @ts-check
+
+/**
+ * - return type of Q callback;
+ * @typedef {{resume:()=>void, isLastOnQ:boolean}} QCBReturn
+ */

package/tsconfig.json

@@ -4,11 +4,11 @@
 		"declaration": true,
 		"emitDeclarationOnly": true,
 		"outDir": "./types",
-		"module": "ESNext",
-		"target": "ES2020",
+		"module": "esnext",
+		"target": "esnext",
 		"moduleResolution": "node",
 		"esModuleInterop": true,
 		"skipLibCheck": true
 	},
-	"include": ["./index.mjs", "./src"]
+	"include": ["./index.mjs", "./src", "./dev"]
 }

package/types/dev/index.d.mts

@@ -0,0 +1 @@
+export {};

package/types/index.d.mts

@@ -1,12 +1,38 @@
-export { $ } from "./src/class/$.mjs";
+export { CompileMJS } from "./src/bundler/CompileMJS.mjs";
+export { EsBundler } from "./src/bundler/EsBundler.mjs";
+export { Console } from "./src/class/Console.mjs";
 export { Derived } from "./src/class/Derived.mjs";
-export { PingFIFO } from "./src/class/PingFIFO.mjs";
-export { PingUnique } from "./src/class/PingUnique.mjs";
-export { Q } from "./src/class/Q.mjs";
-export { QFIFO } from "./src/class/QFIFO.mjs";
-export { QUnique } from "./src/class/QUnique.mjs";
+export { Effect } from "./src/class/Effect.mjs";
+export { EnvSignal } from "./src/class/EnvSignal.mjs";
+export { EventSignal } from "./src/class/EventSignal.mjs";
+export { ListDerived } from "./src/class/ListDerived.mjs";
+export { ListSignal } from "./src/class/ListSignal.mjs";
+export { Paths } from "./src/class/Paths.mjs";
+export { QChannel } from "./src/class/QChannel.mjs";
+export { SafeExit } from "./src/class/SafeExit.mjs";
+export { Setup } from "./src/class/Setup.mjs";
 export { Signal } from "./src/class/Signal.mjs";
-export { NewQBlock } from "./src/function/NewQBlock.mjs";
+export { WorkerMainThread } from "./src/class/WorkerMainThread.mjs";
+export { WorkerResult } from "./src/class/WorkerResult.mjs";
+export { WorkerThread } from "./src/class/WorkerThread.mjs";
+export { Base64URL } from "./src/common/Base64URL.mjs";
+export { EventNameSpace } from "./src/common/EventNameSpace.mjs";
+export { JSautoDOC } from "./src/doc/JSautoDOC.mjs";
+export { CreateImmutable } from "./src/function/CreateImmutable.mjs";
+export { EventCheck } from "./src/function/EventCheck.mjs";
+export { EventObject } from "./src/function/EventObject.mjs";
+export { IsAsync } from "./src/function/IsAsync.mjs";
+export { LazyFactory } from "./src/function/LazyFactory.mjs";
+export { Timeout } from "./src/function/Timeout.mjs";
+export { Try } from "./src/function/Try.mjs";
 export { TryAsync } from "./src/function/TryAsync.mjs";
 export { TrySync } from "./src/function/TrySync.mjs";
-export type AnyButUndefined = {} | null | number | string | boolean | symbol | bigint | Function;
+export { TsToMjs } from "./src/function/TsToMjs.mjs";
+export { WriteFileSafe } from "./src/function/WriteFileSafe.mjs";
+export type AnyButUndefined = import("./src/types/AnyButUndefined.mjs").AnyButUndefined;
+export type ExtnameType = import("./src/types/ExtnameType.mjs").ExtnameType;
+export type IsListSignal = import("./src/types/IsListSignal.mjs").IsListSignal;
+export type ListArg = import("./src/types/ListArg.mjs").ListArg;
+export type MutationType = import("./src/types/MutationType.mjs").MutationType;
+export type QCBFIFOReturn = import("./src/types/QCBFIFOReturn.mjs").QCBFIFOReturn;
+export type QCBReturn = import("./src/types/QCBReturn.mjs").QCBReturn;

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

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

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

@@ -0,0 +1,8 @@
+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/bundler/EsBundler.d.mts

@@ -0,0 +1,7 @@
+export function EsBundler({ content, extension, asBinary }: {
+    content: string;
+    extension: string;
+    asBinary?: boolean;
+}, esbuildOptions?: Omit<Parameters<typeof build>[0], "entryPoints" | "bundle" | "write" | "format" | "sourcemap" | "external" | "stdin">): Promise<ReturnType<typeof TryAsync<string>>>;
+import { build } from 'esbuild';
+import { TryAsync } from '../function/TryAsync.mjs';

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

@@ -0,0 +1,40 @@
+/**
+ * @description
+ * - class with static methods to print to standard console with added style;
+ */
+export class Console {
+    /**
+     * @param {string} prefix
+     * @param {'log'|'info'|'error'|'warn'} mode
+     * - Console method to use
+     * @param {any} data
+     * @param {string} color
+     * @param {string} bgcolor
+     * @returns {void}
+     */
+    static "__#1@#call": (prefix: string, mode: "log" | "info" | "error" | "warn", data: any, color: string, bgcolor: string) => void;
+    /**
+     * @description
+     * @param {any} data
+     * @returns {void}
+     */
+    static log: (data: any) => void;
+    /**
+     * @description
+     * @param {any} data
+     * @returns {void}
+     */
+    static info: (data: any) => void;
+    /**
+     * @description
+     * @param {any} data
+     * @returns {void}
+     */
+    static warn: (data: any) => void;
+    /**
+     * @description
+     * @param {any} data
+     * @returns {void}
+     */
+    static error: (data: any) => void;
+}

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

@@ -1,17 +1,31 @@
 /**
  * @description
- * - a class for creating signal which its value are derived from other signal (`Derived` and `Signal` alike);
- * - can be subscribed by using [New$](#new$);
- * - for minimal total bundle size use `function` [NewDerived](#newderived) instead;
- */
-/**
+ * - a class for creating derived version of [Signal](#signal);
  * @template V
  * @extends Signal<V>
  */
 export class Derived<V> extends Signal<V> {
     /**
-     * @param {()=>V} derivedFunction
+     * @description
+     * - Derived used [Signal](#signal) and [Effect](#effect) under the hood;
+     * @param {(effectInstanceOptions:Effect["options"])=>Promise<V>} derivedFunction
+     * @example
+     * import { Signal, Derived } from  'vivth';
+     *
+     * const count = new Signal(0);
+     * const double = new Derived(async({
+     * 		subscribe,
+     * 		// : registrar callback for this derived instance, immediately return the signal instance
+     * 	}) => {
+     * 	return subscribe(count).value + count.value;
+     * 	// double listen to count changes, by returning the value, double.value also changes
+     * 	// notice the count.value are accessed double, but it's all safe,
+     * 	// since the wrapped one is the only one that are recorded as notifier.
+     * });
+     *
+     * count.value++;
      */
-    constructor(derivedFunction: () => V);
+    constructor(derivedFunction: (effectInstanceOptions: Effect["options"]) => Promise<V>);
 }
 import { Signal } from './Signal.mjs';
+import { Effect } from './Effect.mjs';

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

@@ -0,0 +1,77 @@
+/**
+ * @type {Set<Effect>}
+ */
+export const setOfEffects: Set<Effect>;
+/**
+ * @description
+ * - a class for creating effect;
+ * - compared to previous class <b>$</b> reactivity model, `Effect`:
+ * >- doesn't autosubscribe at first run;
+ * >- it is using passed <b>$</b> named `arg0` options as subscriber;
+ * >- doesn't block other queues during first run(previously blocks other queues to safely register signal autoscubscriber);
+ * >- now can dynamically subscribes to signal, even on conditionals, that are not run during first run;
+ */
+export class Effect {
+    /**
+     * @description
+     * @param {(arg0:Effect["options"])=>Promise<void>} effect
+     * @example
+     * import { Signal, Derived, Effect, Console } from  'vivth';
+     *
+     * const count = new Signal(0);
+     * const double = new Derived( async({$}) => $(count).value \* 2); // double listen to count changes
+     * new Effect(async ({
+     * 			subscribe, // : registrar callback for this effect instance, immediately return the signal instance
+     * 			removeEffect, // : disable this effect instance from reacting to dependency changes;
+     * 		}) => {
+     * 			Console.log(subscribe(double).value); // effect listen to double changes
+     * 			const a = double.value; //  no need to wrap double twice with $
+     * })
+     *
+     * count.value++;
+     */
+    constructor(effect: (arg0: Effect["options"]) => Promise<void>);
+    options: {
+        /**
+         * @instance options
+         * @description
+         * - normally it's passed as argument to constructor, however it is also accessible from `options` property;
+         * @template {Signal} S
+         * @param {S} signal
+         * @returns {S}
+         * @example
+         * const effect = new Effect(async () => {
+         * 	// code
+         * })
+         * effect.options.subscribe(signalInstance);
+         */
+        subscribe: <S extends Signal<any>>(signal: S) => S;
+        /**
+         * @instance options
+         * @description
+         * - normally it's passed as argument to constructor, however it is also accessible from `options` property;
+         * @type {()=>void}
+         * @example
+         * const effect = new Effect(async () => {
+         * 	// code
+         * })
+         * effect.options.removeEffect();
+         */
+        removeEffect: () => void;
+    } & {
+        "vivth:unwrapLazy;": string;
+    };
+    /**
+     * @description
+     * - normally is to let to be automatically run when dependency signals changes, however it's also accessible as instance method;
+     * @returns {void}
+     * @example
+     * const effect = new Effect(async ()=>{
+     * 	// code
+     * })
+     * effect.run();
+     */
+    run: () => void;
+    #private;
+}
+import { Signal } from './Signal.mjs';

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

@@ -0,0 +1,47 @@
+/**
+ * @description
+ * - non browser API;
+ * - uses [Signal](#signal) and [Derived](#derived) under the hood;
+ * @template V
+ */
+export class EnvSignal<V> {
+    /**
+     * @description
+     * - create `EnvSignal` instance;
+     * @param {V} initialValue
+     */
+    constructor(initialValue: V);
+    /**
+     * @description
+     * - exposed property to listen to;
+     * @type {Derived<V>}
+     * @example
+     * import { EnvSignal, Effect } from 'vivth';
+     *
+     * export const myEnv = new EnvSignal(true);
+     * new Effect(async ({ subscribe }) => {
+     * 	const myEnvValue = subscribe(myEnv.env).value;
+     * 	// code
+     * })
+     */
+    env: Derived<V>;
+    /**
+     * @description
+     * - call to correct the value of previously declared value;
+     * - can only be called once;
+     * @param {V} correctedValue
+     * @returns {void}
+     * @example
+     * import { EnvSignal } from 'vivth';
+     *
+     * export const myEnv = new EnvSignal(true);
+     *
+     * // somewhere else on the program
+     * import { myEnv } from '$src/myEnv'
+     *
+     * myEnv.correction(false); // this will notify all subscribers;
+     */
+    correction: (correctedValue: V) => void;
+    #private;
+}
+import { Derived } from './Derived.mjs';