@ls-stack/utils 3.40.0 → 3.42.0

package/dist/arrayUtils.d.cts

@@ -1,27 +1,26 @@
 /**
- * allow to filter and map with better typing ergonomics
+ * Allow to filter and map with better typing ergonomics
  *
  * In the `mapFilter` function return `false` to reject the item, or any other
  * value to map it.
  *
- * @param array
- * @param mapFilter
  * @example
- * // Filter reject and turn value into `value mapped`
- * const items = ['value', 'value', 'reject', 'reject'];
+ *   // Filter reject and turn value into `value mapped`
+ *   const items = ['value', 'value', 'reject', 'reject'];
+ *
+ *   const mappedItems = filterAndMap(items, (item) =>
+ *     item === 'reject' ? false : `${item} mapped`,
+ *   );
  *
- * const mappedItems = filterAndMap(items, (item) =>
- *   item === 'reject'
- *     ? false
- *     : `${item} mapped`,
- * );
+ *   mappedItems; // ['value mapped', 'value mapped']
  *
- * mappedItems; // ['value mapped', 'value mapped']
+ * @param array
+ * @param mapFilter
  */
 declare function filterAndMap<T, R>(array: IterableIterator<T> | readonly T[], mapFilter: (item: T, index: number) => false | R): R[];
 type FilterAndMapReturn<T> = false | T;
 type SortOrder = 'desc' | 'asc';
-type SortByValue<T> = (item: T) => (number | string)[] | number | string;
+type SortByValueFn<T> = (item: T) => (number | string)[] | number | string;
 type SortByProps = {
     order?: SortOrder | SortOrder[];
 } | SortOrder | SortOrder[];
