@futdevpro/fsm-dynamo 1.10.37 → 1.10.39

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

@@ -1,5 +1,3 @@
-
-
 import { DyFM_Paged } from '../../_models/interfaces/paged.interface';
 import { DyFM_Array } from './array.util';
 import { DyFM_delay } from './utilities.util';
@@ -8,9 +6,9 @@ describe('| DyFM_Array', (): void => {
 
   describe('| asyncForEach', (): void => {
     it('| should call the function for each element in the list', async (): Promise<void> => {
-      const list = [ 1, 2, 3 ];
-      const result = [];
-      const func = async (e, i): Promise<void> => { 
+      const list: number[] = [ 1, 2, 3 ];
+      const result: number[] = [];
+      const func = async (e: number, i?: number): Promise<void> => { 
         await DyFM_delay(30);
         result.push(e);
       };
@@ -23,9 +21,9 @@ describe('| DyFM_Array', (): void => {
 
   describe('| asyncMapArray', (): void => {
     it('| should call the function for each element in the list', async (): Promise<void> => {
-      const list = [ 1, 2, 3 ];
+      const list: number[] = [ 1, 2, 3 ];
       
-      const func = async (e, i): Promise<number> => { 
+      const func = async (e: number, i?: number): Promise<number> => { 
         await DyFM_delay(30);
 
         return e * 2;
@@ -39,8 +37,8 @@ describe('| DyFM_Array', (): void => {
   
   describe('| shuffle', () => {
     it('| should shuffle the elements in the array', () => {
-      const inputArray = [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ];
-      const shuffledArray = [ ...inputArray ];
+      const inputArray: number[] = [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ];
+      const shuffledArray: number[] = [ ...inputArray ];
 
       DyFM_Array.shuffle(shuffledArray);
 
@@ -67,8 +65,8 @@ describe('| DyFM_Array', (): void => {
   });
   
   describe('| page function', () => {
-    const array = [ 1, 2, 3, 4, 5, 6, 7, 8 ];
-    const pageSize = 2;
+    const array: number[] = [ 1, 2, 3, 4, 5, 6, 7, 8 ];
+    const pageSize: number = 2;
 
     it('| should return the correct page of items based on pageIndex and pageSize', () => {
       expect(DyFM_Array.page(array, 0, pageSize)).toEqual([ 1, 2 ]);
@@ -85,9 +83,9 @@ describe('| DyFM_Array', (): void => {
   
   describe('| paged function', () => {
     it('| should return a paginated array', () => {
-      const array = [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ];
-      const pageIndex = 1;
-      const pageSize = 4;
+      const array: number[] = [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ];
+      const pageIndex: number = 1;
+      const pageSize: number = 4;
       const expected: DyFM_Paged<any> = {
         pageIndex: 1,
         pageSize: 4,
@@ -102,9 +100,9 @@ describe('| DyFM_Array', (): void => {
     });
     
     it('| should handle edge cases like empty array', () => {
-      const array = [];
-      const pageIndex = 1;
-      const pageSize = 5;
+      const array: number[] = [];
+      const pageIndex: number = 1;
+      const pageSize: number = 5;
       const expected: DyFM_Paged<any> = {
         pageIndex: 1,
         pageSize: 5,
@@ -121,18 +119,18 @@ describe('| DyFM_Array', (): void => {
   
   describe('| swap function test', () => {
     it('| should swap elements in the array correctly', () => {
-      const array = [ 1, 2, 3, 4 ];
-      const indexA = 0;
-      const indexB = 2;
-      const expectedArray = [ 3, 2, 1, 4 ];
+      const array: number[] = [ 1, 2, 3, 4 ];
+      const indexA: number = 0;
+      const indexB: number = 2;
+      const expectedArray: number[] = [ 3, 2, 1, 4 ];
 
       expect(DyFM_Array.swap(array, indexA, indexB)).toEqual(expectedArray);
     });
 
     it('| should return the same array if same indexes are provided', () => {
-      const array = [ 1, 2, 3, 4 ];
-      const indexA = 0;
-      const indexB = 0;
+      const array: number[] = [ 1, 2, 3, 4 ];
+      const indexA: number = 0;
+      const indexB: number = 0;
 
       expect(DyFM_Array.swap(array, indexA, indexB)).toEqual(array);
     });
@@ -142,11 +140,11 @@ describe('| DyFM_Array', (): void => {
 
   describe('| stringListHasMultiplications', () => {
     it('| should return true if input string array contains duplicates', () => {
-      const input1 = [ 'apple', 'banana', 'apple', 'orange' ];
+      const input1: string[] = [ 'apple', 'banana', 'apple', 'orange' ];
 
       expect(DyFM_Array.stringListHasMultiplications(input1)).toBe(true);
   
-      const input2 = [ 'apple', 'banana', 'orange' ];
+      const input2: string[] = [ 'apple', 'banana', 'orange' ];
 
       expect(DyFM_Array.stringListHasMultiplications(input2)).toBe(false);
     });
@@ -154,8 +152,8 @@ describe('| DyFM_Array', (): void => {
 
   describe('| filterStringMultiplications', () => {
     xit('should return an array with duplicates filtered out', () => {
-      const inputList = [ 'abc', 'def', 'abc', 'ghi', 'abc' ];
-      const expectedOutput = [ 'abc' ];
+      const inputList: string[] = [ 'abc', 'def', 'abc', 'ghi', 'abc' ];
+      const expectedOutput: string[] = [ 'abc' ];
 
       const result = DyFM_Array.filterStringMultiplications(inputList);
 
@@ -163,7 +161,7 @@ describe('| DyFM_Array', (): void => {
     });
 
     it('| should return an empty array if no duplicates are present', () => {
-      const inputList = [ 'abc', 'def', 'ghi' ];
+      const inputList: string[] = [ 'abc', 'def', 'ghi' ];
       const expectedOutput: string[] = [];
 
       const result = DyFM_Array.filterStringMultiplications(inputList);
@@ -183,15 +181,15 @@ describe('| DyFM_Array', (): void => {
 
   describe('| gatherStringMultiplications', () => {
     it('| should return an array of arrays containing duplicated strings', () => {
-      const input = [ 'apple', 'banana', 'apple', 'cherry', 'banana', 'banana' ];
-      const expectedOutput = [[ 'apple', 'apple' ], [ 'banana', 'banana', 'banana' ]];
+      const input: string[] = [ 'apple', 'banana', 'apple', 'cherry', 'banana', 'banana' ];
+      const expectedOutput: string[][] = [[ 'apple', 'apple' ], [ 'banana', 'banana', 'banana' ]];
 
       expect(DyFM_Array.gatherStringMultiplications(input)).toEqual(expectedOutput);
     });
   
     it('| should return an empty array for no duplicated strings', () => {
-      const input = [ 'apple', 'banana', 'cherry' ];
-      const expectedOutput = [];
+      const input: string[] = [ 'apple', 'banana', 'cherry' ];
+      const expectedOutput: string[][] = [];
 
       expect(DyFM_Array.gatherStringMultiplications(input)).toEqual(expectedOutput);
     });
@@ -208,7 +206,7 @@ describe('| DyFM_Array', (): void => {
   
   describe('| haveMultiplications', () => {
     it('| should return true if dataList contains any duplicate entry based on the given key', () => {
-      const dataList = [
+      const dataList: { _id: number, name: string }[] = [
         { _id: 1, name: 'John' },
         { _id: 2, name: 'Jane' },
         { _id: 3, name: 'Alice' },
@@ -221,7 +219,7 @@ describe('| DyFM_Array', (): void => {
     });
 
     it('| should return false if dataList does not contain any duplicate entry based on the given key', () => {
-      const dataList = [
+      const dataList: { _id: number, name: string }[] = [
         { _id: 1, name: 'John' },
         { _id: 2, name: 'Jane' },
         { _id: 3, name: 'Alice' },
@@ -236,7 +234,7 @@ describe('| DyFM_Array', (): void => {
 
   describe('| filterMultiplications', () => {
     xit('should filter out duplicate items based on the specified key', () => {
-      const dataList = [
+      const dataList: { _id: number, name: string }[] = [
         { _id: 1, name: 'Alice' },
         { _id: 2, name: 'Bob' },
         { _id: 1, name: 'Charlie' },
@@ -256,7 +254,7 @@ describe('| DyFM_Array', (): void => {
     });
 
     it('| should return an empty array if no duplicates are found', () => {
-      const dataList = [
+      const dataList: { _id: number, name: string }[] = [
         { _id: 1, name: 'Alice' },
         { _id: 2, name: 'Bob' },
         { _id: 3, name: 'Charlie' },
@@ -278,7 +276,7 @@ describe('| DyFM_Array', (): void => {
 
   describe('| gatherMultiplications', () => {
     it('| should gather multiplications based on the specified key', () => {
-      const dataList = [
+      const dataList: { _id: number, name: string }[] = [
         { _id: 1, name: 'Alice' },
         { _id: 2, name: 'Bob' },
         { _id: 1, name: 'Charlie' },

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

@@ -7,6 +7,12 @@ export type DyFM_List = DyFM_Array;
 
 export class DyFM_Array {  
 
+  /**
+   * Asynchronously iterates over an array and applies a function to each element.
+   * @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.
+   */
   static async asyncForEach<T>(
     list: T[], 
     func: (element: T, index?: number, array?: T[]) => Promise<void>
@@ -16,6 +22,13 @@ export class DyFM_Array {
     }
   }
 
+  /**
+   * Asynchronously iterates over an array and applies a function to each element, returning a single result.
+   * @param startData - The initial data to pass to the function.
+   * @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.
+   */
   static async asyncForEachReturnToOne<T, K>(
     startData: K,
     list: T[], 
@@ -30,6 +43,12 @@ export class DyFM_Array {
     return result;
   }
 
+  /**
+   * Asynchronously iterates over an array and applies a function to each element, returning an array of results.
+   * @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.
+   */
   static async asyncForEachReturnToAll<T, K>(
     list: T[], 
     func: (element: T, index?: number, array?: T[]) => Promise<K>
@@ -43,6 +62,12 @@ export class DyFM_Array {
     return resultList;
   }
 
+  /**
+   * Asynchronously iterates over an array and applies a function to each element, returning an array of results.
+   * @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.
+   */
   static async asyncForEachAllAtOnce<T, R>(
     list: T[], 
     func: (element: T, index?: number, array?: T[]) => Promise<R>
@@ -50,6 +75,12 @@ export class DyFM_Array {
     return await Promise.all(list.map(func));
   }
 
+  /**
+   * Asynchronously filters an array based on a function.
+   * @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.
+   */
   static async asyncFilter<T>(
     list: T[], 
     filterFunc: (element: T, index?: number, array?: T[]) => Promise<boolean>
@@ -64,7 +95,13 @@ export class DyFM_Array {
 
     return resultList;
   }
-  
+
+  /**
+   * Asynchronously maps an array based on a function.
+   * @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.
+   */
   static async asyncMap<T, R>(
     list: T[], 
     mapFunc: (element: T, index?: number, array?: T[]) => Promise<R>
@@ -78,18 +115,39 @@ export class DyFM_Array {
     return resultList;
   }
 
-  static last<T>(array: T[]): T {
+  /**
+   * 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.
+   */
+  static last<T>(array: T[]): T | null {
     return array?.length ? array[array.length - 1] : null;
   }
 
-  static lastString(array: string): string {
-    return array?.length ? array[array.length - 1] : null;
+  /**
+   * 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.
+   */
+  static lastCharacter(string: string): string | null {
+    return string?.length ? string[string.length - 1] : null;
   }
 
-  static first<T>(array: T[]): T {
+  /**
+   * 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.
+   */
+  static first<T>(array: T[]): T | null {
     return array?.length ? array[0] : null;
   }
 
+  /**
+   * Removes an element from an 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.
+   */
   static remove<T>(array: T[], element: T): T[] {
     const index = array.indexOf(element);
 
@@ -100,6 +158,12 @@ export class DyFM_Array {
     return array;
   }
 
+  /**
+   * Finds an element in an array and removes it.
+   * @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.
+   */
   static findNRemove<T>(
     array: T[], 
     func: (element: T, index?: number, array?: T[]) => boolean
@@ -113,6 +177,11 @@ export class DyFM_Array {
     return array;
   }
 
+  /**
+   * Shuffles an array.
+   * @param array - The array to shuffle.
+   * @returns The shuffled array.
+   */
   static shuffle<T>(array: T[]): T[] {
     let currentIndex = array.length;
     let randomIndex: number;
@@ -127,10 +196,24 @@ export class DyFM_Array {
     return array;
   }
 
+  /**
+   * Pages an array.
+   * @param array - The array to page.
+   * @param pageIndex - The index of the page to return.
+   * @param pageSize - The size of the page.
+   * @returns The page of the array.
+   */
   static page<T>(array: T[], pageIndex: number, pageSize: number): T[] {
     return array.slice(pageIndex * pageSize, (pageIndex + 1) * pageSize);
   }
 
+  /**
+   * Pages an array.
+   * @param array - The array to page.
+   * @param pageIndex - The index of the page to return.
+   * @param pageSize - The size of the page.
+   * @returns The page of the array.
+   */
   static paged<T>(array: T[], pageIndex: number, pageSize: number): DyFM_Paged<T> {
     return {
       pageIndex,
@@ -141,26 +224,48 @@ export class DyFM_Array {
     };
   }
 
+  /**
+   * Swaps two elements in an array.
+   * @param array - The array to swap the elements in.
+   * @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.
+   */
   static swap<T>(array: T[], indexA: number, indexB: number): T[] {
     [ array[indexA], array[indexB] ] = [ array[indexB], array[indexA] ];
     
     return 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.
+   */
   static stringListHasMultiplications(stringList: string[]): boolean {
     return stringList.some((str: string, index: number): boolean => {
       return stringList.findIndex((strItem: string): boolean => strItem === str) !== index;
     });
   }
 
+  /**
+   * Filters a string list to remove multiplications.
+   * @param stringList - The string list to filter.
+   * @returns The filtered string list.
+   */
   static filterStringMultiplications(stringList: string[]): string[] {
     return stringList.filter((str: string, index: number): boolean => {
       return stringList.findIndex((strItem: string): boolean => strItem === str) !== index;
     });
   }
 
+  /**
+   * Gathers multiplications from a string list.
+   * @param stringList - The string list to gather multiplications from.
+   * @returns The gathered multiplications.
+   */
   static gatherStringMultiplications(stringList: string[]): string[][] {
-    const multiplications = [];
+    const multiplications: string[][] = [];
 
     stringList.forEach((str: string, index: number): void => {
       if (multiplications.find(
@@ -179,7 +284,13 @@ export class DyFM_Array {
     return multiplications;
   }
 
-  static haveMultiplications<T extends object>(dataList: T[], byKey: string = '_id'): boolean {
+  /**
+   * Checks if a data list has multiplications.
+   * @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.
+   */
+  static haveMultiplications<T extends object>(dataList: T[], byKey: keyof T = '_id' as keyof T): boolean {
     return dataList.some((data: T, index: number): boolean => {
       return dataList.findIndex(
         (listItem: T): boolean => listItem[byKey] === data[byKey]
@@ -187,7 +298,13 @@ export class DyFM_Array {
     });
   }
 
-  static filterMultiplications<T extends object>(dataList: T[], byKey: string = '_id'): T[] {
+  /**
+   * Filters a data list to remove multiplications.
+   * @param dataList - The data list to filter.
+   * @param byKey - The key to filter for multiplications.
+   * @returns The filtered data list.
+   */
+  static filterMultiplications<T extends object>(dataList: T[], byKey: keyof T = '_id' as keyof T): T[] {
     return dataList.filter((data: T, index: number): boolean => {
       return dataList.findIndex(
         (listItem: T): boolean => listItem[byKey] === data[byKey]
@@ -195,8 +312,14 @@ export class DyFM_Array {
     });
   }
 
-  static gatherMultiplications<T extends object>(dataList: T[], byKey: string = '_id'): T[][] {
-    const multiplications = [];
+  /**
+   * Gathers multiplications from a data list.
+   * @param dataList - The data list to gather multiplications from.
+   * @param byKey - The key to gather multiplications from.
+   * @returns The gathered multiplications.
+   */
+  static gatherMultiplications<T extends object>(dataList: T[], byKey: keyof T = '_id' as keyof T): T[][] {
+    const multiplications: T[][] = [];
 
     dataList.forEach((data: T, index: number): void => {
       if (multiplications.find((multiplication: T[]): boolean => multiplication.includes(data))) {
@@ -213,14 +336,25 @@ export class DyFM_Array {
     return multiplications;
   } 
 
-  static findFromEnd<T>(array: T[], func: (element: T, index?: number, array?: T[]) => boolean): T {
+  /**
+   * Finds an element in an array from the end.
+   * @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.
+   */
+  static findFromEnd<T>(
+    array: T[], 
+    func: (element: T, index?: number, 
+    array?: T[]) => boolean
+  ): T | null {
     for (let i = array.length - 1; i >= 0; i--) {
       if (func(array[i], i, array)) {
         return array[i];
       }
     }
-  }
 
+    return null;
+  }
 }