@ls-stack/utils 3.18.0 → 3.19.0

package/docs/enhancedMap.md

@@ -0,0 +1,358 @@
+[**@ls-stack/utils**](README.md)
+
+***
+
+[@ls-stack/utils](modules.md) / enhancedMap
+
+# enhancedMap
+
+## Classes
+
+### EnhancedMap\<K, V\>
+
+Defined in: [packages/utils/src/enhancedMap.ts:5](https://github.com/lucasols/utils/blob/main/packages/utils/src/enhancedMap.ts#L5)
+
+#### Extends
+
+- `Map`\<`K`, `V`\>
+
+#### Type Parameters
+
+##### K
+
+`K`
+
+##### V
+
+`V`
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new EnhancedMap<K, V>(entries?): EnhancedMap<K, V>;
+```
+
+Defined in: node\_modules/.pnpm/typescript@5.7.3/node\_modules/typescript/lib/lib.es2015.collection.d.ts:50
+
+###### Parameters
+
+###### entries?
+
+`null` | readonly readonly \[`K`, `V`\][]
+
+###### Returns
+
+[`EnhancedMap`](#enhancedmap)\<`K`, `V`\>
+
+###### Inherited from
+
+```ts
+Map<K, V>.constructor
+```
+
+##### Constructor
+
+```ts
+new EnhancedMap<K, V>(iterable?): EnhancedMap<K, V>;
+```
+
+Defined in: node\_modules/.pnpm/typescript@5.7.3/node\_modules/typescript/lib/lib.es2015.collection.d.ts:49
+
+###### Parameters
+
+###### iterable?
+
+`null` | `Iterable`\<readonly \[`K`, `V`\], `any`, `any`\>
+
+###### Returns
+
+[`EnhancedMap`](#enhancedmap)\<`K`, `V`\>
+
+###### Inherited from
+
+```ts
+Map<K, V>.constructor
+```
+
+#### Methods
+
+##### find()
+
+```ts
+find(predicate): 
+  | undefined
+  | {
+  key: K;
+  value: V;
+};
+```
+
+Defined in: [packages/utils/src/enhancedMap.ts:6](https://github.com/lucasols/utils/blob/main/packages/utils/src/enhancedMap.ts#L6)
+
+###### Parameters
+
+###### predicate
+
+(`value`, `key`) => `boolean`
+
+###### Returns
+
+  \| `undefined`
+  \| \{
+  `key`: `K`;
+  `value`: `V`;
+\}
+
+##### getOrInsert()
+
+```ts
+getOrInsert(key, fallback): V;
+```
+
+Defined in: [packages/utils/src/enhancedMap.ts:44](https://github.com/lucasols/utils/blob/main/packages/utils/src/enhancedMap.ts#L44)
+
+###### Parameters
+
+###### key
+
+`K`
+
+###### fallback
+
+() => `V`
+
+###### Returns
+
+`V`
+
+##### getOrThrow()
+
+```ts
+getOrThrow(key): V;
+```
+
+Defined in: [packages/utils/src/enhancedMap.ts:34](https://github.com/lucasols/utils/blob/main/packages/utils/src/enhancedMap.ts#L34)
+
+###### Parameters
+
+###### key
+
+`K`
+
+###### Returns
+
+`V`
+
+##### setMultiple()
+
+###### Call Signature
+
+```ts
+setMultiple(values): this;
+```
+
+Defined in: [packages/utils/src/enhancedMap.ts:18](https://github.com/lucasols/utils/blob/main/packages/utils/src/enhancedMap.ts#L18)
+
+###### Parameters
+
+###### values
+
+`Record`\<`K` & `string`, `V`\>
+
+###### Returns
+
+`this`
+
+###### Call Signature
+
+```ts
+setMultiple(...values): this;
+```
+
+Defined in: [packages/utils/src/enhancedMap.ts:19](https://github.com/lucasols/utils/blob/main/packages/utils/src/enhancedMap.ts#L19)
+
+###### Parameters
+
+###### values
+
+...\[`K`, `V`\][]
+
+###### Returns
+
+`this`
+
+##### toFilteredValues()
+
+```ts
+toFilteredValues(predicate): V[];
+```
+
+Defined in: [packages/utils/src/enhancedMap.ts:52](https://github.com/lucasols/utils/blob/main/packages/utils/src/enhancedMap.ts#L52)
+
+###### Parameters
+
+###### predicate
+
+(`value`, `key`) => `boolean`
+
+###### Returns
+
+`V`[]
+
+##### toKeys()
+
+```ts
+toKeys(): K[];
+```
+
+Defined in: [packages/utils/src/enhancedMap.ts:104](https://github.com/lucasols/utils/blob/main/packages/utils/src/enhancedMap.ts#L104)
+
+###### Returns
+
+`K`[]
+
+##### toMap()
+
+```ts
+toMap<T>(mapFunction): T[];
+```
+
+Defined in: [packages/utils/src/enhancedMap.ts:64](https://github.com/lucasols/utils/blob/main/packages/utils/src/enhancedMap.ts#L64)
+
+###### Type Parameters
+
+###### T
+
+`T`
+
+###### Parameters
+
+###### mapFunction
+
+(`value`, `key`, `reject`) => *typeof* [`enhancedMapReject`](#enhancedmapreject) \| `T`
+
+###### Returns
+
+`T`[]
+
+##### toObjMap()
+
+```ts
+toObjMap<ObjKey, ObjValue>(mapFunction): Record<ObjKey, ObjValue>;
+```
+
+Defined in: [packages/utils/src/enhancedMap.ts:84](https://github.com/lucasols/utils/blob/main/packages/utils/src/enhancedMap.ts#L84)
+
+###### Type Parameters
+
+###### ObjKey
+
+`ObjKey` *extends* `PropertyKey`
+
+###### ObjValue
+
+`ObjValue`
+
+###### Parameters
+
+###### mapFunction
+
+(`value`, `key`) => `false` \| \[`ObjKey`, `ObjValue`\]
+
+###### Returns
+
+`Record`\<`ObjKey`, `ObjValue`\>
+
+##### toValues()
+
+```ts
+toValues(): V[];
+```
+
+Defined in: [packages/utils/src/enhancedMap.ts:100](https://github.com/lucasols/utils/blob/main/packages/utils/src/enhancedMap.ts#L100)
+
+###### Returns
+
+`V`[]
+
+##### from()
+
+###### Call Signature
+
+```ts
+static from<T, K>(array, key): EnhancedMap<T[K], T>;
+```
+
+Defined in: [packages/utils/src/enhancedMap.ts:108](https://github.com/lucasols/utils/blob/main/packages/utils/src/enhancedMap.ts#L108)
+
+###### Type Parameters
+
+###### T
+
+`T` *extends* `Record`\<`string`, `unknown`\>
+
+###### K
+
+`K` *extends* `string` \| `number` \| `symbol`
+
+###### Parameters
+
+###### array
+
+`undefined` | `null` | `Iterable`\<`T`, `any`, `any`\> | `T`[]
+
+###### key
+
+`K`
+
+###### Returns
+
+[`EnhancedMap`](#enhancedmap)\<`T`\[`K`\], `T`\>
+
+###### Call Signature
+
+```ts
+static from<T, K, V>(array, mapFunction): EnhancedMap<K, V>;
+```
+
+Defined in: [packages/utils/src/enhancedMap.ts:112](https://github.com/lucasols/utils/blob/main/packages/utils/src/enhancedMap.ts#L112)
+
+###### Type Parameters
+
+###### T
+
+`T`
+
+###### K
+
+`K`
+
+###### V
+
+`V`
+
+###### Parameters
+
+###### array
+
+`undefined` | `null` | `T`[] | `Iterable`\<`T`, `any`, `any`\>
+
+###### mapFunction
+
+(`item`) => `false` \| \[`K`, `V`\]
+
+###### Returns
+
+[`EnhancedMap`](#enhancedmap)\<`K`, `V`\>
+
+## Variables
+
+### enhancedMapReject
+
+```ts
+const enhancedMapReject: typeof enhancedMapReject;
+```
+
+Defined in: [packages/utils/src/enhancedMap.ts:3](https://github.com/lucasols/utils/blob/main/packages/utils/src/enhancedMap.ts#L3)

package/docs/exhaustiveMatch/-internal-.md

@@ -0,0 +1,39 @@
+[**@ls-stack/utils**](../README.md)
+
+***
+
+[@ls-stack/utils](../modules.md) / [exhaustiveMatch](README.md) / \<internal\>
+
+# \<internal\>
+
+## Type Aliases
+
+### Pattern\<R\>
+
+```ts
+type Pattern<R> = { [K in T]: (() => R) | "_nxt" | "_never" };
+```
+
+Defined in: [packages/utils/src/exhaustiveMatch.ts:2](https://github.com/lucasols/utils/blob/main/packages/utils/src/exhaustiveMatch.ts#L2)
+
+#### Type Parameters
+
+##### R
+
+`R`
+
+***
+
+### Pattern\<R\>
+
+```ts
+type Pattern<R> = { [P in K]: ((props: Extract<T, Record<D, P>>) => R) | "_never" };
+```
+
+Defined in: [packages/utils/src/exhaustiveMatch.ts:52](https://github.com/lucasols/utils/blob/main/packages/utils/src/exhaustiveMatch.ts#L52)
+
+#### Type Parameters
+
+##### R
+
+`R`

package/docs/exhaustiveMatch/README.md

@@ -0,0 +1,146 @@
+[**@ls-stack/utils**](../README.md)
+
+***
+
+[@ls-stack/utils](../modules.md) / exhaustiveMatch
+
+# exhaustiveMatch
+
+## Modules
+
+- [\<internal\>](-internal-.md)
+
+## Functions
+
+### exhaustiveMatch()
+
+```ts
+function exhaustiveMatch<T>(value): object;
+```
+
+Defined in: [packages/utils/src/exhaustiveMatch.ts:1](https://github.com/lucasols/utils/blob/main/packages/utils/src/exhaustiveMatch.ts#L1)
+
+#### Type Parameters
+
+##### T
+
+`T` *extends* `string`
+
+#### Parameters
+
+##### value
+
+`T`
+
+#### Returns
+
+##### with()
+
+```ts
+with: <R>(pattern) => R = matchWith;
+```
+
+The pattern can be:
+- a function that returns the result
+- '_nxt' to try the next pattern
+- '_never' to indicate that this pattern should never be matched
+
+###### Type Parameters
+
+###### R
+
+`R`
+
+###### Parameters
+
+###### pattern
+
+[`Pattern`](-internal-.md#pattern)\<`R`\>
+
+###### Returns
+
+`R`
+
+##### withObject()
+
+```ts
+withObject: <R>(pattern) => R;
+```
+
+match with early evaluation of the values
+
+###### Type Parameters
+
+###### R
+
+`R`
+
+###### Parameters
+
+###### pattern
+
+`Record`\<`T`, `R`\>
+
+###### Returns
+
+`R`
+
+***
+
+### exhaustiveMatchObjUnion()
+
+```ts
+function exhaustiveMatchObjUnion<T, D, K>(obj, key): object;
+```
+
+Defined in: [packages/utils/src/exhaustiveMatch.ts:47](https://github.com/lucasols/utils/blob/main/packages/utils/src/exhaustiveMatch.ts#L47)
+
+#### Type Parameters
+
+##### T
+
+`T` *extends* `Record`\<`string`, `unknown`\>
+
+##### D
+
+`D` *extends* `string` \| `number` \| `symbol`
+
+##### K
+
+`K` *extends* `string`
+
+#### Parameters
+
+##### obj
+
+`T`
+
+##### key
+
+`D`
+
+#### Returns
+
+`object`
+
+##### with()
+
+```ts
+with: <R>(pattern) => R = withLazy;
+```
+
+###### Type Parameters
+
+###### R
+
+`R`
+
+###### Parameters
+
+###### pattern
+
+[`Pattern`](-internal-.md#pattern-1)\<`R`\>
+
+###### Returns
+
+`R`

package/docs/getAutoIncrementId.md

@@ -0,0 +1,93 @@
+[**@ls-stack/utils**](README.md)
+
+***
+
+[@ls-stack/utils](modules.md) / getAutoIncrementId
+
+# getAutoIncrementId
+
+## Functions
+
+### getAutoIncrementId()
+
+```ts
+function getAutoIncrementId(): number;
+```
+
+Defined in: [packages/utils/src/getAutoIncrementId.ts:19](https://github.com/lucasols/utils/blob/main/packages/utils/src/getAutoIncrementId.ts#L19)
+
+Returns a unique auto-incrementing number each time it's called.
+This is useful for generating simple unique identifiers within a single session/process.
+
+**Note:** This is not suitable for distributed systems or persistent storage.
+For cryptographically secure or collision-resistant IDs, use `nanoid()` instead.
+
+#### Returns
+
+`number`
+
+A unique incrementing number starting from 1
+
+#### Example
+
+```ts
+const id1 = getAutoIncrementId(); // 1
+const id2 = getAutoIncrementId(); // 2
+const id3 = getAutoIncrementId(); // 3
+```
+
+***
+
+### getLocalAutoIncrementIdGenerator()
+
+```ts
+function getLocalAutoIncrementIdGenerator(options): () => string;
+```
+
+Defined in: [packages/utils/src/getAutoIncrementId.ts:44](https://github.com/lucasols/utils/blob/main/packages/utils/src/getAutoIncrementId.ts#L44)
+
+Creates a local auto-increment ID generator with optional prefix and suffix.
+Each generator maintains its own independent counter starting from 1.
+This is useful when you need multiple independent ID sequences or formatted IDs.
+
+#### Parameters
+
+##### options
+
+Configuration object
+
+###### prefix?
+
+`string`
+
+Optional prefix to prepend to each generated ID
+
+###### suffix?
+
+`string`
+
+Optional suffix to append to each generated ID
+
+#### Returns
+
+A function that generates formatted auto-increment IDs
+
+```ts
+(): string;
+```
+
+##### Returns
+
+`string`
+
+#### Example
+
+```ts
+const userIdGen = getLocalAutoIncrementIdGenerator({ prefix: 'user-' });
+const postIdGen = getLocalAutoIncrementIdGenerator({ prefix: 'post-', suffix: '-draft' });
+
+console.log(userIdGen()); // "user-1"
+console.log(userIdGen()); // "user-2"
+console.log(postIdGen()); // "post-1-draft"
+console.log(postIdGen()); // "post-2-draft"
+```

package/docs/getCompositeKey.md

@@ -0,0 +1,39 @@
+[**@ls-stack/utils**](README.md)
+
+***
+
+[@ls-stack/utils](modules.md) / getCompositeKey
+
+# getCompositeKey
+
+## Functions
+
+### getCompositeKey()
+
+```ts
+function getCompositeKey(input, maxSortingDepth): string;
+```
+
+Defined in: [packages/utils/src/getCompositeKey.ts:10](https://github.com/lucasols/utils/blob/main/packages/utils/src/getCompositeKey.ts#L10)
+
+Returns a stable key for the input value.
+
+#### Parameters
+
+##### input
+
+`unknown`
+
+The value to get a stable key for.
+
+##### maxSortingDepth
+
+`number` = `3`
+
+The maximum depth to sort the input value. Default is 3.
+
+#### Returns
+
+`string`
+
+A stable key for the input value.

package/docs/getValueStableKey.md

@@ -0,0 +1,57 @@
+[**@ls-stack/utils**](README.md)
+
+***
+
+[@ls-stack/utils](modules.md) / getValueStableKey
+
+# getValueStableKey
+
+## Variables
+
+### ~~getValueStableKey()~~
+
+```ts
+const getValueStableKey: (input, maxSortingDepth) => string = getCompositeKey;
+```
+
+Defined in: [packages/utils/src/getValueStableKey.ts:12](https://github.com/lucasols/utils/blob/main/packages/utils/src/getValueStableKey.ts#L12)
+
+Returns a stable key for the input value.
+
+Returns a stable key for the input value.
+
+#### Parameters
+
+##### input
+
+`unknown`
+
+The value to get a stable key for.
+
+##### maxSortingDepth
+
+`number` = `3`
+
+The maximum depth to sort the input value. Default is 3.
+
+#### Returns
+
+`string`
+
+A stable key for the input value.
+
+#### Param
+
+The value to get a stable key for.
+
+#### Param
+
+The maximum depth to sort the input value. Default is 3.
+
+#### Returns
+
+A stable key for the input value.
+
+#### Deprecated
+
+Use `getCompositeKey` from `@ls-stack/utils/getCompositeKey` instead.