vivth 1.1.2 → 1.2.0

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

@@ -0,0 +1,90 @@
+/**
+ * @description
+ * - collection of static methods of file access with added safety to mkdir before proceeding;
+ */
+export class FileSafe {
+    /**
+     * @description
+     * - method to create file safely by recursively mkdir the dirname of the outFile;
+     * - also returning promise of result & error as value;
+     * @param {Parameters<writeFile>[0]} outFile
+     * @param {Parameters<writeFile>[1]} content
+     * @param {Parameters<writeFile>[2]} [options]
+     * @returns {ReturnType<typeof TryAsync<void>>}
+     * @example
+     * import { join } from 'node:path';
+     * import { FileSafe, Paths } from 'vivth';
+     *
+     * const [, errorWrite] = await FileSafe.write(
+     * 	join(Paths.root, '/some/path.mjs'),
+     * 	`console.log("hello-world!!");`,
+     * 	{ encoding: 'utf-8' }
+     * );
+     */
+    static write: (outFile: Parameters<typeof writeFile>[0], content: Parameters<typeof writeFile>[1], options?: Parameters<typeof writeFile>[2]) => ReturnType<typeof TryAsync<void>>;
+    /**
+     * @description
+     * - method to copy file/dir safely by recursively mkdir the dirname of the dest;
+     * - also returning promise of result & error as value;
+     * @param {Parameters<typeof copyFile>[0]} sourceFile
+     * @param {Parameters<typeof copyFile>[1]} destinationFile
+     * @param {Parameters<typeof copyFile>[2]} mode
+     * @returns {ReturnType<typeof TryAsync<void>>}
+     * @example
+     * import { join } from 'node:path';
+     * import { FileSafe, Paths } from 'vivth';
+     *
+     * const [, errorWrite] = await FileSafe.copy(
+     * 	join(Paths.root, '/some/path.mjs'),
+     * 	join(Paths.root, '/other/path.copy.mjs'),
+     * 	{ encoding: 'utf-8' }
+     * );
+     */
+    static copy: (sourceFile: Parameters<typeof copyFile>[0], destinationFile: Parameters<typeof copyFile>[1], mode: Parameters<typeof copyFile>[2]) => ReturnType<typeof TryAsync<void>>;
+    /**
+     * @description
+     * - method to rename file/dir safely by recursively mkdir the dirname of the dest;
+     * - also returning promise of result & error as value;
+     * @param {Parameters<typeof rename>[0]} oldPath
+     * @param {Parameters<typeof rename>[0]} newPath
+     * @returns {ReturnType<typeof TryAsync<void>>}
+     * @example
+     * import { join } from 'node:path';
+     * import { FileSafe, Paths } from 'vivth';
+     *
+     * const [, errorRename] = await FileSafe.rename(
+     * 	join(Paths.root, 'some/path'),
+     * 	join(Paths.root, 'other/path'),
+     * );
+     */
+    static rename: (oldPath: Parameters<typeof rename>[0], newPath: Parameters<typeof rename>[0]) => ReturnType<typeof TryAsync<void>>;
+    /**
+     * @description
+     * - function to remove dir and file;
+     * - also returning promise of result & error as value;
+     * @param {Parameters<rm>[0]} path
+     * @param {Parameters<rm>[1]} [rmOptions]
+     * @returns {ReturnType<typeof TryAsync<void>>}
+     */
+    static rm: (path: Parameters<typeof rm>[0], rmOptions?: Parameters<typeof rm>[1]) => ReturnType<typeof TryAsync<void>>;
+    /**
+     * @description
+     * - create directory recursively;
+     * - also returning promise of result & error as value;
+     * @param {Parameters<mkdir>[0]} outDir
+     * - absolute path
+     * @returns {ReturnType<typeof TryAsync<string>>}
+     * @example
+     * import { join } from 'node:path';
+     * import { FileSafe, Paths } from 'vivth';
+     *
+     * const [str, errorMkDir] = await FileSafe.mkdir(join(Paths.root, '/some/path/example'));
+     */
+    static mkdir: (outDir: Parameters<typeof mkdir>[0]) => ReturnType<typeof TryAsync<string>>;
+}
+import { TryAsync } from '../function/TryAsync.mjs';
+import { writeFile } from 'node:fs/promises';
+import { copyFile } from 'node:fs/promises';
+import { rename } from 'node:fs/promises';
+import { rm } from 'node:fs/promises';
+import { mkdir } from 'node:fs/promises';

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

@@ -3,16 +3,19 @@
  * - class to create `dervivedList` that satisfy `Array<Record<string, string>>`;
  * - usefull for `derivedLoops`, e.g. temporary search values;
  * - is a `Derived` instance;
