@ls-stack/utils 3.65.0 → 3.66.0

package/dist/{arrayUtils.d.cts → arrayUtils.d.mts}

@@ -1,3 +1,4 @@
+//#region src/arrayUtils.d.ts
 /**
  * Allow to filter and map with better typing ergonomics
  *
@@ -22,7 +23,7 @@ type FilterAndMapReturn<T> = false | T;
 type SortOrder = 'desc' | 'asc';
 type SortByValueFn<T> = (item: T) => (number | string)[] | number | string;
 type SortByProps = {
-    order?: SortOrder | SortOrder[];
+  order?: SortOrder | SortOrder[];
 } | SortOrder | SortOrder[];
 /**
  * Sort an array based on a value
@@ -71,9 +72,9 @@ declare function sortBy<T>(arr: T[], sortByValue: SortByValueFn<T>, props?: Sort
 declare function getAscIndexOrder(index: number | undefined): number;
 declare function arrayWithPrev<T>(array: T[]): [current: T, prev: T | null][];
 declare function arrayWithPrevAndIndex<T>(array: T[]): {
-    item: T;
-    prev: T | null;
-    index: number;
+  item: T;
+  prev: T | null;
+  index: number;
 }[];
 declare function isInArray<T, const U extends T>(value: T, oneOf: readonly U[]): value is U;
 declare function isInArrayWithoutNarrowing<T, const U extends T>(value: T, oneOf: readonly U[]): boolean;
@@ -111,23 +112,23 @@ declare function truncateArray<T>(array: T[], maxLength: number, appendIfTruncat
  */
 declare function findAndMap<T, R>(array: T[], predicate: (value: T) => R | false): R | undefined;
 type ArrayOps<T> = {
-    /**
-     * Filter and map an array
-     *
-     * @example
-     *   const items = [1, 2, 3];
-     *
-     *   const enhancedItems = arrayOps(items);
-     *
-     *   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: SortByValueFn<T>, props: SortByProps) => T[];
-    rejectDuplicates: (getKey: (item: T) => unknown) => T[];
-    findAndMap: <R>(predicate: (value: T) => R | false) => R | undefined;
+  /**
+   * Filter and map an array
+   *
+   * @example
+   *   const items = [1, 2, 3];
+   *
+   *   const enhancedItems = arrayOps(items);
+   *
+   *   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: SortByValueFn<T>, props: SortByProps) => T[];
+  rejectDuplicates: (getKey: (item: T) => unknown) => T[];
+  findAndMap: <R>(predicate: (value: T) => R | false) => R | undefined;
 };
 /**
  * Enhance an array with extra methods
@@ -167,5 +168,5 @@ declare function intersperse<T, I>(array: T[], separator: I): (T | I)[];
  * @returns A new array with the repeated values
  */
 declare function repeat<T>(value: T, count: number, separator?: T): T[];
-
-export { type FilterAndMapReturn, type SortByProps, type SortByValueFn, arrayOps, arrayWithPrev, arrayWithPrevAndIndex, filterAndMap, findAfterIndex, findAndMap, findBeforeIndex, getAscIndexOrder, hasDuplicates, intersperse, isInArray, isInArrayWithoutNarrowing, looseIsInArray, rejectArrayUndefinedValues, rejectDuplicates, repeat, sortBy, truncateArray };
+//#endregion
+export { FilterAndMapReturn, SortByProps, SortByValueFn, arrayOps, arrayWithPrev, arrayWithPrevAndIndex, filterAndMap, findAfterIndex, findAndMap, findBeforeIndex, getAscIndexOrder, hasDuplicates, intersperse, isInArray, isInArrayWithoutNarrowing, looseIsInArray, rejectArrayUndefinedValues, rejectDuplicates, repeat, sortBy, truncateArray };

package/dist/arrayUtils.mjs

@@ -0,0 +1,249 @@
+import { a as isFunction } from "./assertions-qMxfVhSu.mjs";
+
+//#region src/arrayUtils.ts
+/**
+* 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.
+*
+* @example
+*   // Filter reject and turn value into `value mapped`
+*   const items = ['value', 'value', 'reject', 'reject'];
+*
+*   const mappedItems = filterAndMap(items, (item) =>
+*     item === 'reject' ? false : `${item} mapped`,
+*   );
+*
+*   mappedItems; // ['value mapped', 'value mapped']
+*
+* @param array
+* @param mapFilter
+*/
+function filterAndMap(array, mapFilter) {
+	const result = [];
+	let i = -1;
+	for (const item of array) {
+		i += 1;
+		const filterResult = mapFilter(item, i);
+		if (filterResult !== false) result.push(filterResult);
+	}
+	return result;
+}
+/**
+* Sort an array based on a value
+*
+* Sort by `ascending` order by default
+*
+* Use `Infinity` as as wildcard to absolute max and min values
+*
+* @example
+*   const items = [1, 3, 2, 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 },
+*   ];
+*
+*   // return a array to sort by multiple values
+*   const sortedItems = sortBy(items, (item) => [item.a, item.b]);
+*
+* @param arr
+* @param sortByValue
+* @param props
+*/
+function sortBy(arr, sortByValue, props = "asc") {
+	const order = Array.isArray(props) || typeof props === "string" ? props : props.order ?? "asc";
+	return [...arr].sort((a, b) => {
+		const _aPriority = sortByValue(a);
+		const _bPriority = sortByValue(b);
+		const aPriority = Array.isArray(_aPriority) ? _aPriority : [_aPriority];
+		const bPriority = Array.isArray(_bPriority) ? _bPriority : [_bPriority];
+		for (let i = 0; i < aPriority.length; i++) {
+			const levelOrder = typeof order === "string" ? order : order[i] ?? "asc";
+			const aP = aPriority[i] ?? 0;
+			const bP = bPriority[i] ?? 0;
+			if (aP === bP) continue;
+			if (bP === Infinity || aP === -Infinity || aP < bP) return levelOrder === "asc" ? -1 : 1;
+			if (aP === Infinity || bP === -Infinity || aP > bP) return levelOrder === "asc" ? 1 : -1;
+		}
+		return 0;
+	});
+}
+/**
+* Get the correct 0 based value for sync with other array in ascending order
+*
+* @example
+*   ```ts
+*   const items = [1, 2, 3];
+*
+*   const index = sortBy(
+*     items,
+*     (item) => getAscIndexOrder(
+*       followOrder.findIndex((order) => order === item)
+*     )
+*   );
+*   ```;
+*
+* @param index
+*/
+function getAscIndexOrder(index) {
+	return index === -1 ? Infinity : index ?? Infinity;
+}
+function arrayWithPrev(array) {
+	return array.map((item, i) => [item, array[i - 1] ?? null]);
+}
+function arrayWithPrevAndIndex(array) {
+	return array.map((item, i) => ({
+		item,
+		prev: array[i - 1] ?? null,
+		index: i
+	}));
+}
+function isInArray(value, oneOf) {
+	for (let i = 0; i < oneOf.length; i++) if (oneOf[i] === value) return true;
+	return false;
+}
+function isInArrayWithoutNarrowing(value, oneOf) {
+	return oneOf.includes(value);
+}
+function looseIsInArray(value, array) {
+	return array.includes(value);
+}
+function findAfterIndex(array, index, predicate) {
+	for (let i = index + 1; i < array.length; i++) if (predicate(array[i])) return array[i];
+}
+function findBeforeIndex(array, index, predicate) {
+	let indexToUse = index;
+	if (indexToUse >= array.length) indexToUse = array.length;
+	for (let i = indexToUse - 1; i >= 0; i--) if (predicate(array[i])) return array[i];
+}
+function rejectArrayUndefinedValues(array) {
+	return array.filter((item) => item !== void 0);
+}
+function hasDuplicates(array, getKey = (item) => item) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const item of array) {
+		const key = getKey(item);
+		if (seen.has(key)) return true;
+		seen.add(key);
+	}
+	return false;
+}
+function rejectDuplicates(array, getKey = (item) => item) {
+	const seen = /* @__PURE__ */ new Set();
+	const result = [];
+	for (const item of array) {
+		const key = getKey(item);
+		if (seen.has(key)) continue;
+		seen.add(key);
+		result.push(item);
+	}
+	return result;
+}
+function truncateArray(array, maxLength, appendIfTruncated) {
+	const truncate = array.length > maxLength;
+	const result = truncate ? [...array.slice(0, maxLength)] : array;
+	if (truncate && appendIfTruncated) {
+		if (isFunction(appendIfTruncated)) return [...result, appendIfTruncated(array.length - maxLength)];
+		return [...result, appendIfTruncated];
+	}
+	return result;
+}
+/**
+* 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`.
+*
+* @example
+*   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'
+*
+* @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
+*/
+function findAndMap(array, predicate) {
+	for (const item of array) {
+		const value = predicate(item);
+		if (value !== false) return value;
+	}
+}
+/**
+* Enhance an array with extra methods
+*
+* @example
+*   const enhancedItems = arrayOps(array);
+*
+*   enhancedItems.filterAndMap((item) => (item === 2 ? false : item));
+*   enhancedItems.sortBy((item) => item);
+*   enhancedItems.rejectDuplicates((item) => item);
+*
+* @param array
+*/
+function arrayOps(array) {
+	return {
+		filterAndMap: (mapFilter) => filterAndMap(array, mapFilter),
+		sortBy: (sortByValue, props) => sortBy(array, sortByValue, props),
+		rejectDuplicates: (getKey) => rejectDuplicates(array, getKey),
+		findAndMap: (predicate) => findAndMap(array, predicate)
+	};
+}
+/**
+* Inserts a separator value between each element in an array.
+*
+* @example
+*   intersperse([1, 2, 3], 0); // [1, 0, 2, 0, 3]
+*
+* @param array - The array to intersperse
+* @param separator - The value to insert between elements
+* @returns A new array with separator values inserted between elements
+*/
+function intersperse(array, separator) {
+	const result = [];
+	for (let i = 0; i < array.length; i++) {
+		result.push(array[i]);
+		if (i < array.length - 1) result.push(separator);
+	}
+	return result;
+}
+/**
+* Creates an array by repeating a value a specified number of times, optionally
+* with a separator between each repetition.
+*
+* @example
+*   repeat('x', 3); // ['x', 'x', 'x']
+*   repeat('x', 3, '-'); // ['x', '-', 'x', '-', 'x']
+*
+* @param value - The value to repeat
+* @param count - Number of times to repeat the value
+* @param separator - Optional separator to insert between repetitions
+* @returns A new array with the repeated values
+*/
+function repeat(value, count, separator) {
+	const result = [];
+	for (let i = 0; i < count; i++) {
+		result.push(value);
+		if (separator !== void 0 && i < count - 1) result.push(separator);
+	}
+	return result;
+}
+
+//#endregion
+export { arrayOps, arrayWithPrev, arrayWithPrevAndIndex, filterAndMap, findAfterIndex, findAndMap, findBeforeIndex, getAscIndexOrder, hasDuplicates, intersperse, isInArray, isInArrayWithoutNarrowing, looseIsInArray, rejectArrayUndefinedValues, rejectDuplicates, repeat, sortBy, truncateArray };

