@ls-stack/utils 3.18.0 → 3.19.0

package/README.md

@@ -22,23 +22,9 @@ import { deepEqual } from '@ls-stack/utils/deepEqual';
 import { debounce } from '@ls-stack/utils/debounce';
 ```
 
-## Available Utilities
-
-This package includes a wide range of utilities for:
-
-- **Array manipulation** (`arrayUtils`) - sorting, grouping, filtering
-- **Async operations** (`asyncQueue`, `parallelAsyncCalls`, `promiseUtils`) - queue management and promise utilities
-- **Type assertions** (`assertions`) - runtime type checking
-- **Caching** (`cache`) - efficient caching with TTL support
-- **Concurrency control** (`concurrentCalls`, `createThrottleController`) - rate limiting and throttling
-- **Object utilities** (`objUtils`) - deep operations on objects
-- **String utilities** (`stringUtils`) - string manipulation and formatting
-- **Math utilities** (`mathUtils`) - mathematical operations and calculations
-- **And many more...**
-
 ## Documentation
 
-Comprehensive API documentation is available in the [`docs/`](docs/) folder. Start with the [modules overview](docs/modules.md) to explore all available utilities.
+For a complete list of available utilities and their APIs, see the auto-generated documentation in the [`docs/`](docs/) folder. Start with the [modules overview](docs/modules.md) to explore all available utilities.
 
 ### Generating Documentation
 

package/docs/README.md

@@ -0,0 +1,72 @@
+**@ls-stack/utils**
+
+***
+
+# @ls-stack/utils
+
+Generic TypeScript utilities for modern JavaScript/TypeScript projects.
+
+## Installation
+
+```bash
+npm install @ls-stack/utils
+# or
+pnpm add @ls-stack/utils
+# or
+yarn add @ls-stack/utils
+```
+
+## Usage
+
+Import specific utilities from their modules:
+
+```typescript
+import { createAsyncQueue } from '@ls-stack/utils/asyncQueue';
+import { deepEqual } from '@ls-stack/utils/deepEqual';
+import { debounce } from '@ls-stack/utils/debounce';
+```
+
+## Documentation
+
+For a complete list of available utilities and their APIs, see the auto-generated documentation in the [`docs/`](docs/) folder. Start with the [modules overview](_media/modules.md) to explore all available utilities.
+
+### Generating Documentation
+
+To regenerate the documentation after making changes:
+
+```bash
+pnpm docs
+```
+
+For continuous updates during development:
+
+```bash
+pnpm docs:watch
+```
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Run tests
+pnpm test
+
+# Run tests with UI
+pnpm test:ui
+
+# Build the library
+pnpm build
+
+# Lint code
+pnpm lint
+```
+
+## License
+
+MIT
+
+## Repository
+
+[github:lucasols/utils](https://github.com/lucasols/utils)

package/docs/_media/modules.md

@@ -0,0 +1,52 @@
+[**@ls-stack/utils**](README.md)
+
+***
+
+# @ls-stack/utils
+
+## Modules
+
+- [arrayUtils](arrayUtils/README.md)
+- [assertions](assertions/README.md)
+- [asyncQueue](asyncQueue/README.md)
+- [awaitDebounce](awaitDebounce.md)
+- [cache](cache/README.md)
+- [castValues](castValues.md)
+- [concurrentCalls](concurrentCalls/README.md)
+- [consoleFmt](consoleFmt.md)
+- [conversions](conversions.md)
+- [createThrottleController](createThrottleController/README.md)
+- [debounce](debounce.md)
+- [dedent](dedent.md)
+- [deepEqual](deepEqual.md)
+- [enhancedMap](enhancedMap.md)
+- [exhaustiveMatch](exhaustiveMatch/README.md)
+- [getAutoIncrementId](getAutoIncrementId.md)
+- [getCompositeKey](getCompositeKey.md)
+- [getValueStableKey](getValueStableKey.md)
+- [hash](hash.md)
+- [interpolate](interpolate/README.md)
+- [levenshtein](levenshtein.md)
+- [main](main.md)
+- [mathUtils](mathUtils.md)
+- [objUtils](objUtils.md)
+- [parallelAsyncCalls](parallelAsyncCalls/README.md)
+- [promiseUtils](promiseUtils/README.md)
+- [retryOnError](retryOnError.md)
+- [runShellCmd](runShellCmd/README.md)
+- [safeJson](safeJson.md)
+- [saferTyping](saferTyping.md)
+- [serializeXML](serializeXML.md)
+- [shallowEqual](shallowEqual.md)
+- [sleep](sleep.md)
+- [stringUtils](stringUtils/README.md)
+- [testUtils](testUtils.md)
+- [throttle](throttle/README.md)
+- [time](time.md)
+- [timers](timers.md)
+- [tsResult](tsResult/README.md)
+- [typeGuards](typeGuards.md)
+- [typingFnUtils](typingFnUtils/README.md)
+- [typingTestUtils](typingTestUtils.md)
+- [typingUtils](typingUtils.md)
+- [yamlStringify](yamlStringify.md)

package/docs/arrayUtils/-internal-.md

@@ -0,0 +1,17 @@
+[**@ls-stack/utils**](../README.md)
+
+***
+
+[@ls-stack/utils](../modules.md) / [arrayUtils](README.md) / \<internal\>
+
+# \<internal\>
+
+## Type Aliases
+
+### SortOrder
+
+```ts
+type SortOrder = "desc" | "asc";
+```
+
+Defined in: [packages/utils/src/arrayUtils.ts:42](https://github.com/lucasols/utils/blob/main/packages/utils/src/arrayUtils.ts#L42)

package/docs/arrayUtils/README.md

@@ -0,0 +1,423 @@
+[**@ls-stack/utils**](../README.md)
+
+***
+
+[@ls-stack/utils](../modules.md) / arrayUtils
+
+# arrayUtils
+
+## Modules
+
+- [\<internal\>](-internal-.md)
+
+## Type Aliases
+
+### FilterAndMapReturn\<T\>
+
+```ts
+type FilterAndMapReturn<T> = false | T;
+```
+
+Defined in: [packages/utils/src/arrayUtils.ts:40](https://github.com/lucasols/utils/blob/main/packages/utils/src/arrayUtils.ts#L40)
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+## Functions
+
+### arrayWithPrev()
+
+```ts
+function arrayWithPrev<T>(array): [T, null | T][];
+```
+
+Defined in: [packages/utils/src/arrayUtils.ts:103](https://github.com/lucasols/utils/blob/main/packages/utils/src/arrayUtils.ts#L103)
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+#### Parameters
+
+##### array
+
+`T`[]
+
+#### Returns
+
+\[`T`, `null` \| `T`\][]
+
+***
+
+### arrayWithPrevAndIndex()
+
+```ts
+function arrayWithPrevAndIndex<T>(array): object[];
+```
+
+Defined in: [packages/utils/src/arrayUtils.ts:107](https://github.com/lucasols/utils/blob/main/packages/utils/src/arrayUtils.ts#L107)
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+#### Parameters
+
+##### array
+
+`T`[]
+
+#### Returns
+
+`object`[]
+
+***
+
+### filterAndMap()
+
+```ts
+function filterAndMap<T, R>(array, mapFilter): R[];
+```
+
+Defined in: [packages/utils/src/arrayUtils.ts:21](https://github.com/lucasols/utils/blob/main/packages/utils/src/arrayUtils.ts#L21)
+
+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.
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+##### R
+
+`R`
+
+#### Parameters
+
+##### array
+
+`IterableIterator`\<`T`, `any`, `any`\> | readonly `T`[]
+
+##### mapFilter
+
+(`item`, `index`) => `false` \| `R`
+
+#### Returns
+
+`R`[]
+
+#### Example
+
+```ts
+// 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']
+```
+
+***
+
+### findAfterIndex()
+
+```ts
+function findAfterIndex<T>(
+   array, 
+   index, 
+   predicate): undefined | T;
+```
+
+Defined in: [packages/utils/src/arrayUtils.ts:130](https://github.com/lucasols/utils/blob/main/packages/utils/src/arrayUtils.ts#L130)
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+#### Parameters
+
+##### array
+
+`T`[]
+
+##### index
+
+`number`
+
+##### predicate
+
+(`item`) => `boolean`
+
+#### Returns
+
+`undefined` \| `T`
+
+***
+
+### findBeforeIndex()
+
+```ts
+function findBeforeIndex<T>(
+   array, 
+   index, 
+   predicate): undefined | T;
+```
+
+Defined in: [packages/utils/src/arrayUtils.ts:144](https://github.com/lucasols/utils/blob/main/packages/utils/src/arrayUtils.ts#L144)
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+#### Parameters
+
+##### array
+
+`T`[]
+
+##### index
+
+`number`
+
+##### predicate
+
+(`item`) => `boolean`
+
+#### Returns
+
+`undefined` \| `T`
+
+***
+
+### hasDuplicates()
+
+```ts
+function hasDuplicates<T>(array, getKey): boolean;
+```
+
+Defined in: [packages/utils/src/arrayUtils.ts:168](https://github.com/lucasols/utils/blob/main/packages/utils/src/arrayUtils.ts#L168)
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+#### Parameters
+
+##### array
+
+`T`[]
+
+##### getKey
+
+(`item`) => `unknown`
+
+#### Returns
+
+`boolean`
+
+***
+
+### isInArray()
+
+```ts
+function isInArray<T, U>(value, oneOf): value is U;
+```
+
+Defined in: [packages/utils/src/arrayUtils.ts:117](https://github.com/lucasols/utils/blob/main/packages/utils/src/arrayUtils.ts#L117)
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+##### U
+
+`U`
+
+#### Parameters
+
+##### value
+
+`T`
+
+##### oneOf
+
+readonly `U`[]
+
+#### Returns
+
+`value is U`
+
+***
+
+### rejectArrayUndefinedValues()
+
+```ts
+function rejectArrayUndefinedValues<T>(array): T;
+```
+
+Defined in: [packages/utils/src/arrayUtils.ts:164](https://github.com/lucasols/utils/blob/main/packages/utils/src/arrayUtils.ts#L164)
+
+#### Type Parameters
+
+##### T
+
+`T` *extends* `unknown`[]
+
+#### Parameters
+
+##### array
+
+`T`
+
+#### Returns
+
+`T`
+
+***
+
+### rejectDuplicates()
+
+```ts
+function rejectDuplicates<T>(array, getKey): T[];
+```
+
+Defined in: [packages/utils/src/arrayUtils.ts:185](https://github.com/lucasols/utils/blob/main/packages/utils/src/arrayUtils.ts#L185)
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+#### Parameters
+
+##### array
+
+`T`[]
+
+##### getKey
+
+(`item`) => `unknown`
+
+#### Returns
+
+`T`[]
+
+***
+
+### sortBy()
+
+```ts
+function sortBy<T>(
+   arr, 
+   sortByValue, 
+   props): T[];
+```
+
+Defined in: [packages/utils/src/arrayUtils.ts:62](https://github.com/lucasols/utils/blob/main/packages/utils/src/arrayUtils.ts#L62)
+
+Sort an array based on a value
+
+Sort by `ascending` order by default
+
+Use `Infinity` as as wildcard to absolute max and min values
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+#### Parameters
+
+##### arr
+
+`T`[]
+
+##### sortByValue
+
+(`item`) => `string` \| `number` \| (`string` \| `number`)[]
+
+##### props
+
+[`SortOrder`](-internal-.md#sortorder) | [`SortOrder`](-internal-.md#sortorder)[] | \{
+`order?`: SortOrder \| SortOrder\[\] \| undefined;
+\}
+
+#### Returns
+
+`T`[]
+
+#### Example
+
+```ts
+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]);
+```
+
+***
+
+### truncateArray()
+
+```ts
+function truncateArray<T>(
+   array, 
+   maxLength, 
+   appendIfTruncated?): T[];
+```
+
+Defined in: [packages/utils/src/arrayUtils.ts:205](https://github.com/lucasols/utils/blob/main/packages/utils/src/arrayUtils.ts#L205)
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+#### Parameters
+
+##### array
+
+`T`[]
+
+##### maxLength
+
+`number`
+
+##### appendIfTruncated?
+
+`T` | (`truncatedCount`) => `T`
+
+#### Returns
+
+`T`[]

package/docs/assertions/-internal-.md

@@ -0,0 +1,63 @@
+[**@ls-stack/utils**](../README.md)
+
+***
+
+[@ls-stack/utils](../modules.md) / [assertions](README.md) / \<internal\>
+
+# \<internal\>
+
+## Type Aliases
+
+### NotUndefined\<T\>
+
+```ts
+type NotUndefined<T> = T extends undefined ? never : T;
+```
+
+Defined in: [packages/utils/src/assertions.ts:11](https://github.com/lucasols/utils/blob/main/packages/utils/src/assertions.ts#L11)
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+***
+
+### StrictNonNullable\<T, N\>
+
+```ts
+type StrictNonNullable<T, N> = undefined extends T ? NonNullable<T> : null extends T ? NonNullable<T> : N;
+```
+
+Defined in: [packages/utils/src/assertions.ts:50](https://github.com/lucasols/utils/blob/main/packages/utils/src/assertions.ts#L50)
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+##### N
+
+`N` = `unknown`
+
+***
+
+### StrictNonUndefined\<T, N\>
+
+```ts
+type StrictNonUndefined<T, N> = undefined extends T ? NotUndefined<T> : N;
+```
+
+Defined in: [packages/utils/src/assertions.ts:13](https://github.com/lucasols/utils/blob/main/packages/utils/src/assertions.ts#L13)
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+##### N
+
+`N` = `unknown`