@ls-stack/utils 3.39.0 → 3.41.0

package/dist/asyncQueue.js

@@ -27,22 +27,23 @@ var AsyncQueue = class _AsyncQueue {
   /**
    * Event emitter for tracking task lifecycle
    *
-   * @example Listening to Events
-   * ```typescript
-   * const queue = createAsyncQueue<string>();
+   * @example
+   *   Listening to Events
+   *   ```typescript
+   *   const queue = createAsyncQueue<string>();
    *
-   * queue.events.on('start', (event) => {
+   *   queue.events.on('start', (event) => {
    *   console.log('Task started:', event.payload.meta);
-   * });
+   *   });
    *
-   * queue.events.on('complete', (event) => {
+   *   queue.events.on('complete', (event) => {
    *   console.log('Task completed:', event.payload.value);
-   * });
+   *   });
    *
-   * queue.events.on('error', (event) => {
+   *   queue.events.on('error', (event) => {
    *   console.error('Task failed:', event.payload.error);
-   * });
-   * ```
+   *   });
+   *   ```
    */
   events = evtmitter();
   #signal;
@@ -156,32 +157,33 @@ var AsyncQueue = class _AsyncQueue {
   /**
    * Add a task that returns a Result to the queue
    *
-   * Use this method when your task function already returns a Result type.
-   * For functions that throw errors or return plain values, use `resultifyAdd` instead.
+   * Use this method when your task function already returns a Result type. For
+   * functions that throw errors or return plain values, use `resultifyAdd`
+   * instead.
+   *
+   * @example
+   *   ```typescript
+   *   const queue = createAsyncQueue<string>();
+   *
+   *   const result = await queue.add(async () => {
+   *     try {
+   *       const data = await fetchData();
+   *       return Result.ok(data);
+   *     } catch (error) {
+   *       return Result.err(error);
+   *     }
+   *   });
+   *
+   *   if (result.ok) {
+   *     console.log('Success:', result.value);
+   *   } else {
+   *     console.log('Error:', result.error);
+   *   }
+   *   ```;
    *
    * @param fn - Task function that returns a Result
    * @param options - Optional configuration for this task
    * @returns Promise that resolves with the task result
-   *
-   * @example
-   * ```typescript
-   * const queue = createAsyncQueue<string>();
-   *
-   * const result = await queue.add(async () => {
-   *   try {
-   *     const data = await fetchData();
-   *     return Result.ok(data);
-   *   } catch (error) {
-   *     return Result.err(error);
-   *   }
-   * });
-   *
-   * if (result.ok) {
-   *   console.log('Success:', result.value);
-   * } else {
-   *   console.log('Error:', result.error);
-   * }
-   * ```
    */
   async add(fn, options) {
     if (this.#signal?.aborted) {
@@ -225,37 +227,39 @@ var AsyncQueue = class _AsyncQueue {
    * This is the most commonly used method. It automatically wraps your function
    * to handle errors and convert them to Result types.
    *
-   * @param fn - Task function that returns a value or throws
-   * @param options - Optional configuration for this task
-   * @returns Promise that resolves with the task result wrapped in Result
-   *
-   * @example Basic Usage
-   * ```typescript
-   * const queue = createAsyncQueue<string>();
+   * @example
+   *   Basic Usage
+   *   ```typescript
+   *   const queue = createAsyncQueue<string>();
    *
-   * queue.resultifyAdd(async () => {
+   *   queue.resultifyAdd(async () => {
    *   const response = await fetch('/api/data');
    *   return response.json();
-   * }).then(result => {
+   *   }).then(result => {
    *   if (result.ok) {
-   *     console.log('Data:', result.value);
+   *   console.log('Data:', result.value);
    *   } else {
-   *     console.error('Failed:', result.error);
+   *   console.error('Failed:', result.error);
    *   }
-   * });
-   * ```
+   *   });
+   *   ```
    *
-   * @example With Callbacks
-   * ```typescript
-   * queue.resultifyAdd(
+   * @example
+   *   With Callbacks
+   *   ```typescript
+   *   queue.resultifyAdd(
    *   async () => processData(),
    *   {
-   *     onComplete: (data) => console.log('Processed:', data),
-   *     onError: (error) => console.error('Failed:', error),
-   *     timeout: 5000
+   *   onComplete: (data) => console.log('Processed:', data),
+   *   onError: (error) => console.error('Failed:', error),
+   *   timeout: 5000
    *   }
-   * );
-   * ```
+   *   );
+   *   ```
+   *
+   * @param fn - Task function that returns a value or throws
+   * @param options - Optional configuration for this task
+   * @returns Promise that resolves with the task result wrapped in Result
    */
   resultifyAdd(fn, options) {
     return this.add(
@@ -400,29 +404,32 @@ var AsyncQueue = class _AsyncQueue {
     this.#resolveIdleWaiters();
   }
   /**
-   * Wait for the queue to become idle (no pending tasks, no queued tasks, and no rate-limit timers)
+   * Wait for the queue to become idle (no pending tasks, no queued tasks, and
+   * no rate-limit timers)
    *
    * This method resolves when:
+   *
    * - All tasks have completed (success or failure)
    * - The queue is stopped due to error (stopOnError), even with remaining tasks
-   * - There are no queued tasks, no running tasks, and no pending rate-limit timers
-   *
-   * @returns Promise that resolves when the queue is idle
+   * - There are no queued tasks, no running tasks, and no pending rate-limit
+   *   timers
    *
    * @example
-   * ```typescript
-   * const queue = createAsyncQueue<string>();
+   *   ```typescript
+   *   const queue = createAsyncQueue<string>();
    *
-   * // Add multiple tasks
-   * for (let i = 0; i < 10; i++) {
+   *   // Add multiple tasks
+   *   for (let i = 0; i < 10; i++) {
    *   queue.resultifyAdd(async () => `task ${i}`);
-   * }
+   *   }
+   *
+   *   // Wait for all tasks to complete
+   *   await queue.onIdle();
    *
-   * // Wait for all tasks to complete
-   * await queue.onIdle();
+   *   console.log(`Completed: ${queue.completed}, Failed: ${queue.failed}`);
+   *   ```
    *
-   * console.log(`Completed: ${queue.completed}, Failed: ${queue.failed}`);
-   * ```
+   * @returns Promise that resolves when the queue is idle
    */
   async onIdle() {
     if (this.#stopped || this.#pending === 0 && this.#size === 0 && this.#rateLimitTimeouts.size === 0) {
@@ -453,24 +460,24 @@ var AsyncQueue = class _AsyncQueue {
   /**
    * Clear all queued tasks (does not affect currently running tasks)
    *
-   * This removes all tasks waiting in the queue but allows currently
-   * executing tasks to complete normally.
+   * This removes all tasks waiting in the queue but allows currently executing
+   * tasks to complete normally.
    *
    * @example
-   * ```typescript
-   * const queue = createAsyncQueue({ concurrency: 1 });
+   *   ```typescript
+   *   const queue = createAsyncQueue({ concurrency: 1 });
    *
-   * // Add multiple tasks
-   * queue.resultifyAdd(async () => longRunningTask()); // Will start immediately
-   * queue.resultifyAdd(async () => task2()); // Queued
-   * queue.resultifyAdd(async () => task3()); // Queued
+   *   // Add multiple tasks
+   *   queue.resultifyAdd(async () => longRunningTask()); // Will start immediately
+   *   queue.resultifyAdd(async () => task2()); // Queued
+   *   queue.resultifyAdd(async () => task3()); // Queued
    *
-   * // Clear remaining queued tasks
-   * queue.clear();
+   *   // Clear remaining queued tasks
+   *   queue.clear();
    *
-   * // Only the first task will complete
-   * await queue.onIdle();
-   * ```
+   *   // Only the first task will complete
+   *   await queue.onIdle();
+   *   ```;
    */
   clear() {
     this.#queue = [];
@@ -504,17 +511,17 @@ var AsyncQueue = class _AsyncQueue {
    * Manually start processing tasks (only needed if autoStart: false)
    *
    * @example
-   * ```typescript
-   * const queue = createAsyncQueue({ autoStart: false });
+   *   ```typescript
+   *   const queue = createAsyncQueue({ autoStart: false });
    *
-   * // Add tasks without starting processing
-   * queue.resultifyAdd(async () => 'task1');
-   * queue.resultifyAdd(async () => 'task2');
+   *   // Add tasks without starting processing
+   *   queue.resultifyAdd(async () => 'task1');
+   *   queue.resultifyAdd(async () => 'task2');
    *
-   * // Start processing when ready
-   * queue.start();
-   * await queue.onIdle();
-   * ```
+   *   // Start processing when ready
+   *   queue.start();
+   *   await queue.onIdle();
+   *   ```;
    */
   start() {
     if (this.#stopped) {
@@ -527,26 +534,24 @@ var AsyncQueue = class _AsyncQueue {
    * Pause processing new tasks (currently running tasks continue)
    *
    * @example
-   * ```typescript
-   * const queue = createAsyncQueue();
+   *   ```typescript
+   *   const queue = createAsyncQueue();
    *
-   * // Start some tasks
-   * queue.resultifyAdd(async () => longRunningTask1());
-   * queue.resultifyAdd(async () => longRunningTask2());
+   *   // Start some tasks
+   *   queue.resultifyAdd(async () => longRunningTask1());
+   *   queue.resultifyAdd(async () => longRunningTask2());
    *
-   * // Pause before more tasks are picked up
-   * queue.pause();
+   *   // Pause before more tasks are picked up
+   *   queue.pause();
    *
-   * // Later, resume processing
-   * queue.resume();
-   * ```
+   *   // Later, resume processing
+   *   queue.resume();
+   *   ```;
    */
   pause() {
     this.#paused = true;
   }
-  /**
-   * Resume processing tasks after pause
-   */
+  /** Resume processing tasks after pause */
   resume() {
     this.#paused = false;
     if (this.#started && !this.#stopped) {
@@ -556,27 +561,27 @@ var AsyncQueue = class _AsyncQueue {
   /**
    * Reset the queue after being stopped, allowing new tasks to be processed
    *
-   * This clears the stopped state and error reason, and resumes processing
-   * any remaining queued tasks if autoStart was enabled.
+   * This clears the stopped state and error reason, and resumes processing any
+   * remaining queued tasks if autoStart was enabled.
    *
    * @example
-   * ```typescript
-   * const queue = createAsyncQueue({ stopOnError: true });
+   *   ```typescript
+   *   const queue = createAsyncQueue({ stopOnError: true });
    *
-   * // Add tasks that will cause the queue to stop
-   * queue.resultifyAdd(async () => { throw new Error('fail'); });
-   * queue.resultifyAdd(async () => 'remaining task');
+   *   // Add tasks that will cause the queue to stop
+   *   queue.resultifyAdd(async () => { throw new Error('fail'); });
+   *   queue.resultifyAdd(async () => 'remaining task');
    *
-   * await queue.onIdle();
+   *   await queue.onIdle();
    *
-   * if (queue.isStopped) {
+   *   if (queue.isStopped) {
    *   console.log(`Queue stopped, ${queue.size} tasks remaining`);
    *
    *   // Reset and process remaining tasks
    *   queue.reset();
    *   await queue.onIdle();
-   * }
-   * ```
+   *   }
+   *   ```
    */
   reset() {
     this.#stopped = false;

package/dist/awaitDebounce.d.cts

@@ -1,34 +1,37 @@
 import { __LEGIT_ANY__ } from './saferTyping.cjs';
 
 /**
- * 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'.
+ * 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.
- *
- * @param options - Configuration object
- * @param options.callId - Unique identifier for the debounce group. Calls with the same ID are debounced together
- * @param options.debounce - Debounce delay in milliseconds
- * @returns Promise that resolves to 'continue' if this call should proceed, or 'skip' if it was superseded
+ * 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.
  *
  * @example
- * ```ts
- * async function searchUsers(query: string) {
- *   const result = await awaitDebounce({ callId: 'search', debounce: 300 });
- *   if (result === 'skip') return; // This search was superseded
+ *   ```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);
- * }
+ *     // 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
- * ```
+ *   // Called rapidly - only the last call will execute
+ *   searchUsers('a');
+ *   searchUsers('ab');
+ *   searchUsers('abc'); // Only this one will continue
+ *   ```;
+ *
+ * @param options - Configuration object
+ * @param options.callId - Unique identifier for the debounce group. Calls with
+ *   the same ID are debounced together
+ * @param options.debounce - Debounce delay in milliseconds
+ * @returns Promise that resolves to 'continue' if this call should proceed, or
+ *   'skip' if it was superseded
  */
 declare function awaitDebounce({ callId: _callId, debounce, }: {
     callId: __LEGIT_ANY__;

package/dist/awaitDebounce.d.ts

@@ -1,34 +1,37 @@
 import { __LEGIT_ANY__ } from './saferTyping.js';
 
 /**
- * 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'.
+ * 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.
- *
- * @param options - Configuration object
- * @param options.callId - Unique identifier for the debounce group. Calls with the same ID are debounced together
- * @param options.debounce - Debounce delay in milliseconds
- * @returns Promise that resolves to 'continue' if this call should proceed, or 'skip' if it was superseded
+ * 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.
  *
  * @example
- * ```ts
- * async function searchUsers(query: string) {
- *   const result = await awaitDebounce({ callId: 'search', debounce: 300 });
- *   if (result === 'skip') return; // This search was superseded
+ *   ```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);
- * }
+ *     // 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
- * ```
+ *   // Called rapidly - only the last call will execute
+ *   searchUsers('a');
+ *   searchUsers('ab');
+ *   searchUsers('abc'); // Only this one will continue
+ *   ```;
+ *
+ * @param options - Configuration object
+ * @param options.callId - Unique identifier for the debounce group. Calls with
+ *   the same ID are debounced together
+ * @param options.debounce - Debounce delay in milliseconds
+ * @returns Promise that resolves to 'continue' if this call should proceed, or
+ *   'skip' if it was superseded
  */
 declare function awaitDebounce({ callId: _callId, debounce, }: {
     callId: __LEGIT_ANY__;

package/dist/cache.cjs

@@ -78,7 +78,8 @@ var WithExpiration = class {
   expiration;
   /**
    * @param value - The value to store in the cache.
-   * @param expiration - The expiration time of the value in seconds or a duration object.
+   * @param expiration - The expiration time of the value in seconds or a
+   *   duration object.
    */
   constructor(value, expiration) {
     this.value = value;

package/dist/cache.d.cts

@@ -6,15 +6,15 @@ declare function cachedGetter<T>(getter: () => T): {
 type Options = {
     /**
      * The maximum number of items in the cache.
+     *
      * @default 1000
      */
     maxCacheSize?: number;
-    /**
-     * The maximum age of items in the cache.
-     */
+    /** The maximum age of items in the cache. */
     maxItemAge?: DurationObj;
     /**
      * The throttle for checking expired items in milliseconds.
+     *
      * @default
      * 10_000
      */
@@ -29,25 +29,31 @@ declare class WithExpiration<T> {
     expiration: number;
     /**
      * @param value - The value to store in the cache.
-     * @param expiration - The expiration time of the value in seconds or a duration object.
+     * @param expiration - The expiration time of the value in seconds or a
+     *   duration object.
      */
     constructor(value: T, expiration: DurationObj);
 }
 type Utils<T> = {
     skipCaching: (value: T) => SkipCaching<T>;
     /**
-     * Create a new WithExpiration object with the given value and expiration time.
+     * Create a new WithExpiration object with the given value and expiration
+     * time.
+     *
      * @param value - The value to store in the cache.
-     * @param expiration - The expiration time of the value in seconds or a duration object.
+     * @param expiration - The expiration time of the value in seconds or a
+     *   duration object.
      */
     withExpiration: (value: T, expiration: DurationObj) => WithExpiration<T>;
 };
 type GetOptions<T> = {
     /**
-     * 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.
+     * 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.
+     *
      * @param value The value to check
-     * @returns true if the value should be rejected, false otherwise
+     * @returns True if the value should be rejected, false otherwise
      */
     skipCachingWhen?: (value: T) => boolean;
 };

package/dist/cache.d.ts

@@ -6,15 +6,15 @@ declare function cachedGetter<T>(getter: () => T): {
 type Options = {
     /**
      * The maximum number of items in the cache.
+     *
      * @default 1000
      */
     maxCacheSize?: number;
-    /**
-     * The maximum age of items in the cache.
-     */
+    /** The maximum age of items in the cache. */
     maxItemAge?: DurationObj;
     /**
      * The throttle for checking expired items in milliseconds.
+     *
      * @default
      * 10_000
      */
@@ -29,25 +29,31 @@ declare class WithExpiration<T> {
     expiration: number;
     /**
      * @param value - The value to store in the cache.
-     * @param expiration - The expiration time of the value in seconds or a duration object.
+     * @param expiration - The expiration time of the value in seconds or a
+     *   duration object.
      */
     constructor(value: T, expiration: DurationObj);
 }
 type Utils<T> = {
     skipCaching: (value: T) => SkipCaching<T>;
     /**
-     * Create a new WithExpiration object with the given value and expiration time.
+     * Create a new WithExpiration object with the given value and expiration
+     * time.
+     *
      * @param value - The value to store in the cache.
-     * @param expiration - The expiration time of the value in seconds or a duration object.
+     * @param expiration - The expiration time of the value in seconds or a
+     *   duration object.
      */
     withExpiration: (value: T, expiration: DurationObj) => WithExpiration<T>;
 };
 type GetOptions<T> = {
     /**
-     * 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.
+     * 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.
+     *
      * @param value The value to check
-     * @returns true if the value should be rejected, false otherwise
+     * @returns True if the value should be rejected, false otherwise
      */
     skipCachingWhen?: (value: T) => boolean;
 };

package/dist/cache.js

@@ -29,7 +29,8 @@ var WithExpiration = class {
   expiration;
   /**
    * @param value - The value to store in the cache.
-   * @param expiration - The expiration time of the value in seconds or a duration object.
+   * @param expiration - The expiration time of the value in seconds or a
+   *   duration object.
    */
   constructor(value, expiration) {
     this.value = value;

package/dist/{chunk-GHAQOUA6.js → chunk-23KPGKDT.js}

@@ -1,3 +1,10 @@
+import {
+  typedObjectEntries
+} from "./chunk-DTE2QMWE.js";
+import {
+  sortBy
+} from "./chunk-27AL66CH.js";
+
 // src/objUtils.ts
 function objectTypedEntries(obj) {
   return Object.entries(obj);
@@ -38,6 +45,18 @@ function rejectObjUndefinedValues(obj) {
   }
   return result;
 }
+function filterObjectKeys(obj, predicate) {
+  return Object.fromEntries(
+    Object.entries(obj).filter(
+      ([key, value]) => predicate(key, value)
+    )
+  );
+}
+function sortObjectKeys(obj, sortByFn, options) {
+  return Object.fromEntries(
+    sortBy(typedObjectEntries(obj), sortByFn, options)
+  );
+}
 
 export {
   objectTypedEntries,
@@ -46,5 +65,7 @@ export {
   mapObjectToObject,
   omit,
   looseGetObjectProperty,
-  rejectObjUndefinedValues
+  rejectObjUndefinedValues,
+  filterObjectKeys,
+  sortObjectKeys
 };