package/dist/assertions-qMxfVhSu.mjs

@@ -0,0 +1,207 @@
+import { a as isPlainObject$1, i as isObject$1, n as isFunction$1, o as isPromise$1 } from "./typeGuards-B1mzA-Rz.mjs";
+
+//#region src/assertions.ts
+const undefErrMsg = "not undefined assertion failed";
+const nullishErrMsg = "not nullish assertion failed";
+/**
+* Ensures a value is not undefined and returns it with the correct type.
+*
+* Throws an error if the value is undefined. Use it instead of `!` operator for
+* better type safety.
+*
+* @example
+*   ```typescript
+*   const maybeString: string | undefined = getValue();
+*   const definiteString = notUndefined(maybeString); // Type: string
+*
+*   // With custom error message
+*   const value = notUndefined(maybeValue, 'Value must be defined');
+*
+*   // With custom error function
+*   const value = notUndefined(maybeValue, () => new ValidationError('Required field'));
+*   ```;
+*
+* @template T - The type of the input value
+* @param value - The value to check for undefined
+* @param error - Error message string or function that returns an Error to
+*   throw if value is undefined
+* @returns The input value with undefined excluded from its type
+* @throws {Error} When the value is undefined
+*/
+function notUndefined(value, error = undefErrMsg) {
+	if (value === void 0) throw typeof error === "function" ? error() : new Error(error);
+	return value;
+}
+/**
+* Ensures a value is not null or undefined and returns it with the correct
+* type.
+*
+* Throws an error if the value is null or undefined. Use it instead of `!`
+* operator for better type safety.
+*
+* @example
+*   ```typescript
+*   const maybeString: string | null | undefined = getValue();
+*   const definiteString = notNullish(maybeString); // Type: string
+*
+*   // With custom error message
+*   const value = notNullish(maybeValue, 'Value cannot be null or undefined');
+*
+*   // With custom error function
+*   const value = notNullish(maybeValue, () => new ValidationError('Required field'));
+*   ```;
+*
+* @template T - The type of the input value
+* @param value - The value to check for null or undefined
+* @param error - Error message string or function that returns an Error to
+*   throw if value is nullish
+* @returns The input value with null and undefined excluded from its type
+* @throws {Error} When the value is null or undefined
+*/
+function notNullish(value, error = nullishErrMsg) {
+	if (value === void 0 || value === null) throw typeof error === "function" ? error() : new Error(error);
+	return value;
+}
+/**
+* Asserts that a value is not null or undefined using TypeScript's assertion
+* signature.
+*
+* Throws an error if the value is null or undefined. Use it instead of `!`
+* operator for better type safety.
+*
+* @example
+*   ```typescript
+*   function processValue(input: string | null | undefined) {
+*     assertIsNotNullish(input);
+*     // TypeScript now knows input is string
+*     console.log(input.toUpperCase());
+*   }
+*
+*   // With custom error
+*   assertIsNotNullish(value, 'Value is required for processing');
+*   ```;
+*
+* @template T - The type of the input value
+* @param value - The value to assert is not null or undefined
+* @param error - Error message string or function that returns an Error to
+*   throw if value is nullish
+* @throws {Error} When the value is null or undefined
+*/
+function assertIsNotNullish(value, error = nullishErrMsg) {
+	if (value === void 0 || value === null) throw typeof error === "function" ? error() : new Error(error);
+}
+/**
+* Asserts that a value is not undefined using TypeScript's assertion signature.
+*
+* Throws an error if the value is undefined. Use it instead of `!` operator for
+* better type safety.
+*
+* @example
+*   ```typescript
+*   function processValue(input: string | undefined) {
+*     assertIsNotUndefined(input);
+*     // TypeScript now knows input is string
+*     console.log(input.toUpperCase());
+*   }
+*
+*   // With custom error
+*   assertIsNotUndefined(value, 'Value must be defined');
+*   ```;
+*
+* @template T - The type of the input value
+* @param value - The value to assert is not undefined
+* @param error - Error message string or function that returns an Error to
+*   throw if value is undefined
+* @throws {Error} When the value is undefined
+*/
+function assertIsNotUndefined(value, error = undefErrMsg) {
+	if (value === void 0) throw typeof error === "function" ? error() : new Error(error);
+}
+/**
+* Asserts that a condition is always true, throwing an error if it's falsy.
+*
+* This function is useful for enforcing invariants in your code - conditions
+* that should always be true. It uses TypeScript's assertion signature to
+* narrow types based on the condition.
+*
+* @example
+*   ```typescript
+*   function divide(a: number, b: number) {
+*     invariant(b !== 0, 'Division by zero is not allowed');
+*     return a / b;
+*   }
+*
+*   // Type narrowing example
+*   function processUser(user: User | null) {
+*     invariant(user, 'User must be logged in');
+*     // TypeScript now knows user is User, not null
+*     console.log(user.name);
+*   }
+*
+*   // With custom error function
+*   invariant(isValid, () => new ValidationError('Invalid state detected'));
+*   ```;
+*
+* @param condition - The condition to check (any truthy/falsy value)
+* @param error - Error message string or function that returns an Error to
+*   throw if condition is falsy
+* @throws {Error} When the condition is falsy
+*/
+function invariant(condition, error = "Invariant violation") {
+	if (!condition) throw typeof error === "function" ? error() : /* @__PURE__ */ new Error(`Invariant violation: ${error}`);
+}
+/**
+* Ensures exhaustive type checking in switch statements or conditional logic.
+*
+* This function should be used in the default case of switch statements or the
+* final else branch of conditional logic to ensure all possible cases are
+* handled. It helps catch missing cases at compile time when new union members
+* are added.
+*
+* @example
+*   ```typescript
+*   type Status = 'pending' | 'success' | 'error';
+*
+*   function handleStatus(status: Status) {
+*     switch (status) {
+*       case 'pending':
+*         return 'Loading...';
+*       case 'success':
+*         return 'Done!';
+*       case 'error':
+*         return 'Failed!';
+*       default:
+*         throw exhaustiveCheck(status); // TypeScript error if Status gains new members
+*     }
+*   }
+*
+*   // In conditional logic
+*   function processValue(value: string | number) {
+*     if (typeof value === 'string') {
+*       return value.toUpperCase();
+*     } else if (typeof value === 'number') {
+*       return value.toString();
+*     } else {
+*       throw exhaustiveCheck(value); // Ensures all cases are covered
+*     }
+*   }
+*   ```;
+*
+* @template Except - The type that should never be reached
+* @param narrowedType - The value that should never exist at runtime
+* @returns An Error object (this function should never actually execute)
+*/
+function exhaustiveCheck(narrowedType) {
+	return /* @__PURE__ */ new Error("This should never happen");
+}
+/** @deprecated Use import from `@ls-stack/typeGuards` instead */
+const isFunction = isFunction$1;
+/** @deprecated Use import from `@ls-stack/typeGuards` instead */
+const isObject = isObject$1;
+/** @deprecated Use import from `@ls-stack/typeGuards` instead */
+const isPlainObject = isPlainObject$1;
+/** @deprecated Use import from `@ls-stack/typeGuards` instead */
+const isPromise = isPromise$1;
+
+//#endregion
+export { isFunction as a, isPromise as c, invariant as i, notNullish as l, assertIsNotUndefined as n, isObject as o, exhaustiveCheck as r, isPlainObject as s, assertIsNotNullish as t, notUndefined as u };

