@futdevpro/fsm-dynamo 1.14.10 → 1.14.12

package/src/_collections/utils/array.util.ts

@@ -16,6 +16,14 @@ export class DyFM_Array {
    * @param list - The array to iterate over.
    * @param func - The function to apply to each element.
    * @returns A promise that resolves when all elements have been processed.
+   * 
+   * @example 
+   * ```ts
+   * const list: number[] = [ 1, 2, 3 ];
+   * await DyFM_Array.asyncForEach(list, async (element: number, index?: number, array?: number[]): Promise<void> => {
+   *   console.log(element, index, array);
+   * });
+   * ```
    */
   static async asyncForEach<T>(
     list: T[], 
@@ -32,6 +40,14 @@ export class DyFM_Array {
    * @param list - The array to iterate over.
    * @param func - The function to apply to each element.
    * @returns A promise that resolves to the final result.
+   * 
+   * @example 
+   * ```ts
+   * const list: number[] = [ 1, 2, 3 ];
+   * const result = await DyFM_Array.asyncForEachReturnToOne(0, list, async (element: number, dataCurrent: number, index?: number, array?: number[]): Promise<number> => {
+   *   return dataCurrent + element;
+   * });
+   * ```
    */
   static async asyncForEachReturnToOne<T, K>(
     startData: K,
@@ -52,6 +68,14 @@ export class DyFM_Array {
    * @param list - The array to iterate over.
    * @param func - The function to apply to each element.
    * @returns A promise that resolves to an array of results.
+   * 
+   * @example 
+   * ```ts
+   * const list: number[] = [ 1, 2, 3 ];
+   * const result = await DyFM_Array.asyncForEachReturnToAll(list, async (element: number, index?: number, array?: number[]): Promise<number> => {
+   *   return element * 2;
+   * });
+   * ```
    */
   static async asyncForEachReturnToAll<T, K>(
     list: T[], 
@@ -71,6 +95,15 @@ export class DyFM_Array {
    * @param list - The array to iterate over.
    * @param func - The function to apply to each element.
    * @returns A promise that resolves to an array of results.
+   * 
+   * @example 
+   * ```ts
+   * const list: number[] = [ 1, 2, 3 ];
+   * const result = await DyFM_Array.asyncForEachAllAtOnce(list, async (element: number, index?: number, array?: number[]): Promise<number> => {
+   *   return [ element * 2, element * 3 ];
+   * });
+   * console.log(result); // [ [ 2, 3 ], [ 4, 6 ], [ 6, 9 ] ]
+   * ```
    */
   static async asyncForEachAllAtOnce<T, R>(
     list: T[], 
@@ -84,6 +117,15 @@ export class DyFM_Array {
    * @param list - The array to filter.
    * @param filterFunc - The function to apply to each element.
    * @returns A promise that resolves to an array of results.
+   * 
+   * @example 
+   * ```ts
+   * const list: number[] = [ 1, 2, 3 ];
+   * const result = await DyFM_Array.asyncFilter(list, async (element: number, index?: number, array?: number[]): Promise<boolean> => {
+   *   return element % 2 === 0;
+   * });
+   * console.log(result); // [ 2 ]
+   * ```
    */
   static async asyncFilter<T>(
     list: T[], 
@@ -105,6 +147,15 @@ export class DyFM_Array {
    * @param list - The array to map.
    * @param mapFunc - The function to apply to each element.
    * @returns A promise that resolves to an array of results.
+   * 
+   * @example 
+   * ```ts
+   * const list: number[] = [ 1, 2, 3 ];
+   * const result = await DyFM_Array.asyncMap(list, async (element: number, index?: number, array?: number[]): Promise<number> => {
+   *   return element * 2;
+   * });
+   * console.log(result); // [ 2, 4, 6 ]
+   * ```
    */
   static async asyncMap<T, R>(
     list: T[], 
@@ -123,6 +174,13 @@ export class DyFM_Array {
    * Returns the last element of an array.
    * @param array - The array to get the last element from.
    * @returns The last element of the array, or null if the array is empty.
+   * 
+   * @example 
+   * ```ts
+   * const list: number[] = [ 1, 2, 3 ];
+   * const result = DyFM_Array.last(list);
+   * console.log(result); // 3
+   * ```
    */
   static last<T>(array: T[]): T | null {
     return array?.length ? array[array.length - 1] : null;
@@ -133,6 +191,13 @@ export class DyFM_Array {
    * @param string - The string to check.
    * @param array - The array to check.
    * @returns True if the string is the last element of the array, false otherwise.
+   * 
+   * @example 
+   * ```ts
+   * const list: number[] = [ 1, 2, 3 ];
+   * const result = DyFM_Array.isLast(3, list);
+   * console.log(result); // true
+   * ```
    */
   static isLast<T>(element: T, array: T[]): boolean {
     return array.indexOf(element) === array.length - 1;
@@ -143,6 +208,13 @@ export class DyFM_Array {
    * @param string - The string to check.
    * @param array - The array to check.
    * @returns True if the string is the last element of the array, false otherwise.
+   * 
+   * @example 
+   * ```ts
+   * const list: number[] = [ 1, 2, 3 ];
+   * const result = DyFM_Array.isLastIndex(2, list);
+   * console.log(result); // true
+   * ```
    */
   static isLastIndex<T>(index: number, array: T[]): boolean {
     return index === array.length - 1;
@@ -153,6 +225,13 @@ export class DyFM_Array {
    * @param string - The string to check.
    * @param array - The array to check.
    * @returns True if the string is the first element of the array, false otherwise.
+   * 
+   * @example 
+   * ```ts
+   * const list: number[] = [ 1, 2, 3 ];
+   * const result = DyFM_Array.isFirst(1, list);
+   * console.log(result); // true
+   * ```
    */
   static isFirst<T>(element: T, array: T[]): boolean {
     return array.indexOf(element) === 0;
@@ -162,6 +241,13 @@ export class DyFM_Array {
    * Returns the last character of a string.
    * @param string - The string to get the last character from.
    * @returns The last character of the string, or null if the string is empty.
+   * 
+   * @example 
+   * ```ts
+   * const string = 'hello';
+   * const result = DyFM_Array.lastCharacter(string);
+   * console.log(result); // 'o'
+   * ```
    */
   static lastCharacter(string: string): string | null {
     return string?.length ? string[string.length - 1] : null;
@@ -171,6 +257,13 @@ export class DyFM_Array {
    * Returns the first element of an array.
    * @param array - The array to get the first element from.
    * @returns The first element of the array, or null if the array is empty.
+   * 
+   * @example 
+   * ```ts
+   * const list: number[] = [ 1, 2, 3 ];
+   * const result = DyFM_Array.first(list);
+   * console.log(result); // 1
+   * ```
    */
   static first<T>(array: T[]): T | null {
     return array?.length ? array[0] : null;
@@ -181,6 +274,13 @@ export class DyFM_Array {
    * @param array - The array to remove the element from.
    * @param element - The element to remove from the array.
    * @returns The array with the element removed.
+   * 
+   * @example 
+   * ```ts
+   * const list: number[] = [ 1, 2, 3 ];
+   * const result = DyFM_Array.remove(list, 2);
+   * console.log(result); // [ 1, 3 ]
+   * ```
    */
   static remove<T>(array: T[], element: T): T[] {
     const index = array.indexOf(element);
@@ -197,6 +297,15 @@ export class DyFM_Array {
    * @param array - The array to find and remove the element from.
    * @param func - The function to apply to each element.
    * @returns The array with the element removed.
+   * 
+   * @example 
+   * ```ts
+   * const list: number[] = [ 1, 2, 3 ];
+   * const result = DyFM_Array.findNRemove(list, (element: number, index?: number, array?: number[]): boolean => {
+   *   return element === 2;
+   * });
+   * console.log(result); // [ 1, 3 ]
+   * ```
    */
   static findNRemove<T>(
     array: T[], 
@@ -215,6 +324,13 @@ export class DyFM_Array {
    * Shuffles an array.
    * @param array - The array to shuffle.
    * @returns The shuffled array.
+   * 
+   * @example 
+   * ```ts
+   * const list: number[] = [ 1, 2, 3 ];
+   * const result = DyFM_Array.shuffle(list);
+   * console.log(result); // [ 3, 1, 2 ]
+   * ```
    */
   static shuffle<T>(array: T[]): T[] {
     let currentIndex = array.length;
@@ -236,6 +352,13 @@ export class DyFM_Array {
    * @param pageIndex - The index of the page to return.
    * @param pageSize - The size of the page.
    * @returns The page of the array.
+   * 
+   * @example 
+   * ```ts
+   * const list: number[] = [ 1, 2, 3, 4, 5, 6, 7, 8 ];
+   * const result = DyFM_Array.page(list, 0, 2);
+   * console.log(result); // [ 1, 2 ]
+   * ```
    */
   static page<T>(array: T[], pageIndex: number, pageSize: number): T[] {
     return array.slice(pageIndex * pageSize, (pageIndex + 1) * pageSize);
@@ -247,6 +370,13 @@ export class DyFM_Array {
    * @param pageIndex - The index of the page to return.
    * @param pageSize - The size of the page.
    * @returns The page of the array.
+   * 
+   * @example 
+   * ```ts
+   * const list: number[] = [ 1, 2, 3, 4, 5, 6, 7, 8 ];
+   * const result = DyFM_Array.paged(list, 0, 2);
+   * console.log(result); // { pageIndex: 0, pageSize: 2, total: 8, totalPageCount: 4, items: [ 1, 2 ] }
+   * ```
    */
   static paged<T>(array: T[], pageIndex: number, pageSize: number): DyFM_Paged<T> {
     return {
@@ -264,6 +394,13 @@ export class DyFM_Array {
    * @param indexA - The index of the first element to swap.
    * @param indexB - The index of the second element to swap.
    * @returns The array with the elements swapped.
+   * 
+   * @example 
+   * ```ts
+   * const list: number[] = [ 1, 2, 3 ];
+   * const result = DyFM_Array.swap(list, 0, 2);
+   * console.log(result); // [ 3, 2, 1 ]
+   * ```
    */
   static swap<T>(array: T[], indexA: number, indexB: number): T[] {
     [ array[indexA], array[indexB] ] = [ array[indexB], array[indexA] ];
@@ -275,6 +412,13 @@ export class DyFM_Array {
    * Checks if a string list has multiplications.
    * @param stringList - The string list to check.
    * @returns True if the string list has multiplications, false otherwise.
+   * 
+   * @example 
+   * ```ts
+   * const list: string[] = [ 'a', 'b', 'c', 'a' ];
+   * const result = DyFM_Array.stringListHasMultiplications(list);
+   * console.log(result); // true
+   * ```
    */
   static stringListHasMultiplications(stringList: string[]): boolean {
     return stringList.some((str: string, index: number): boolean => {
@@ -286,6 +430,13 @@ export class DyFM_Array {
    * Filters a string list to remove multiplications.
    * @param stringList - The string list to filter.
    * @returns The filtered string list.
+   * 
+   * @example 
+   * ```ts
+   * const list: string[] = [ 'a', 'b', 'c', 'a' ];
+   * const result = DyFM_Array.filterStringMultiplications(list);
+   * console.log(result); // [ 'a', 'b', 'c' ]
+   * ```
    */
   static filterStringMultiplications(stringList: string[]): string[] {
     return stringList.filter((str: string, index: number): boolean => {
@@ -297,6 +448,13 @@ export class DyFM_Array {
    * Gathers multiplications from a string list.
    * @param stringList - The string list to gather multiplications from.
    * @returns The gathered multiplications.
+   * 
+   * @example 
+   * ```ts
+   * const list: string[] = [ 'a', 'b', 'c', 'a' ];
+   * const result = DyFM_Array.gatherStringMultiplications(list);
+   * console.log(result); // [ [ 'a', 'a' ] ]
+   * ```
    */
   static gatherStringMultiplications(stringList: string[]): string[][] {
     const multiplications: string[][] = [];
@@ -323,6 +481,13 @@ export class DyFM_Array {
    * @param dataList - The data list to check.
    * @param byKey - The key to check for multiplications.
    * @returns True if the data list has multiplications, false otherwise.
+   * 
+   * @example 
+   * ```ts
+   * const list: { _id: number, name: string }[] = [ { _id: 1, name: 'John' }, { _id: 2, name: 'Jane' }, { _id: 1, name: 'Bob' } ];
+   * const result = DyFM_Array.haveMultiplications(list, '_id');
+   * console.log(result); // true
+   * ```
    */
   static haveMultiplications<T extends object>(dataList: T[], byKey: keyof T = '_id' as keyof T): boolean {
     return dataList.some((data: T, index: number): boolean => {
@@ -337,6 +502,13 @@ export class DyFM_Array {
    * @param dataList - The data list to filter.
    * @param byKey - The key to filter for multiplications.
    * @returns The filtered data list.
+   * 
+   * @example 
+   * ```ts
+   * const list: { _id: number, name: string }[] = [ { _id: 1, name: 'John' }, { _id: 2, name: 'Jane' }, { _id: 1, name: 'Bob' } ];
+   * const result = DyFM_Array.filterMultiplications(list, '_id');
+   * console.log(result); // [ { _id: 1, name: 'John' } , { _id: 2, name: 'Jane' } ]
+   * ```
    */
   static filterMultiplications<T extends object>(dataList: T[], byKey: keyof T = '_id' as keyof T): T[] {
     return dataList.filter((data: T, index: number): boolean => {
@@ -351,6 +523,13 @@ export class DyFM_Array {
    * @param dataList - The data list to gather multiplications from.
    * @param byKey - The key to gather multiplications from.
    * @returns The gathered multiplications.
+   * 
+   * @example 
+   * ```ts
+   * const list: { _id: number, name: string }[] = [ { _id: 1, name: 'John' }, { _id: 2, name: 'Jane' }, { _id: 1, name: 'Bob' } ];
+   * const result = DyFM_Array.gatherMultiplications(list, '_id');
+   * console.log(result); // [ [ { _id: 1, name: 'John' }, { _id: 1, name: 'Bob' } ] ]
+   * ```
    */
   static gatherMultiplications<T extends object>(dataList: T[], byKey: keyof T = '_id' as keyof T): T[][] {
     const multiplications: T[][] = [];
@@ -375,6 +554,15 @@ export class DyFM_Array {
    * @param array - The array to find the element in.
    * @param func - The function to apply to each element.
    * @returns The element found, or null if no element is found.
+   * 
+   * @example 
+   * ```ts
+   * const list: number[] = [ 1, 2, 3 ];
+   * const result = DyFM_Array.findFromEnd(list, (element: number, index?: number, array?: number[]): boolean => {
+   *   return element === 2;
+   * });
+   * console.log(result); // 2
+   * ```
    */
   static findFromEnd<T>(
     array: T[], 
@@ -395,6 +583,7 @@ export class DyFM_Array {
    * sorts so that the objects that have the value true for the checkFor function are at the beginning of the array
    * @param checkFor 
    * @returns 
+   * 
    */
   static getSortForTrueFn<T>(
     checkFor: (a: T) => boolean

package/src/_collections/utils/async.util.ts

@@ -10,6 +10,11 @@ export class DyFM_Async {
    * delays the execution of a function
    * @param ms 
    * @returns 
+   * 
+   * @example
+   * ```ts
+   * await DyFM_Async.wait(1000);
+   * ```
    */
   static wait(ms: number): Promise<void> {
     return new Promise((resolve): any => setTimeout(resolve, ms));
@@ -20,6 +25,11 @@ export class DyFM_Async {
   /** 
    * WARNING: This function is recommended to use ONLY for limited instances,
    * because it can cause performance issues.
+   * 
+   * @example
+   * ```ts
+   * await DyFM_Async.waitUntil(() => check(), 100, 10000);
+   * ```
    */
   static waitUntil(
     check: () => boolean, 
@@ -80,6 +90,14 @@ export class DyFM_Async {
 
   /**
    * Creates a promise that resolves when the observable emits a value that passes the check function
+   * 
+   * @example
+   * ```ts
+   * const observable = new Observable<number>(observer => {
+   *   setInterval(() => observer.next(Math.random()), 100);
+   * });
+   * const result = await DyFM_Async.takeUntil(observable, (value?: number) => value && value > 0.5);
+   * ```
    */
   static takeUntil<T>(
     observable: Observable<T>, 
@@ -97,6 +115,17 @@ export class DyFM_Async {
     });
   }
 
+  /**
+   * Waits for a given amount of time and logs the remaining time.
+   * @param totalWaitTimeMs - The total amount of time to wait.
+   * @param context - The context of the countdown.
+   * @returns A promise that resolves when the countdown is complete.
+   * 
+   * @example
+   * ```ts
+   * await DyFM_Async.waitWithCountdownLogging(1000, 'Countdown');
+   * ```
+   */
   static async waitWithCountdownLogging(
     totalWaitTimeMs: number,
     context: string = 'Countdown'
@@ -105,6 +134,17 @@ export class DyFM_Async {
     const endTime = startTime + totalWaitTimeMs;
     
     // Define logging intervals based on total duration
+    /**
+     * Gets the logging interval based on the total duration.
+     * @param totalMs - The total duration in milliseconds.
+     * @returns The logging interval in milliseconds.
+     * 
+     * @example
+     * ```ts
+     * const logInterval = getLogInterval(1000);
+     * console.log(logInterval); // 1000
+     * ```
+     */
     const getLogInterval = (totalMs: number): number => {
       const totalSeconds = totalMs / second;
       const totalMinutes = totalSeconds / 60;

package/src/_collections/utils/json-error-helper.util.ts

@@ -32,6 +32,12 @@ export class DyFM_JsonErrorHelper {
    * @param jsonInput - The original JSON input string
    * @param contextLines - Number of context lines to show before and after the error (default: 5)
    * @returns Object containing line number, context lines, and character position, or null if parsing fails
+   * 
+   * @example
+   * ```ts
+   * const lineInfo = DyFM_JsonErrorHelper.extractLineInfoFromJsonError('Expected property name or "}" in JSON at position 10', '{"name": "John", "age": 30}', 5);
+   * console.log(lineInfo); // { lineNumber: 1, contextLines: [ '{"name": "John", "age": 30}' ], characterPosition: 10 }
+   * ```
    */
   static extractLineInfoFromJsonError(
     errorMessage: string, 
@@ -86,6 +92,16 @@ export class DyFM_JsonErrorHelper {
 
   /**
    * Helper method to create line info from a character position
+   * @param jsonInput - The original JSON input string
+   * @param position - The character position where the error occurred
+   * @param contextLines - Number of context lines to show before and after the error (default: 5)
+   * @returns Object containing line number, context lines, and character position
+   * 
+   * @example
+   * ```ts
+   * const lineInfo = DyFM_JsonErrorHelper.createLineInfoFromPosition('{"name": "John", "age": 30}', 10, 5);
+   * console.log(lineInfo); // { lineNumber: 1, contextLines: [ '{"name": "John", "age": 30}' ], characterPosition: 10 }
+   * ```
    */
   private static createLineInfoFromPosition(
     jsonInput: string, 
@@ -152,6 +168,12 @@ export class DyFM_JsonErrorHelper {
    * @param lineInfo - The line information extracted from the error
    * @param errorMessage - The original error message
    * @returns Formatted error string for logging
+   * 
+   * @example
+   * ```ts
+   * const logLines = DyFM_JsonErrorHelper.formatJsonErrorForLogging({ lineNumber: 1, contextLines: [ '{"name": "John", "age": 30}' ], characterPosition: 10 }, 'Expected property name or "}" in JSON at position 10');
+   * console.log(logLines); // [ 'JSON parsing failed: Expected property name or "}" in JSON at position 10', 'Error at line 1, character 10:', 'Context (1 lines):', '    1: {"name": "John", "age": 30}' ]
+   * ```
    */
   static formatJsonErrorForLogging(
     lineInfo: JsonErrorLineInfo, 
@@ -185,6 +207,13 @@ export class DyFM_JsonErrorHelper {
    * @param contextLines - Number of context lines to show in error (default: 5)
    * @returns Parsed JSON object
    * @throws Error with detailed line information if parsing fails
+   * 
+   * @example
+   * ```ts
+   * const json = '{"name": "John", "age": 30}';
+   * const result = DyFM_JsonErrorHelper.parseJsonWithEnhancedError(json);
+   * console.log(result); // { name: 'John', age: 30 }
+   * ```
    */
   static parseJsonWithEnhancedError(
     jsonString: string, 
@@ -225,6 +254,7 @@ export class DyFM_JsonErrorHelper {
       
       if (lineInfo) {
         const formattedError = this.formatJsonErrorForLogging(lineInfo, errorMessage);
+        
         throw new Error(`JSON parsing failed:\n${formattedError.join('\n')}`);
       } else {
         // Fallback to simple error if we can't extract line info
@@ -235,6 +265,15 @@ export class DyFM_JsonErrorHelper {
 
   /**
    * Formats single-line JSON with line breaks for better error reporting
+   * @param jsonString - The JSON string to format
+   * @returns The formatted JSON string
+   * 
+   * @example
+   * ```ts
+   * const json = '{"name": "John", "age": 30, "city": "New York"}';
+   * const result = DyFM_JsonErrorHelper.formatJsonForBetterErrors(json);
+   * console.log(result); // '{\n  "name": "John",\n  "age": 30,\n  "city": "New York"\n}'
+   * ```
    */
   private static formatJsonForBetterErrors(jsonString: string): string {
     if (!jsonString || typeof jsonString !== 'string') {
@@ -248,14 +287,15 @@ export class DyFM_JsonErrorHelper {
       .replace(/\[/g, '[\n  ')
       .replace(/\]/g, '\n]')
       .replace(/\n\s*\n/g, '\n') // Remove double newlines
-      .replace(/^\s+|\s+$/gm, function(match, offset, string) {
+      .replace(/^\s+|\s+$/gm, function(match: string, offset: number, string: string): string {
         // Trim but preserve indentation structure
         if (!string || typeof string !== 'string') {
           return match;
         }
-        const lines = string.slice(0, offset).split('\n');
-        const depth = (string.slice(0, offset).match(/{|\[/g) || []).length - 
+        const lines: string[] = string.slice(0, offset).split('\n');
+        const depth: number = (string.slice(0, offset).match(/{|\[/g) || []).length - 
                      (string.slice(0, offset).match(/}|\]/g) || []).length;
+
         return '  '.repeat(Math.max(0, depth));
       });
   }