@ls-stack/utils 3.18.0 → 3.20.0

package/docs/stringUtils/README.md

@@ -0,0 +1,166 @@
+[**@ls-stack/utils**](../README.md)
+
+***
+
+[@ls-stack/utils](../modules.md) / stringUtils
+
+# stringUtils
+
+## Modules
+
+- [\<internal\>](-internal-.md)
+
+## Variables
+
+### ~~joinStrings()~~
+
+```ts
+const joinStrings: (...args) => string = concatStrings;
+```
+
+Defined in: [packages/utils/src/stringUtils.ts:33](https://github.com/lucasols/utils/blob/main/packages/utils/src/stringUtils.ts#L33)
+
+A util to create more legible conditional concatenated strings
+
+#### Parameters
+
+##### args
+
+...([`Arg`](-internal-.md#arg) \| [`Arg`](-internal-.md#arg)[])[]
+
+#### Returns
+
+`string`
+
+#### Example
+
+```ts
+joinStrings('a', 'b', 'c') // 'abc'
+joinStrings('a', false, 'c') // 'ac'
+joinStrings('a', addBString ? 'b' : null, 'c') // 'ac' if addBString is false, 'abc' if addBString is true
+```
+
+#### Deprecated
+
+Use [concatStrings](#concatstrings) instead
+
+## Functions
+
+### concatStrings()
+
+```ts
+function concatStrings(...args): string;
+```
+
+Defined in: [packages/utils/src/stringUtils.ts:11](https://github.com/lucasols/utils/blob/main/packages/utils/src/stringUtils.ts#L11)
+
+A util to create more legible conditional concatenated strings
+
+#### Parameters
+
+##### args
+
+...([`Arg`](-internal-.md#arg) \| [`Arg`](-internal-.md#arg)[])[]
+
+#### Returns
+
+`string`
+
+#### Example
+
+```ts
+joinStrings('a', 'b', 'c') // 'abc'
+joinStrings('a', false, 'c') // 'ac'
+joinStrings('a', addBString ? 'b' : null, 'c') // 'ac' if addBString is false, 'abc' if addBString is true
+```
+
+***
+
+### convertToSnakeCase()
+
+```ts
+function convertToSnakeCase(str): string;
+```
+
+Defined in: [packages/utils/src/stringUtils.ts:46](https://github.com/lucasols/utils/blob/main/packages/utils/src/stringUtils.ts#L46)
+
+#### Parameters
+
+##### str
+
+`string`
+
+#### Returns
+
+`string`
+
+***
+
+### formatNum()
+
+```ts
+function formatNum(num): string;
+```
+
+Defined in: [packages/utils/src/stringUtils.ts:35](https://github.com/lucasols/utils/blob/main/packages/utils/src/stringUtils.ts#L35)
+
+#### Parameters
+
+##### num
+
+`number`
+
+#### Returns
+
+`string`
+
+***
+
+### isSnakeCase()
+
+```ts
+function isSnakeCase(str): boolean;
+```
+
+Defined in: [packages/utils/src/stringUtils.ts:42](https://github.com/lucasols/utils/blob/main/packages/utils/src/stringUtils.ts#L42)
+
+#### Parameters
+
+##### str
+
+`string`
+
+#### Returns
+
+`boolean`
+
+***
+
+### truncateString()
+
+```ts
+function truncateString(
+   str, 
+   length, 
+   ellipsis): string;
+```
+
+Defined in: [packages/utils/src/stringUtils.ts:53](https://github.com/lucasols/utils/blob/main/packages/utils/src/stringUtils.ts#L53)
+
+#### Parameters
+
+##### str
+
+`string`
+
+##### length
+
+`number`
+
+##### ellipsis
+
+`string` = `'…'`
+
+#### Returns
+
+`string`

package/docs/testUtils.md

@@ -0,0 +1,315 @@
+[**@ls-stack/utils**](README.md)
+
+***
+
+[@ls-stack/utils](modules.md) / testUtils
+
+# testUtils
+
+## Functions
+
+### createLoggerStore()
+
+```ts
+function createLoggerStore(__namedParameters): object;
+```
+
+Defined in: [packages/utils/src/testUtils.ts:8](https://github.com/lucasols/utils/blob/main/packages/utils/src/testUtils.ts#L8)
+
+#### Parameters
+
+##### \_\_namedParameters
+
+###### arrays?
+
+  \| `"length"`
+  \| `"all"`
+  \| `"firstAndLast"`
+  \| \{
+  `firstNItems`: `number`;
+\} = `...`
+
+###### changesOnly?
+
+`boolean` = `false`
+
+###### filterKeys?
+
+`string`[]
+
+###### fromLastSnapshot?
+
+`boolean` = `false`
+
+###### maxLineLengthBeforeSplit?
+
+`number` = `80`
+
+###### rejectKeys?
+
+`string`[]
+
+###### splitLongLines?
+
+`true` = `true`
+
+###### useEmojiForBooleans?
+
+`boolean` = `true`
+
+#### Returns
+
+`object`
+
+##### add()
+
+```ts
+add: (render) => void;
+```
+
+###### Parameters
+
+###### render
+
+`Record`\<`string`, `unknown`\> | readonly `Record`\<`string`, `unknown`\>[]
+
+###### Returns
+
+`void`
+
+##### addMark()
+
+```ts
+addMark: (label) => void;
+```
+
+###### Parameters
+
+###### label
+
+`string`
+
+###### Returns
+
+`void`
+
+##### getSnapshot()
+
+```ts
+getSnapshot: (__namedParameters) => string;
+```
+
+###### Parameters
+
+###### \_\_namedParameters
+
+###### arrays?
+
+  \| `"length"`
+  \| `"all"`
+  \| `"firstAndLast"`
+  \| \{
+  `firstNItems`: `number`;
+\} = `defaultArrays`
+
+###### changesOnly?
+
+`boolean` = `defaultChangesOnly`
+
+###### filterKeys?
+
+`string`[] = `defaultFilterKeys`
+
+###### fromLastSnapshot?
+
+`boolean` = `defaultFromLastSnapshot`
+
+###### includeLastSnapshotEndMark?
+
+`boolean` = `true`
+
+###### maxLineLengthBeforeSplit?
+
+`number` = `defaultMaxLineLengthBeforeSplit`
+
+###### rejectKeys?
+
+`string`[] = `defaultRejectKeys`
+
+###### splitLongLines?
+
+`boolean` = `defaultSplitLongLines`
+
+###### useEmojiForBooleans?
+
+`boolean` = `defaultUseEmojiForBooleans`
+
+###### Returns
+
+`string`
+
+##### logsCount()
+
+```ts
+logsCount: () => number;
+```
+
+###### Returns
+
+`number`
+
+##### reset()
+
+```ts
+reset: (keepLastRender) => void;
+```
+
+###### Parameters
+
+###### keepLastRender
+
+`boolean` = `false`
+
+###### Returns
+
+`void`
+
+##### waitNextLog()
+
+```ts
+waitNextLog: (timeout) => Promise<void>;
+```
+
+###### Parameters
+
+###### timeout
+
+`number` = `50`
+
+###### Returns
+
+`Promise`\<`void`\>
+
+##### changesSnapshot
+
+###### Get Signature
+
+```ts
+get changesSnapshot(): string;
+```
+
+###### Returns
+
+`string`
+
+##### rendersTime
+
+###### Get Signature
+
+```ts
+get rendersTime(): number[];
+```
+
+###### Returns
+
+`number`[]
+
+##### snapshot
+
+###### Get Signature
+
+```ts
+get snapshot(): string;
+```
+
+###### Returns
+
+`string`
+
+##### snapshotFromLast
+
+###### Get Signature
+
+```ts
+get snapshotFromLast(): string;
+```
+
+###### Returns
+
+`string`
+
+***
+
+### getResultFn()
+
+```ts
+function getResultFn<T>(fnGetter, wrapper?): T;
+```
+
+Defined in: [packages/utils/src/testUtils.ts:274](https://github.com/lucasols/utils/blob/main/packages/utils/src/testUtils.ts#L274)
+
+#### Type Parameters
+
+##### T
+
+`T` *extends* (...`args`) => `any`
+
+#### Parameters
+
+##### fnGetter
+
+() => `T`
+
+##### wrapper?
+
+(...`args`) => `any`
+
+#### Returns
+
+`T`
+
+***
+
+### waitController()
+
+```ts
+function waitController(): object;
+```
+
+Defined in: [packages/utils/src/testUtils.ts:289](https://github.com/lucasols/utils/blob/main/packages/utils/src/testUtils.ts#L289)
+
+#### Returns
+
+`object`
+
+##### stopWaiting()
+
+```ts
+stopWaiting: () => void;
+```
+
+###### Returns
+
+`void`
+
+##### stopWaitingAfter()
+
+```ts
+stopWaitingAfter: (ms) => void;
+```
+
+###### Parameters
+
+###### ms
+
+`number`
+
+###### Returns
+
+`void`
+
+##### wait
+
+```ts
+wait: Promise<void>;
+```

package/docs/throttle/-internal-.md

@@ -0,0 +1,47 @@
+[**@ls-stack/utils**](../README.md)
+
+***
+
+[@ls-stack/utils](../modules.md) / [throttle](README.md) / \<internal\>
+
+# \<internal\>
+
+## Interfaces
+
+### ThrottleSettings
+
+Defined in: [packages/utils/src/throttle.ts:7](https://github.com/lucasols/utils/blob/main/packages/utils/src/throttle.ts#L7)
+
+#### Properties
+
+##### leading?
+
+```ts
+optional leading: boolean;
+```
+
+Defined in: [packages/utils/src/throttle.ts:12](https://github.com/lucasols/utils/blob/main/packages/utils/src/throttle.ts#L12)
+
+Specify invoking on the leading edge of the timeout.
+
+###### Default
+
+```ts
+true
+```
+
+##### trailing?
+
+```ts
+optional trailing: boolean;
+```
+
+Defined in: [packages/utils/src/throttle.ts:17](https://github.com/lucasols/utils/blob/main/packages/utils/src/throttle.ts#L17)
+
+Specify invoking on the trailing edge of the timeout.
+
+###### Default
+
+```ts
+true
+```

package/docs/throttle/README.md

@@ -0,0 +1,178 @@
+[**@ls-stack/utils**](../README.md)
+
+***
+
+[@ls-stack/utils](../modules.md) / throttle
+
+# throttle
+
+## Modules
+
+- [\<internal\>](-internal-.md)
+
+## Functions
+
+### createThrottledFunctionFactory()
+
+```ts
+function createThrottledFunctionFactory<T, R>(
+   wait, 
+   callback, 
+   options?): object;
+```
+
+Defined in: [packages/utils/src/throttle.ts:104](https://github.com/lucasols/utils/blob/main/packages/utils/src/throttle.ts#L104)
+
+Creates a factory for throttled functions that caches throttled instances based on function arguments.
+Each unique set of arguments gets its own throttled function instance, allowing for fine-grained
+throttling control per argument combination.
+
+This is useful when you want to throttle calls to the same function but with different parameters
+independently. For example, throttling API calls per user ID or throttling UI updates per component.
+
+#### Type Parameters
+
+##### T
+
+`T` *extends* `undefined` \| `null` \| `string` \| `number` \| `boolean`
+
+The type of arguments the callback function accepts
+
+##### R
+
+`R`
+
+The return type of the callback function
+
+#### Parameters
+
+##### wait
+
+`number`
+
+The number of milliseconds to throttle invocations to
+
+##### callback
+
+(...`args`) => `R`
+
+The function to throttle
+
+##### options?
+
+[`ThrottleSettings`](-internal-.md#throttlesettings)
+
+The throttle options (leading/trailing behavior)
+
+#### Returns
+
+`object`
+
+An object with a `call` method that accepts the callback arguments
+
+##### call()
+
+```ts
+call: (...args) => undefined | R;
+```
+
+###### Parameters
+
+###### args
+
+...`T`[]
+
+###### Returns
+
+`undefined` \| `R`
+
+#### Examples
+
+```ts
+const apiThrottle = createThrottledFunctionFactory(
+  1000,
+  (userId: string, action: string) => callAPI(userId, action)
+);
+
+// Each user gets their own throttled instance
+apiThrottle.call('user1', 'update'); // Executes immediately
+apiThrottle.call('user2', 'update'); // Executes immediately (different user)
+apiThrottle.call('user1', 'update'); // Throttled (same user)
+```
+
+```ts
+// Throttle UI updates per component
+const updateThrottle = createThrottledFunctionFactory(
+  100,
+  (componentId: string, data: any) => updateComponent(componentId, data)
+);
+```
+
+***
+
+### throttle()
+
+```ts
+function throttle<T>(
+   func, 
+   wait, 
+options?): DebouncedFunc<T>;
+```
+
+Defined in: [packages/utils/src/throttle.ts:51](https://github.com/lucasols/utils/blob/main/packages/utils/src/throttle.ts#L51)
+
+Creates a throttled function that only invokes the provided function at most once per every `wait` milliseconds.
+The throttled function comes with a `cancel` method to cancel delayed invocations and a `flush` method to immediately invoke them.
+
+Throttling is useful for rate-limiting events that fire frequently, like scroll or resize handlers.
+Unlike debouncing, throttling guarantees the function is called at regular intervals.
+
+#### Type Parameters
+
+##### T
+
+`T` *extends* [`__LEGIT_ANY_FUNCTION__`](../saferTyping.md#__legit_any_function__)
+
+The type of the function to throttle
+
+#### Parameters
+
+##### func
+
+`T`
+
+The function to throttle
+
+##### wait
+
+`number`
+
+The number of milliseconds to throttle invocations to
+
+##### options?
+
+[`ThrottleSettings`](-internal-.md#throttlesettings)
+
+The options object
+
+#### Returns
+
+[`DebouncedFunc`](../debounce.md#debouncedfunc)\<`T`\>
+
+Returns the new throttled function
+
+#### Examples
+
+```ts
+const throttledSave = throttle(saveData, 1000);
+
+// Will only call saveData at most once per second
+throttledSave();
+throttledSave();
+throttledSave();
+```
+
+```ts
+// Only invoke on trailing edge
+const throttledHandler = throttle(handleScroll, 100, { leading: false });
+```