@ls-stack/utils 3.17.1 → 3.19.0

package/docs/asyncQueue/README.md

@@ -0,0 +1,75 @@
+[**@ls-stack/utils**](../README.md)
+
+***
+
+[@ls-stack/utils](../modules.md) / asyncQueue
+
+# asyncQueue
+
+## Modules
+
+- [\<internal\>](-internal-.md)
+
+## Functions
+
+### createAsyncQueue()
+
+```ts
+function createAsyncQueue<T, E>(options?): AsyncQueue<T, E>;
+```
+
+Defined in: [packages/utils/src/asyncQueue.ts:328](https://github.com/lucasols/utils/blob/main/packages/utils/src/asyncQueue.ts#L328)
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+##### E
+
+`E` *extends* `ResultValidErrors` = `Error`
+
+#### Parameters
+
+##### options?
+
+[`AsyncQueueOptions`](-internal-.md#asyncqueueoptions)
+
+#### Returns
+
+[`AsyncQueue`](-internal-.md#asyncqueue)\<`T`, `E`\>
+
+***
+
+### createAsyncQueueWithMeta()
+
+```ts
+function createAsyncQueueWithMeta<T, I, E>(options?): AsyncQueueWithMeta<T, I, E>;
+```
+
+Defined in: [packages/utils/src/asyncQueue.ts:334](https://github.com/lucasols/utils/blob/main/packages/utils/src/asyncQueue.ts#L334)
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+##### I
+
+`I`
+
+##### E
+
+`E` *extends* `ResultValidErrors` = `Error`
+
+#### Parameters
+
+##### options?
+
+[`AsyncQueueOptions`](-internal-.md#asyncqueueoptions)
+
+#### Returns
+
+[`AsyncQueueWithMeta`](-internal-.md#asyncqueuewithmeta)\<`T`, `I`, `E`\>

package/docs/awaitDebounce.md

@@ -0,0 +1,66 @@
+[**@ls-stack/utils**](README.md)
+
+***
+
+[@ls-stack/utils](modules.md) / awaitDebounce
+
+# awaitDebounce
+
+## Functions
+
+### awaitDebounce()
+
+```ts
+function awaitDebounce(options): Promise<"skip" | "continue">;
+```
+
+Defined in: [packages/utils/src/awaitDebounce.ts:41](https://github.com/lucasols/utils/blob/main/packages/utils/src/awaitDebounce.ts#L41)
+
+Creates an awaitable debounce mechanism that allows you to debounce async operations.
+When called multiple times with the same `callId`, only the last call will resolve with 'continue',
+while all previous calls resolve with 'skip'.
+
+This is useful for debouncing API calls, search operations, or any async work where you want
+to ensure only the most recent request is processed.
+
+#### Parameters
+
+##### options
+
+Configuration object
+
+###### callId
+
+`any`
+
+Unique identifier for the debounce group. Calls with the same ID are debounced together
+
+###### debounce
+
+`number`
+
+Debounce delay in milliseconds
+
+#### Returns
+
+`Promise`\<`"skip"` \| `"continue"`\>
+
+Promise that resolves to 'continue' if this call should proceed, or 'skip' if it was superseded
+
+#### Example
+
+```ts
+async function searchUsers(query: string) {
+  const result = await awaitDebounce({ callId: 'search', debounce: 300 });
+  if (result === 'skip') return; // This search was superseded
+
+  // Only the most recent search will reach here
+  const users = await fetchUsers(query);
+  updateUI(users);
+}
+
+// Called rapidly - only the last call will execute
+searchUsers('a');
+searchUsers('ab');
+searchUsers('abc'); // Only this one will continue
+```

package/docs/cache/-internal-.md

@@ -0,0 +1,168 @@
+[**@ls-stack/utils**](../README.md)
+
+***
+
+[@ls-stack/utils](../modules.md) / [cache](README.md) / \<internal\>
+
+# \<internal\>
+
+## Type Aliases
+
+### GetOptions\<T\>
+
+```ts
+type GetOptions<T> = object;
+```
+
+Defined in: [packages/utils/src/cache.ts:65](https://github.com/lucasols/utils/blob/main/packages/utils/src/cache.ts#L65)
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+#### Properties
+
+##### skipCachingWhen()?
+
+```ts
+optional skipCachingWhen: (value) => boolean;
+```
+
+Defined in: [packages/utils/src/cache.ts:72](https://github.com/lucasols/utils/blob/main/packages/utils/src/cache.ts#L72)
+
+A function that determines whether a value should be rejected from being cached.
+If the function returns true, the value will be returned but not cached.
+
+###### Parameters
+
+###### value
+
+`T`
+
+The value to check
+
+###### Returns
+
+`boolean`
+
+true if the value should be rejected, false otherwise
+
+***
+
+### Options
+
+```ts
+type Options = object;
+```
+
+Defined in: [packages/utils/src/cache.ts:15](https://github.com/lucasols/utils/blob/main/packages/utils/src/cache.ts#L15)
+
+#### Properties
+
+##### expirationThrottle?
+
+```ts
+optional expirationThrottle: number;
+```
+
+Defined in: [packages/utils/src/cache.ts:30](https://github.com/lucasols/utils/blob/main/packages/utils/src/cache.ts#L30)
+
+The throttle for checking expired items in milliseconds.
+
+###### Default
+
+```ts
+10_000
+```
+
+##### maxCacheSize?
+
+```ts
+optional maxCacheSize: number;
+```
+
+Defined in: [packages/utils/src/cache.ts:20](https://github.com/lucasols/utils/blob/main/packages/utils/src/cache.ts#L20)
+
+The maximum number of items in the cache.
+
+###### Default
+
+```ts
+1000
+```
+
+##### maxItemAge?
+
+```ts
+optional maxItemAge: DurationObj;
+```
+
+Defined in: [packages/utils/src/cache.ts:24](https://github.com/lucasols/utils/blob/main/packages/utils/src/cache.ts#L24)
+
+The maximum age of items in the cache.
+
+***
+
+### Utils\<T\>
+
+```ts
+type Utils<T> = object;
+```
+
+Defined in: [packages/utils/src/cache.ts:55](https://github.com/lucasols/utils/blob/main/packages/utils/src/cache.ts#L55)
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+#### Properties
+
+##### skipCaching()
+
+```ts
+skipCaching: (value) => SkipCaching<T>;
+```
+
+Defined in: [packages/utils/src/cache.ts:56](https://github.com/lucasols/utils/blob/main/packages/utils/src/cache.ts#L56)
+
+###### Parameters
+
+###### value
+
+`T`
+
+###### Returns
+
+[`SkipCaching`](README.md#skipcaching)\<`T`\>
+
+##### withExpiration()
+
+```ts
+withExpiration: (value, expiration) => WithExpiration<T>;
+```
+
+Defined in: [packages/utils/src/cache.ts:62](https://github.com/lucasols/utils/blob/main/packages/utils/src/cache.ts#L62)
+
+Create a new WithExpiration object with the given value and expiration time.
+
+###### Parameters
+
+###### value
+
+`T`
+
+The value to store in the cache.
+
+###### expiration
+
+[`DurationObj`](../time.md#durationobj)
+
+The expiration time of the value in seconds or a duration object.
+
+###### Returns
+
+[`WithExpiration`](README.md#withexpiration)\<`T`\>

package/docs/cache/README.md

@@ -0,0 +1,360 @@
+[**@ls-stack/utils**](../README.md)
+
+***
+
+[@ls-stack/utils](../modules.md) / cache
+
+# cache
+
+## Modules
+
+- [\<internal\>](-internal-.md)
+
+## Classes
+
+### SkipCaching\<T\>
+
+Defined in: [packages/utils/src/cache.ts:33](https://github.com/lucasols/utils/blob/main/packages/utils/src/cache.ts#L33)
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new SkipCaching<T>(value): SkipCaching<T>;
+```
+
+Defined in: [packages/utils/src/cache.ts:36](https://github.com/lucasols/utils/blob/main/packages/utils/src/cache.ts#L36)
+
+###### Parameters
+
+###### value
+
+`T`
+
+###### Returns
+
+[`SkipCaching`](#skipcaching)\<`T`\>
+
+#### Properties
+
+##### value
+
+```ts
+value: T;
+```
+
+Defined in: [packages/utils/src/cache.ts:34](https://github.com/lucasols/utils/blob/main/packages/utils/src/cache.ts#L34)
+
+***
+
+### WithExpiration\<T\>
+
+Defined in: [packages/utils/src/cache.ts:41](https://github.com/lucasols/utils/blob/main/packages/utils/src/cache.ts#L41)
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+#### Constructors
+
+##### Constructor
+
+```ts
+new WithExpiration<T>(value, expiration): WithExpiration<T>;
+```
+
+Defined in: [packages/utils/src/cache.ts:49](https://github.com/lucasols/utils/blob/main/packages/utils/src/cache.ts#L49)
+
+###### Parameters
+
+###### value
+
+`T`
+
+The value to store in the cache.
+
+###### expiration
+
+[`DurationObj`](../time.md#durationobj)
+
+The expiration time of the value in seconds or a duration object.
+
+###### Returns
+
+[`WithExpiration`](#withexpiration)\<`T`\>
+
+#### Properties
+
+##### expiration
+
+```ts
+expiration: number;
+```
+
+Defined in: [packages/utils/src/cache.ts:43](https://github.com/lucasols/utils/blob/main/packages/utils/src/cache.ts#L43)
+
+##### value
+
+```ts
+value: T;
+```
+
+Defined in: [packages/utils/src/cache.ts:42](https://github.com/lucasols/utils/blob/main/packages/utils/src/cache.ts#L42)
+
+## Type Aliases
+
+### Cache\<T\>
+
+```ts
+type Cache<T> = object;
+```
+
+Defined in: [packages/utils/src/cache.ts:75](https://github.com/lucasols/utils/blob/main/packages/utils/src/cache.ts#L75)
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+#### Properties
+
+#####  cache
+
+```ts
+ cache: object;
+```
+
+Defined in: [packages/utils/src/cache.ts:95](https://github.com/lucasols/utils/blob/main/packages/utils/src/cache.ts#L95)
+
+###### map
+
+```ts
+map: Map<string, {
+  timestamp: number;
+  value: T | Promise<T>;
+}>;
+```
+
+##### cleanExpiredItems()
+
+```ts
+cleanExpiredItems: () => void;
+```
+
+Defined in: [packages/utils/src/cache.ts:89](https://github.com/lucasols/utils/blob/main/packages/utils/src/cache.ts#L89)
+
+###### Returns
+
+`void`
+
+##### clear()
+
+```ts
+clear: () => void;
+```
+
+Defined in: [packages/utils/src/cache.ts:86](https://github.com/lucasols/utils/blob/main/packages/utils/src/cache.ts#L86)
+
+###### Returns
+
+`void`
+
+##### get()
+
+```ts
+get: (cacheKey) => T | undefined;
+```
+
+Defined in: [packages/utils/src/cache.ts:87](https://github.com/lucasols/utils/blob/main/packages/utils/src/cache.ts#L87)
+
+###### Parameters
+
+###### cacheKey
+
+`string`
+
+###### Returns
+
+`T` \| `undefined`
+
+##### getAsync()
+
+```ts
+getAsync: (cacheKey) => Promise<T | undefined>;
+```
+
+Defined in: [packages/utils/src/cache.ts:90](https://github.com/lucasols/utils/blob/main/packages/utils/src/cache.ts#L90)
+
+###### Parameters
+
+###### cacheKey
+
+`string`
+
+###### Returns
+
+`Promise`\<`T` \| `undefined`\>
+
+##### getOrInsert()
+
+```ts
+getOrInsert: (cacheKey, val, options?) => T;
+```
+
+Defined in: [packages/utils/src/cache.ts:76](https://github.com/lucasols/utils/blob/main/packages/utils/src/cache.ts#L76)
+
+###### Parameters
+
+###### cacheKey
+
+`string`
+
+###### val
+
+(`utils`) => `T` \| [`SkipCaching`](#skipcaching)\<`T`\>
+
+###### options?
+
+[`GetOptions`](-internal-.md#getoptions)\<`T`\>
+
+###### Returns
+
+`T`
+
+##### getOrInsertAsync()
+
+```ts
+getOrInsertAsync: (cacheKey, val, options?) => Promise<T>;
+```
+
+Defined in: [packages/utils/src/cache.ts:81](https://github.com/lucasols/utils/blob/main/packages/utils/src/cache.ts#L81)
+
+###### Parameters
+
+###### cacheKey
+
+`string`
+
+###### val
+
+(`utils`) => `Promise`\<`T` \| [`SkipCaching`](#skipcaching)\<`T`\>\>
+
+###### options?
+
+[`GetOptions`](-internal-.md#getoptions)\<`T`\>
+
+###### Returns
+
+`Promise`\<`T`\>
+
+##### set()
+
+```ts
+set: (cacheKey, value) => void;
+```
+
+Defined in: [packages/utils/src/cache.ts:88](https://github.com/lucasols/utils/blob/main/packages/utils/src/cache.ts#L88)
+
+###### Parameters
+
+###### cacheKey
+
+`string`
+
+###### value
+
+`T` | [`WithExpiration`](#withexpiration)\<`T`\>
+
+###### Returns
+
+`void`
+
+##### setAsync()
+
+```ts
+setAsync: (cacheKey, value) => Promise<T>;
+```
+
+Defined in: [packages/utils/src/cache.ts:91](https://github.com/lucasols/utils/blob/main/packages/utils/src/cache.ts#L91)
+
+###### Parameters
+
+###### cacheKey
+
+`string`
+
+###### value
+
+(`utils`) => `Promise`\<`T` \| [`WithExpiration`](#withexpiration)\<`T`\>\>
+
+###### Returns
+
+`Promise`\<`T`\>
+
+## Functions
+
+### cachedGetter()
+
+```ts
+function cachedGetter<T>(getter): object;
+```
+
+Defined in: [packages/utils/src/cache.ts:3](https://github.com/lucasols/utils/blob/main/packages/utils/src/cache.ts#L3)
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+#### Parameters
+
+##### getter
+
+() => `T`
+
+#### Returns
+
+`object`
+
+##### value
+
+```ts
+value: T;
+```
+
+***
+
+### createCache()
+
+```ts
+function createCache<T>(__namedParameters): Cache<T>;
+```
+
+Defined in: [packages/utils/src/cache.ts:100](https://github.com/lucasols/utils/blob/main/packages/utils/src/cache.ts#L100)
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+#### Parameters
+
+##### \_\_namedParameters
+
+[`Options`](-internal-.md#options) = `{}`
+
+#### Returns
+
+[`Cache`](#cache)\<`T`\>

package/docs/castValues.md

@@ -0,0 +1,47 @@
+[**@ls-stack/utils**](README.md)
+
+***
+
+[@ls-stack/utils](modules.md) / castValues
+
+# castValues
+
+## Functions
+
+### castToNumber()
+
+```ts
+function castToNumber(value): null | number;
+```
+
+Defined in: [packages/utils/src/castValues.ts:14](https://github.com/lucasols/utils/blob/main/packages/utils/src/castValues.ts#L14)
+
+#### Parameters
+
+##### value
+
+`unknown`
+
+#### Returns
+
+`null` \| `number`
+
+***
+
+### castToString()
+
+```ts
+function castToString(value): null | string;
+```
+
+Defined in: [packages/utils/src/castValues.ts:1](https://github.com/lucasols/utils/blob/main/packages/utils/src/castValues.ts#L1)
+
+#### Parameters
+
+##### value
+
+`unknown`
+
+#### Returns
+
+`null` \| `string`