package/dist/{assertions.d.ts → assertions.d.mts}

@@ -1,5 +1,6 @@
-import { isFunction as isFunction$1, isObject as isObject$1, isPlainObject as isPlainObject$1, isPromise as isPromise$1 } from './typeGuards.js';
+import { isFunction as isFunction$1, isObject as isObject$1, isPlainObject as isPlainObject$1, isPromise as isPromise$1 } from "./typeGuards.mjs";
 
+//#region src/assertions.d.ts
 type NotUndefined<T> = T extends undefined ? never : T;
 type StrictNonUndefined<T, N = unknown> = undefined extends T ? NotUndefined<T> : N;
 /**
@@ -188,5 +189,5 @@ declare const isObject: typeof isObject$1;
 declare const isPlainObject: typeof isPlainObject$1;
 /** @deprecated Use import from `@ls-stack/typeGuards` instead */
 declare const isPromise: typeof isPromise$1;
-
-export { assertIsNotNullish, assertIsNotUndefined, exhaustiveCheck, invariant, isFunction, isObject, isPlainObject, isPromise, notNullish, notUndefined };
+//#endregion
+export { assertIsNotNullish, assertIsNotUndefined, exhaustiveCheck, invariant, isFunction, isObject, isPlainObject, isPromise, notNullish, notUndefined };

package/dist/assertions.mjs

@@ -0,0 +1,3 @@
+import { a as isFunction, c as isPromise, i as invariant, l as notNullish, n as assertIsNotUndefined, o as isObject, r as exhaustiveCheck, s as isPlainObject, t as assertIsNotNullish, u as notUndefined } from "./assertions-qMxfVhSu.mjs";
+
+export { assertIsNotNullish, assertIsNotUndefined, exhaustiveCheck, invariant, isFunction, isObject, isPlainObject, isPromise, notNullish, notUndefined };