@@ -32,37 +31,42 @@ type SortByProps = {
  *
  * Use `Infinity` as as wildcard to absolute max and min values
  *
- * @param arr
- * @param sortByValue
- * @param props
  * @example
- * const items = [1, 3, 2, 4];
+ *   const items = [1, 3, 2, 4];
+ *
+ *   const sortedItems = sortBy(items, (item) => item);
+ *   // [1, 2, 3, 4]
  *
- * const sortedItems = sortBy(items, (item) => item);
- * // [1, 2, 3, 4]
+ *   const items2 = [
+ *     { a: 1, b: 2 },
+ *     { a: 2, b: 1 },
+ *     { a: 1, b: 1 },
+ *   ];
  *
- * const items2 = [{ a: 1, b: 2 }, { a: 2, b: 1 }, { a: 1, b: 1}]
+ *   // return a array to sort by multiple values
+ *   const sortedItems = sortBy(items, (item) => [item.a, item.b]);
  *
- * // return a array to sort by multiple values
- * const sortedItems = sortBy(items, (item) => [item.a, item.b]);
+ * @param arr
+ * @param sortByValue
+ * @param props
  */
-declare function sortBy<T>(arr: T[], sortByValue: SortByValue<T>, props?: SortByProps): T[];
+declare function sortBy<T>(arr: T[], sortByValue: SortByValueFn<T>, props?: SortByProps): T[];
 /**
  * Get the correct 0 based value for sync with other array in ascending order
  *
- * @param index
- *
  * @example
- * ```ts
- * const items = [1, 2, 3];
- *
- * const index = sortBy(
- *   items,
- *   (item) => getAscIndexOrder(
- *     followOrder.findIndex((order) => order === item)
- *   )
- * );
- * ```
+ *   ```ts
+ *   const items = [1, 2, 3];
+ *
+ *   const index = sortBy(
+ *     items,
+ *     (item) => getAscIndexOrder(
+ *       followOrder.findIndex((order) => order === item)
+ *     )
+ *   );
+ *   ```;
+ *
+ * @param index
  */
 declare function getAscIndexOrder(index: number | undefined): number;
 declare function arrayWithPrev<T>(array: T[]): [current: T, prev: T | null][];
@@ -82,50 +86,59 @@ type ArrayOps<T> = {
     /**
      * Filter and map an array
      *
-     * @param mapFilter - A function that takes an item and returns a value or `false`
-     * to reject the item.
      * @example
-     * const items = [1, 2, 3];
+     *   const items = [1, 2, 3];
+     *
+     *   const enhancedItems = arrayOps(items);
      *
-     * const enhancedItems = arrayOps(items);
+     *   enhancedItems.filterAndMap((item) => (item === 2 ? false : item));
      *
-     * enhancedItems.filterAndMap((item) => item === 2 ? false : item);
+     * @param mapFilter - A function that takes an item and returns a value or
+     *   `false` to reject the item.
      */
     filterAndMap: <R>(mapFilter: (item: T, index: number) => false | R) => R[];
-    sortBy: (sortByValue: SortByValue<T>, props: SortByProps) => T[];
+    sortBy: (sortByValue: SortByValueFn<T>, props: SortByProps) => T[];
     rejectDuplicates: (getKey: (item: T) => unknown) => T[];
     findAndMap: <R>(predicate: (value: T) => R | false) => R | undefined;
 };
 /**
- * Finds the first item in an array where the predicate returns a non-false value and returns that mapped value.
+ * Finds the first item in an array where the predicate returns a non-false
+ * value and returns that mapped value.
  *
- * Combines find and map operations - applies the predicate to each item until one returns
- * a value that is not `false`, then returns that mapped value. If no item matches, returns `undefined`.
+ * Combines find and map operations - applies the predicate to each item until
+ * one returns a value that is not `false`, then returns that mapped value. If
+ * no item matches, returns `undefined`.
  *
- * @param array - The array to search through
- * @param predicate - Function that returns a mapped value or `false` to skip the item
- * @returns The first mapped value that is not `false`, or `undefined` if no item matches
  * @example
- * const users = [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }];
+ *   const users = [
+ *     { id: 1, name: 'Alice' },
+ *     { id: 2, name: 'Bob' },
+ *   ];
+ *
+ *   const foundName = findAndMap(users, (user) =>
+ *     user.id === 2 ? user.name.toUpperCase() : false,
+ *   );
+ *   // foundName is 'BOB'
  *
- * const foundName = findAndMap(users, (user) =>
- *   user.id === 2 ? user.name.toUpperCase() : false
- * );
- * // foundName is 'BOB'
+ * @param array - The array to search through
+ * @param predicate - Function that returns a mapped value or `false` to skip
+ *   the item
+ * @returns The first mapped value that is not `false`, or `undefined` if no
+ *   item matches
  */
 declare function findAndMap<T, R>(array: T[], predicate: (value: T) => R | false): R | undefined;
 /**
  * Enhance an array with extra methods
  *
- * @param array
  * @example
+ *   const enhancedItems = arrayOps(array);
  *
- * const enhancedItems = arrayOps(array);
+ *   enhancedItems.filterAndMap((item) => (item === 2 ? false : item));
+ *   enhancedItems.sortBy((item) => item);
+ *   enhancedItems.rejectDuplicates((item) => item);
  *
- * enhancedItems.filterAndMap((item) => item === 2 ? false : item);
- * enhancedItems.sortBy((item) => item);
- * enhancedItems.rejectDuplicates((item) => item);
+ * @param array
  */
 declare function arrayOps<T>(array: T[]): ArrayOps<T>;
 
-export { type FilterAndMapReturn, arrayOps, arrayWithPrev, arrayWithPrevAndIndex, filterAndMap, findAfterIndex, findAndMap, findBeforeIndex, getAscIndexOrder, hasDuplicates, isInArray, rejectArrayUndefinedValues, rejectDuplicates, sortBy, truncateArray };
+export { type FilterAndMapReturn, type SortByProps, type SortByValueFn, arrayOps, arrayWithPrev, arrayWithPrevAndIndex, filterAndMap, findAfterIndex, findAndMap, findBeforeIndex, getAscIndexOrder, hasDuplicates, isInArray, rejectArrayUndefinedValues, rejectDuplicates, sortBy, truncateArray };

package/dist/arrayUtils.d.ts

@@ -1,27 +1,26 @@
 /**
- * allow to filter and map with better typing ergonomics
+ * Allow to filter and map with better typing ergonomics
  *
  * In the `mapFilter` function return `false` to reject the item, or any other
  * value to map it.
  *
- * @param array
- * @param mapFilter
  * @example
- * // Filter reject and turn value into `value mapped`
- * const items = ['value', 'value', 'reject', 'reject'];
+ *   // Filter reject and turn value into `value mapped`
+ *   const items = ['value', 'value', 'reject', 'reject'];
+ *
+ *   const mappedItems = filterAndMap(items, (item) =>
+ *     item === 'reject' ? false : `${item} mapped`,
+ *   );
  *
- * const mappedItems = filterAndMap(items, (item) =>
- *   item === 'reject'
- *     ? false
- *     : `${item} mapped`,
- * );
+ *   mappedItems; // ['value mapped', 'value mapped']
  *
- * mappedItems; // ['value mapped', 'value mapped']
+ * @param array
+ * @param mapFilter
  */
 declare function filterAndMap<T, R>(array: IterableIterator<T> | readonly T[], mapFilter: (item: T, index: number) => false | R): R[];
 type FilterAndMapReturn<T> = false | T;
 type SortOrder = 'desc' | 'asc';
-type SortByValue<T> = (item: T) => (number | string)[] | number | string;
+type SortByValueFn<T> = (item: T) => (number | string)[] | number | string;
 type SortByProps = {
     order?: SortOrder | SortOrder[];
 } | SortOrder | SortOrder[];
@@ -32,37 +31,42 @@ type SortByProps = {
  *
  * Use `Infinity` as as wildcard to absolute max and min values
  *
- * @param arr
- * @param sortByValue
- * @param props
  * @example
- * const items = [1, 3, 2, 4];
+ *   const items = [1, 3, 2, 4];
+ *
+ *   const sortedItems = sortBy(items, (item) => item);
+ *   // [1, 2, 3, 4]
  *
- * const sortedItems = sortBy(items, (item) => item);
- * // [1, 2, 3, 4]
+ *   const items2 = [
+ *     { a: 1, b: 2 },
+ *     { a: 2, b: 1 },
+ *     { a: 1, b: 1 },
+ *   ];
  *
- * const items2 = [{ a: 1, b: 2 }, { a: 2, b: 1 }, { a: 1, b: 1}]
+ *   // return a array to sort by multiple values
+ *   const sortedItems = sortBy(items, (item) => [item.a, item.b]);
  *
- * // return a array to sort by multiple values
- * const sortedItems = sortBy(items, (item) => [item.a, item.b]);
+ * @param arr
+ * @param sortByValue
+ * @param props
  */
-declare function sortBy<T>(arr: T[], sortByValue: SortByValue<T>, props?: SortByProps): T[];
+declare function sortBy<T>(arr: T[], sortByValue: SortByValueFn<T>, props?: SortByProps): T[];
 /**
  * Get the correct 0 based value for sync with other array in ascending order
  *
- * @param index
- *
  * @example
- * ```ts
- * const items = [1, 2, 3];
- *
- * const index = sortBy(
- *   items,
- *   (item) => getAscIndexOrder(
- *     followOrder.findIndex((order) => order === item)
- *   )
- * );
- * ```
+ *   ```ts
+ *   const items = [1, 2, 3];
+ *
+ *   const index = sortBy(
+ *     items,
+ *     (item) => getAscIndexOrder(
+ *       followOrder.findIndex((order) => order === item)
+ *     )
+ *   );
+ *   ```;
+ *
+ * @param index
  */
 declare function getAscIndexOrder(index: number | undefined): number;
 declare function arrayWithPrev<T>(array: T[]): [current: T, prev: T | null][];
@@ -82,50 +86,59 @@ type ArrayOps<T> = {
     /**
      * Filter and map an array
      *
-     * @param mapFilter - A function that takes an item and returns a value or `false`
-     * to reject the item.
      * @example
-     * const items = [1, 2, 3];
+     *   const items = [1, 2, 3];
+     *
+     *   const enhancedItems = arrayOps(items);
      *
-     * const enhancedItems = arrayOps(items);
+     *   enhancedItems.filterAndMap((item) => (item === 2 ? false : item));
      *
-     * enhancedItems.filterAndMap((item) => item === 2 ? false : item);
+     * @param mapFilter - A function that takes an item and returns a value or
+     *   `false` to reject the item.
      */
     filterAndMap: <R>(mapFilter: (item: T, index: number) => false | R) => R[];
-    sortBy: (sortByValue: SortByValue<T>, props: SortByProps) => T[];
+    sortBy: (sortByValue: SortByValueFn<T>, props: SortByProps) => T[];
     rejectDuplicates: (getKey: (item: T) => unknown) => T[];
     findAndMap: <R>(predicate: (value: T) => R | false) => R | undefined;
 };
 /**
- * Finds the first item in an array where the predicate returns a non-false value and returns that mapped value.
+ * Finds the first item in an array where the predicate returns a non-false
+ * value and returns that mapped value.
  *
- * Combines find and map operations - applies the predicate to each item until one returns
- * a value that is not `false`, then returns that mapped value. If no item matches, returns `undefined`.
+ * Combines find and map operations - applies the predicate to each item until
+ * one returns a value that is not `false`, then returns that mapped value. If
+ * no item matches, returns `undefined`.
  *
- * @param array - The array to search through
- * @param predicate - Function that returns a mapped value or `false` to skip the item
- * @returns The first mapped value that is not `false`, or `undefined` if no item matches
  * @example
- * const users = [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }];
+ *   const users = [
+ *     { id: 1, name: 'Alice' },
+ *     { id: 2, name: 'Bob' },
+ *   ];
+ *
+ *   const foundName = findAndMap(users, (user) =>
+ *     user.id === 2 ? user.name.toUpperCase() : false,
+ *   );
+ *   // foundName is 'BOB'
  *
- * const foundName = findAndMap(users, (user) =>
- *   user.id === 2 ? user.name.toUpperCase() : false
- * );
- * // foundName is 'BOB'
+ * @param array - The array to search through
+ * @param predicate - Function that returns a mapped value or `false` to skip
+ *   the item
+ * @returns The first mapped value that is not `false`, or `undefined` if no
+ *   item matches
  */
 declare function findAndMap<T, R>(array: T[], predicate: (value: T) => R | false): R | undefined;
 /**
  * Enhance an array with extra methods
  *
- * @param array
  * @example
+ *   const enhancedItems = arrayOps(array);
  *
- * const enhancedItems = arrayOps(array);
+ *   enhancedItems.filterAndMap((item) => (item === 2 ? false : item));
+ *   enhancedItems.sortBy((item) => item);
+ *   enhancedItems.rejectDuplicates((item) => item);
  *
- * enhancedItems.filterAndMap((item) => item === 2 ? false : item);
- * enhancedItems.sortBy((item) => item);
- * enhancedItems.rejectDuplicates((item) => item);
+ * @param array
  */
 declare function arrayOps<T>(array: T[]): ArrayOps<T>;
 
-export { type FilterAndMapReturn, arrayOps, arrayWithPrev, arrayWithPrevAndIndex, filterAndMap, findAfterIndex, findAndMap, findBeforeIndex, getAscIndexOrder, hasDuplicates, isInArray, rejectArrayUndefinedValues, rejectDuplicates, sortBy, truncateArray };
+export { type FilterAndMapReturn, type SortByProps, type SortByValueFn, arrayOps, arrayWithPrev, arrayWithPrevAndIndex, filterAndMap, findAfterIndex, findAndMap, findBeforeIndex, getAscIndexOrder, hasDuplicates, isInArray, rejectArrayUndefinedValues, rejectDuplicates, sortBy, truncateArray };