@ls-stack/utils 3.8.0 → 3.9.1

package/README.md

@@ -1 +1,82 @@
-# Generic typescript 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';
+```
+
+## 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.
+
+### 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/lib/arrayUtils.cjs

@@ -29,9 +29,17 @@ __export(arrayUtils_exports, {
   isInArray: () => isInArray,
   rejectArrayUndefinedValues: () => rejectArrayUndefinedValues,
   rejectDuplicates: () => rejectDuplicates,
-  sortBy: () => sortBy
+  sortBy: () => sortBy,
+  truncateArray: () => truncateArray
 });
 module.exports = __toCommonJS(arrayUtils_exports);
+
+// src/assertions.ts
+function isFunction(value) {
+  return typeof value === "function";
+}
+
+// src/arrayUtils.ts
 function filterAndMap(array, mapFilter) {
   const result = [];
   let i = -1;
@@ -133,6 +141,17 @@ function rejectDuplicates(array, getKey = (item) => item) {
   }
   return result;
 }
+function truncateArray(array, maxLength, appendIfTruncated) {
+  const truncate = array.length > maxLength;
+  const result = truncate ? [...array.slice(0, maxLength)] : array;
+  if (truncate && appendIfTruncated) {
+    if (isFunction(appendIfTruncated)) {
+      return [...result, appendIfTruncated(array.length - maxLength)];
+    }
+    return [...result, appendIfTruncated];
+  }
+  return result;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   arrayWithPrev,
@@ -144,5 +163,6 @@ function rejectDuplicates(array, getKey = (item) => item) {
   isInArray,
   rejectArrayUndefinedValues,
   rejectDuplicates,
-  sortBy
+  sortBy,
+  truncateArray
 });

package/lib/arrayUtils.d.cts

@@ -52,5 +52,6 @@ declare function findBeforeIndex<T>(array: T[], index: number, predicate: (item:
 declare function rejectArrayUndefinedValues<T extends unknown[]>(array: T): T;
 declare function hasDuplicates<T>(array: T[], getKey?: (item: T) => unknown): boolean;
 declare function rejectDuplicates<T>(array: T[], getKey?: (item: T) => unknown): T[];
+declare function truncateArray<T>(array: T[], maxLength: number, appendIfTruncated?: T | ((truncatedCount: number) => T)): T[];
 
-export { type FilterAndMapReturn, arrayWithPrev, arrayWithPrevAndIndex, filterAndMap, findAfterIndex, findBeforeIndex, hasDuplicates, isInArray, rejectArrayUndefinedValues, rejectDuplicates, sortBy };
+export { type FilterAndMapReturn, arrayWithPrev, arrayWithPrevAndIndex, filterAndMap, findAfterIndex, findBeforeIndex, hasDuplicates, isInArray, rejectArrayUndefinedValues, rejectDuplicates, sortBy, truncateArray };

package/lib/arrayUtils.d.ts

@@ -52,5 +52,6 @@ declare function findBeforeIndex<T>(array: T[], index: number, predicate: (item:
 declare function rejectArrayUndefinedValues<T extends unknown[]>(array: T): T;
 declare function hasDuplicates<T>(array: T[], getKey?: (item: T) => unknown): boolean;
 declare function rejectDuplicates<T>(array: T[], getKey?: (item: T) => unknown): T[];
+declare function truncateArray<T>(array: T[], maxLength: number, appendIfTruncated?: T | ((truncatedCount: number) => T)): T[];
 
-export { type FilterAndMapReturn, arrayWithPrev, arrayWithPrevAndIndex, filterAndMap, findAfterIndex, findBeforeIndex, hasDuplicates, isInArray, rejectArrayUndefinedValues, rejectDuplicates, sortBy };
+export { type FilterAndMapReturn, arrayWithPrev, arrayWithPrevAndIndex, filterAndMap, findAfterIndex, findBeforeIndex, hasDuplicates, isInArray, rejectArrayUndefinedValues, rejectDuplicates, sortBy, truncateArray };

package/lib/arrayUtils.js

@@ -8,8 +8,10 @@ import {
   isInArray,
   rejectArrayUndefinedValues,
   rejectDuplicates,
-  sortBy
-} from "./chunk-XMUFRC2U.js";
+  sortBy,
+  truncateArray
+} from "./chunk-UTFE4P3P.js";
+import "./chunk-3XCS7FVO.js";
 export {
   arrayWithPrev,
   arrayWithPrevAndIndex,
@@ -20,5 +22,6 @@ export {
   isInArray,
   rejectArrayUndefinedValues,
   rejectDuplicates,
-  sortBy
+  sortBy,
+  truncateArray
 };

package/lib/asyncQueue.cjs

@@ -95,13 +95,15 @@ var AsyncQueue = class {
     return deferred.promise;
   }
   resultifyAdd(fn, options) {
-    const cb = async (ctx) => {
-      if (isPromise(fn)) {
-        return await fn;
-      }
-      return fn(ctx);
-    };
-    return this.add((ctx) => (0, import_t_result.resultify)(cb(ctx)), options);
+    return this.add(
+      (ctx) => (0, import_t_result.resultify)(async () => {
+        if (isPromise(fn)) {
+          return await fn;
+        }
+        return fn(ctx);
+      }),
+      options
+    );
   }
   async #processQueue() {
     if (this.#pending >= this.#concurrency || this.#queue.length === 0) {
@@ -125,20 +127,20 @@ var AsyncQueue = class {
     }
     const signal = signals.length > 1 ? AbortSignal.any(signals) : signals[0];
     let abortListener;
-    const signalAbortPromise = new Promise((_, reject) => {
-      if (signal) {
+    try {
+      if (signal?.aborted) {
         const error = signal.reason instanceof Error ? signal.reason : new DOMException("Aborted", "AbortError");
-        if (signal.aborted) {
-          reject(error);
-          return;
-        }
-        abortListener = () => {
-          reject(error);
-        };
-        signal.addEventListener("abort", abortListener, { once: true });
+        throw error;
       }
-    });
-    try {
+      const signalAbortPromise = new Promise((_, reject) => {
+        if (signal) {
+          const error = signal.reason instanceof Error ? signal.reason : new DOMException("Aborted", "AbortError");
+          abortListener = () => {
+            reject(error);
+          };
+          signal.addEventListener("abort", abortListener, { once: true });
+        }
+      });
       const taskRunPromise = task.run({ signal, id: task.id });
       this.events.emit("start", { id: task.id });
       const result = await Promise.race([taskRunPromise, signalAbortPromise]);
@@ -157,7 +159,7 @@ var AsyncQueue = class {
         this.#failed++;
         this.events.emit("error", {
           id: task.id,
-          error: (0, import_t_result.unknownToError)(error)
+          error
         });
       }
     } catch (error) {

package/lib/asyncQueue.d.cts

@@ -50,7 +50,7 @@ declare class AsyncQueueWithId<T, I, E extends ResultValidErrors = Error> extend
     add(fn: ((ctx: RunCtx<I>) => Promise<Result<T, E>> | Result<T, E>) | Promise<Result<T, E>>, options?: AddOptionsWithId<I>): Promise<Result<T, E | Error>>;
     resultifyAdd(fn: ((ctx: RunCtx<I>) => Promise<T> | T) | Promise<T>, options?: AddOptionsWithId<I>): Promise<Result<T, E | Error>>;
 }
-declare function createAsyncQueue<T, E extends ResultValidErrors = Error>(options?: AsyncQueueOptions): AsyncQueue<T, E, undefined>;
+declare function createAsyncQueue<T, E extends ResultValidErrors = Error>(options?: AsyncQueueOptions): AsyncQueue<T, E>;
 declare function createAsyncQueueWithId<T, I, E extends ResultValidErrors = Error>(options?: AsyncQueueOptions): AsyncQueueWithId<T, I, E>;
 
 export { createAsyncQueue, createAsyncQueueWithId };

package/lib/asyncQueue.d.ts

@@ -50,7 +50,7 @@ declare class AsyncQueueWithId<T, I, E extends ResultValidErrors = Error> extend
     add(fn: ((ctx: RunCtx<I>) => Promise<Result<T, E>> | Result<T, E>) | Promise<Result<T, E>>, options?: AddOptionsWithId<I>): Promise<Result<T, E | Error>>;
     resultifyAdd(fn: ((ctx: RunCtx<I>) => Promise<T> | T) | Promise<T>, options?: AddOptionsWithId<I>): Promise<Result<T, E | Error>>;
 }
-declare function createAsyncQueue<T, E extends ResultValidErrors = Error>(options?: AsyncQueueOptions): AsyncQueue<T, E, undefined>;
+declare function createAsyncQueue<T, E extends ResultValidErrors = Error>(options?: AsyncQueueOptions): AsyncQueue<T, E>;
 declare function createAsyncQueueWithId<T, I, E extends ResultValidErrors = Error>(options?: AsyncQueueOptions): AsyncQueueWithId<T, I, E>;
 
 export { createAsyncQueue, createAsyncQueueWithId };

package/lib/asyncQueue.js

@@ -58,13 +58,15 @@ var AsyncQueue = class {
     return deferred.promise;
   }
   resultifyAdd(fn, options) {
-    const cb = async (ctx) => {
-      if (isPromise(fn)) {
-        return await fn;
-      }
-      return fn(ctx);
-    };
-    return this.add((ctx) => resultify(cb(ctx)), options);
+    return this.add(
+      (ctx) => resultify(async () => {
+        if (isPromise(fn)) {
+          return await fn;
+        }
+        return fn(ctx);
+      }),
+      options
+    );
   }
   async #processQueue() {
     if (this.#pending >= this.#concurrency || this.#queue.length === 0) {
@@ -88,20 +90,20 @@ var AsyncQueue = class {
     }
     const signal = signals.length > 1 ? AbortSignal.any(signals) : signals[0];
     let abortListener;
-    const signalAbortPromise = new Promise((_, reject) => {
-      if (signal) {
+    try {
+      if (signal?.aborted) {
         const error = signal.reason instanceof Error ? signal.reason : new DOMException("Aborted", "AbortError");
-        if (signal.aborted) {
-          reject(error);
-          return;
-        }
-        abortListener = () => {
-          reject(error);
-        };
-        signal.addEventListener("abort", abortListener, { once: true });
+        throw error;
       }
-    });
-    try {
+      const signalAbortPromise = new Promise((_, reject) => {
+        if (signal) {
+          const error = signal.reason instanceof Error ? signal.reason : new DOMException("Aborted", "AbortError");
+          abortListener = () => {
+            reject(error);
+          };
+          signal.addEventListener("abort", abortListener, { once: true });
+        }
+      });
       const taskRunPromise = task.run({ signal, id: task.id });
       this.events.emit("start", { id: task.id });
       const result = await Promise.race([taskRunPromise, signalAbortPromise]);
@@ -120,7 +122,7 @@ var AsyncQueue = class {
         this.#failed++;
         this.events.emit("error", {
           id: task.id,
-          error: unknownToError(error)
+          error
         });
       }
     } catch (error) {

package/lib/{chunk-XMUFRC2U.js → chunk-UTFE4P3P.js}

@@ -1,3 +1,7 @@
+import {
+  isFunction
+} from "./chunk-3XCS7FVO.js";
+
 // src/arrayUtils.ts
 function filterAndMap(array, mapFilter) {
   const result = [];
@@ -100,6 +104,17 @@ function rejectDuplicates(array, getKey = (item) => item) {
   }
   return result;
 }
+function truncateArray(array, maxLength, appendIfTruncated) {
+  const truncate = array.length > maxLength;
+  const result = truncate ? [...array.slice(0, maxLength)] : array;
+  if (truncate && appendIfTruncated) {
+    if (isFunction(appendIfTruncated)) {
+      return [...result, appendIfTruncated(array.length - maxLength)];
+    }
+    return [...result, appendIfTruncated];
+  }
+  return result;
+}
 
 export {
   filterAndMap,
@@ -111,5 +126,6 @@ export {
   findBeforeIndex,
   rejectArrayUndefinedValues,
   hasDuplicates,
-  rejectDuplicates
+  rejectDuplicates,
+  truncateArray
 };

package/lib/concurrentCalls.cjs

@@ -42,11 +42,30 @@ function isPromise(value) {
   return isObject(value) && "then" in value && isFunction(value.then);
 }
 
+// src/arrayUtils.ts
+function truncateArray(array, maxLength, appendIfTruncated) {
+  const truncate = array.length > maxLength;
+  const result = truncate ? [...array.slice(0, maxLength)] : array;
+  if (truncate && appendIfTruncated) {
+    if (isFunction(appendIfTruncated)) {
+      return [...result, appendIfTruncated(array.length - maxLength)];
+    }
+    return [...result, appendIfTruncated];
+  }
+  return result;
+}
+
 // src/sleep.ts
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+// src/stringUtils.ts
+function truncateString(str, length, ellipsis = "\u2026") {
+  if (str.length <= length) return str;
+  return str.slice(0, length - 1) + ellipsis;
+}
+
 // src/concurrentCalls.ts
 var ConcurrentCalls = class {
   #pendingCalls = [];
@@ -266,7 +285,11 @@ var ConcurrentCallsWithMetadata = class {
     const allFailed = failedProcessing.length === total;
     const aggregatedError = failedProcessing.length > 0 ? new AggregateError(
       failedProcessing.map((f) => f.error),
-      "One or more calls failed"
+      `${failedProcessing.length}/${total} calls failed: ${truncateArray(
+        failedProcessing.map((f) => truncateString(f.error.message, 20)),
+        5,
+        "..."
+      ).join("; ")}`
     ) : null;
     return {
       succeeded: succeededProcessing,

package/lib/concurrentCalls.js

@@ -1,6 +1,12 @@
+import {
+  truncateString
+} from "./chunk-4REIIZQY.js";
 import {
   sleep
 } from "./chunk-5DZT3Z5Z.js";
+import {
+  truncateArray
+} from "./chunk-UTFE4P3P.js";
 import {
   invariant,
   isPromise
@@ -226,7 +232,11 @@ var ConcurrentCallsWithMetadata = class {
     const allFailed = failedProcessing.length === total;
     const aggregatedError = failedProcessing.length > 0 ? new AggregateError(
       failedProcessing.map((f) => f.error),
-      "One or more calls failed"
+      `${failedProcessing.length}/${total} calls failed: ${truncateArray(
+        failedProcessing.map((f) => truncateString(f.error.message, 20)),
+        5,
+        "..."
+      ).join("; ")}`
     ) : null;
     return {
       succeeded: succeededProcessing,

package/lib/testUtils.cjs

@@ -25,6 +25,11 @@ __export(testUtils_exports, {
 });
 module.exports = __toCommonJS(testUtils_exports);
 
+// src/assertions.ts
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 // src/arrayUtils.ts
 function filterAndMap(array, mapFilter) {
   const result = [];
@@ -46,11 +51,6 @@ function arrayWithPrevAndIndex(array) {
   }));
 }
 
-// src/assertions.ts
-function isObject(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 // src/deepEqual.ts
 var has = Object.prototype.hasOwnProperty;
 function find(iter, tar, maxDepth) {

package/lib/testUtils.js

@@ -5,13 +5,13 @@ import {
 import {
   deepEqual
 } from "./chunk-JQFUKJU5.js";
-import {
-  arrayWithPrevAndIndex,
-  filterAndMap
-} from "./chunk-XMUFRC2U.js";
 import {
   clampMin
 } from "./chunk-HTCYUMDR.js";
+import {
+  arrayWithPrevAndIndex,
+  filterAndMap
+} from "./chunk-UTFE4P3P.js";
 import {
   isObject
 } from "./chunk-3XCS7FVO.js";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ls-stack/utils",
   "description": "Typescript utils",
-  "version": "3.8.0",
+  "version": "3.9.1",
   "license": "MIT",
   "files": [
     "lib"
@@ -179,6 +179,9 @@
     "prettier-plugin-organize-imports": "^4.1.0",
     "tsm": "^2.3.0",
     "tsup": "^8.3.5",
+    "typedoc": "^0.28.4",
+    "typedoc-plugin-markdown": "^4.6.3",
+    "typedoc-plugin-missing-exports": "^4.0.0",
     "typescript": "^5.7.3",
     "typescript-eslint": "^8.21.0",
     "vite": "^6.0.11",
@@ -195,12 +198,14 @@
     "tsc": "tsc -p tsconfig.prod.json",
     "tsc:watch": "tsc -p tsconfig.prod.json --watch",
     "eslint": "CI=true eslint src/ scripts/ --color --max-warnings=0",
-    "build": "pnpm test && pnpm lint && pnpm build:no-test && pnpm build:update-exports",
+    "build": "pnpm test && pnpm lint && pnpm build:no-test && pnpm docs && pnpm build:update-exports",
     "build:no-test": "tsup",
     "build:update-exports": "tsm --no-warnings scripts/updatePackageExports.ts",
     "build-test": "tsup --config tsup.test.config.ts",
     "pre-publish": "./scripts/check-if-is-sync.sh && pnpm build",
     "test:console-fmt": "tsm --no-warnings scripts/testConsoleFmt.ts",
-    "bench:deepEqual": "tsm --no-warnings benchmarks/deepEqual.ts"
+    "bench:deepEqual": "tsm --no-warnings benchmarks/deepEqual.ts",
+    "docs": "typedoc",
+    "docs:watch": "typedoc --watch"
   }
 }