- * @template {ListArg} LA
- * @extends {Derived<LA[]>}
+ * @template {ListArg} LISTARG
+ * @extends {Derived<LISTARG[]>}
  */
-export class ListDerived<LA extends import("../types/ListArg.mjs").ListArg> extends Derived<LA[]> {
+export class ListDerived<LISTARG extends import("../types/ListArg.mjs").ListArg> extends Derived<LISTARG[]> {
     /**
      * @typedef {import('../types/ListArg.mjs').ListArg} ListArg
+     * @typedef {import('../common/lazie.mjs').unwrapLazy} unwrapLazy
      */
     /**
      * @description
-     * @param {(effectInstanceOptions:Effect["options"])=>Promise<LA[]>} derivedFunction
+     * @param {(effectInstanceOptions:Omit<Effect["options"],
+     * unwrapLazy>)=>
+     * Promise<LISTARG[]>} derivedFunction
      * @example
      * import { ListSignal, ListDerived } from 'vivth';
      *
@@ -29,7 +32,7 @@ export class ListDerived<LA extends import("../types/ListArg.mjs").ListArg> exte
      * 	})
      * });
      */
-    constructor(derivedFunction: (effectInstanceOptions: Effect["options"]) => Promise<LA[]>);
+    constructor(derivedFunction: (effectInstanceOptions: Omit<Effect["options"], "vivth:unwrapLazy;">) => Promise<LISTARG[]>);
 }
 import { Derived } from './Derived.mjs';
 import { Effect } from './Effect.mjs';

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

@@ -5,10 +5,10 @@
 /**
  * @description
  * - class to create list that satisfy `Array<Record<string, string>>`.
- * @template {import('../types/ListArg.mjs').ListArg} LA
- * @extends {Signal<LA[]>}
+ * @template {import('../types/ListArg.mjs').ListArg} LISTARG
+ * @extends {Signal<LISTARG[]>}
  */
-export class ListSignal<LA extends import("../types/ListArg.mjs").ListArg> extends Signal<LA[]> {
+export class ListSignal<LISTARG extends import("../types/ListArg.mjs").ListArg> extends Signal<LISTARG[]> {
     /**
      * @description
      * - Checks if the input is an array whose first item (if present) is a plain object
@@ -20,7 +20,7 @@ export class ListSignal<LA extends import("../types/ListArg.mjs").ListArg> exten
     /**
      * @description
      * - usefull for `loops`;
-     * @param {LA[]} [value]
+     * @param {LISTARG[]} [value]
      * @example
      * import { ListSignal } from 'vivth';
      *
@@ -29,7 +29,7 @@ export class ListSignal<LA extends import("../types/ListArg.mjs").ListArg> exten
      *      {key1: "test2",},
      * ]);
      */
-    constructor(value?: LA[]);
+    constructor(value?: LISTARG[]);
     /**
      * @description
      * - methods collection that mimics `Array` API;
@@ -41,17 +41,17 @@ export class ListSignal<LA extends import("../types/ListArg.mjs").ListArg> exten
          * @description
          * - reference to structuredClone elements of `value`;
          * - calling doesn't notify
-         * @type {Array<LA>}
+         * @returns {Array<LISTARG>}
          */
-        readonly structuredClone: Array<LA>;
+        readonly structuredClone: Array<LISTARG>;
         /**
          * @instance arrayMethods
          * @description
          * - appends new elements to the end;
-         * @param {...LA} listArg
+         * @param {...LISTARG} listArg
          * @returns {void}
          */
-        push: (...listArg: LA[]) => void;
+        push: (...listArg: LISTARG[]) => void;
         /**
          * @instance arrayMethods
          * @description
@@ -63,10 +63,10 @@ export class ListSignal<LA extends import("../types/ListArg.mjs").ListArg> exten
          * @instance arrayMethods
          * @description
          * - inserts new element at the start;
-         * @param  {...LA} listArg
+         * @param  {...LISTARG} listArg
          * @returns {void}
          */
-        unshift: (...listArg: LA[]) => void;
+        unshift: (...listArg: LISTARG[]) => void;
         /**
          * @instance arrayMethods
          * @description
@@ -82,11 +82,11 @@ export class ListSignal<LA extends import("../types/ListArg.mjs").ListArg> exten
          * @instance arrayMethods
          * @description
          * - replace whole `List` data with new array.
-         * @param {LA[]} listArgs
+         * @param {LISTARG[]} listArgs
          * - new array in place of the deleted array.
          * @returns {void}
          */
-        replace: (listArgs: LA[]) => void;
+        replace: (listArgs: LISTARG[]) => void;
         /**
          * @instance arrayMethods
          * @description
@@ -95,11 +95,11 @@ export class ListSignal<LA extends import("../types/ListArg.mjs").ListArg> exten
          * - The zero-based location in the data from which to start removing elements.
          * @param {number} deleteCount
          * -The number of elements to remove.
-         * @param {...LA} listArg
+         * @param {...LISTARG} listArg
          * - new data in place of the deleted data.
          * @returns {void}
          */
-        splice: (start: number, deleteCount: number, ...listArg: LA[]) => void;
+        splice: (start: number, deleteCount: number, ...listArg: LISTARG[]) => void;
         /**
          * @instance arrayMethods
          * @description
@@ -114,10 +114,10 @@ export class ListSignal<LA extends import("../types/ListArg.mjs").ListArg> exten
          * @description
          * - modify `List` element at specific index;
          * @param {number} index
-         * @param {Partial<LA>} listArg
+         * @param {Partial<LISTARG>} listArg
          * @returns {void}
          */
-        modify: (index: number, listArg: Partial<LA>) => void;
+        modify: (index: number, listArg: Partial<LISTARG>) => void;
         /**
          * @instance arrayMethods
          * @description
@@ -141,7 +141,112 @@ export class ListSignal<LA extends import("../types/ListArg.mjs").ListArg> exten
          */
         pop: () => void;
     } & {
-        "vivth:unwrapLazy;": string;
+        "vivth:unwrapLazy;": () => {
+            /**
+             * @instance arrayMethods
+             * @description
+             * - reference to structuredClone elements of `value`;
+             * - calling doesn't notify
+             * @returns {Array<LISTARG>}
+             */
+            readonly structuredClone: Array<LISTARG>;
+            /**
+             * @instance arrayMethods
+             * @description
+             * - appends new elements to the end;
+             * @param {...LISTARG} listArg
+             * @returns {void}
+             */
+            push: (...listArg: LISTARG[]) => void;
+            /**
+             * @instance arrayMethods
+             * @description
+             * - removes the first element;
+             * @type {()=>void}
+             */
+            shift: () => void;
+            /**
+             * @instance arrayMethods
+             * @description
+             * - inserts new element at the start;
+             * @param  {...LISTARG} listArg
+             * @returns {void}
+             */
+            unshift: (...listArg: LISTARG[]) => void;
+            /**
+             * @instance arrayMethods
+             * @description
+             * - for both start and end, a negative index can be used to indicate an offset from the end of the data. For example, -2 refers to the second to last element of the data;
+             * @param {number} [start]
+             * - the beginning index of the specified portion of the data. If start is undefined, then the slice begins at index 0.
+             * @param {number} [end]
+             * - the end index of the specified portion of the data. This is exclusive of the element at the index 'end'. If end is undefined, then the slice extends to the end of the data.
+             * @returns {void}
+             */
+            slice: (start?: number, end?: number) => void;
+            /**
+             * @instance arrayMethods
+             * @description
+             * - replace whole `List` data with new array.
+             * @param {LISTARG[]} listArgs
+             * - new array in place of the deleted array.
+             * @returns {void}
+             */
+            replace: (listArgs: LISTARG[]) => void;
+            /**
+             * @instance arrayMethods
+             * @description
+             * - removes elements from an data and, if necessary, inserts new elements in their place;
+             * @param {number} start
+             * - The zero-based location in the data from which to start removing elements.
+             * @param {number} deleteCount
+             * -The number of elements to remove.
+             * @param {...LISTARG} listArg
+             * - new data in place of the deleted data.
+             * @returns {void}
+             */
+            splice: (start: number, deleteCount: number, ...listArg: LISTARG[]) => void;
+            /**
+             * @instance arrayMethods
+             * @description
+             * - swap `List` data between two indexes;
+             * @param {number} indexA
+             * @param {number} indexB
+             * @returns {void}
+             */
+            swap: (indexA: number, indexB: number) => void;
+            /**
+             * @instance arrayMethods
+             * @description
+             * - modify `List` element at specific index;
+             * @param {number} index
+             * @param {Partial<LISTARG>} listArg
+             * @returns {void}
+             */
+            modify: (index: number, listArg: Partial<LISTARG>) => void;
+            /**
+             * @instance arrayMethods
+             * @description
+             * - remove `List` element at specific index;
+             * @param {number} index
+             * @returns {void}
+             */
+            remove: (index: number) => void;
+            /**
+             * @instance arrayMethods
+             * @description
+             * - reverses the elements in an `List` in place.
+             * @returns {void}
+             */
+            reverse: () => void;
+            /**
+             * @instance arrayMethods
+             * @description
+             * - removes the last element;
+             * @returns {void}
+             */
+            pop: () => void;
+        };
     };
     #private;
 }