@ls-stack/utils 3.7.0 → 3.9.0

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

@@ -0,0 +1,239 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/asyncQueue.ts
+var asyncQueue_exports = {};
+__export(asyncQueue_exports, {
+  createAsyncQueue: () => createAsyncQueue,
+  createAsyncQueueWithId: () => createAsyncQueueWithId
+});
+module.exports = __toCommonJS(asyncQueue_exports);
+var import_evtmitter = require("evtmitter");
+var import_t_result = require("t-result");
+
+// src/assertions.ts
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isFunction(value) {
+  return typeof value === "function";
+}
+function isPromise(value) {
+  return isObject(value) && "then" in value && isFunction(value.then);
+}
+
+// src/promiseUtils.ts
+function defer() {
+  let resolve;
+  let reject;
+  const promise = new Promise((_resolve, _reject) => {
+    resolve = _resolve;
+    reject = _reject;
+  });
+  return { resolve, reject, promise };
+}
+
+// src/asyncQueue.ts
+var AsyncQueue = class {
+  #queue = [];
+  #pending = 0;
+  #size = 0;
+  #concurrency;
+  #completed = 0;
+  #failed = 0;
+  #idleResolvers = [];
+  events = (0, import_evtmitter.evtmitter)();
+  #signal;
+  #taskTimeout;
+  constructor({
+    concurrency = 1,
+    signal,
+    timeout: taskTimeout
+  } = {}) {
+    this.#concurrency = concurrency;
+    this.#signal = signal;
+    this.#taskTimeout = taskTimeout;
+  }
+  #enqueue(task) {
+    this.#queue.push(task);
+    this.#size++;
+  }
+  add(fn, options) {
+    const deferred = defer();
+    const taskTimeout = this.#taskTimeout ?? options?.timeout;
+    const task = {
+      run: async (ctx) => {
+        if (isPromise(fn)) {
+          return fn;
+        }
+        return await fn(ctx);
+      },
+      resolve: deferred.resolve,
+      reject: deferred.reject,
+      signal: options?.signal,
+      id: options?.id,
+      timeout: taskTimeout
+    };
+    this.#enqueue(task);
+    this.#processQueue();
+    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);
+  }
+  async #processQueue() {
+    if (this.#pending >= this.#concurrency || this.#queue.length === 0) {
+      return;
+    }
+    const task = this.#queue.shift();
+    if (!task) {
+      return;
+    }
+    this.#pending++;
+    this.#size--;
+    const signals = [];
+    if (task.signal) {
+      signals.push(task.signal);
+    }
+    if (this.#signal) {
+      signals.push(this.#signal);
+    }
+    if (task.timeout) {
+      signals.push(AbortSignal.timeout(task.timeout));
+    }
+    const signal = signals.length > 1 ? AbortSignal.any(signals) : signals[0];
+    let abortListener;
+    const signalAbortPromise = new Promise((_, reject) => {
+      if (signal) {
+        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 });
+      }
+    });
+    try {
+      const taskRunPromise = task.run({ signal, id: task.id });
+      this.events.emit("start", { id: task.id });
+      const result = await Promise.race([taskRunPromise, signalAbortPromise]);
+      if ((0, import_t_result.isResult)(result)) {
+        task.resolve(result);
+        if (result.error) {
+          this.#failed++;
+          this.events.emit("error", { id: task.id, error: result.error });
+        } else {
+          this.#completed++;
+          this.events.emit("complete", { id: task.id, value: result.value });
+        }
+      } else {
+        const error = new Error("Response not a Result");
+        task.resolve(import_t_result.Result.err(error));
+        this.#failed++;
+        this.events.emit("error", {
+          id: task.id,
+          error: (0, import_t_result.unknownToError)(error)
+        });
+      }
+    } catch (error) {
+      task.resolve(import_t_result.Result.err(error));
+      this.#failed++;
+      this.events.emit("error", { id: task.id, error: (0, import_t_result.unknownToError)(error) });
+    } finally {
+      if (signal && abortListener) {
+        signal.removeEventListener("abort", abortListener);
+      }
+      this.#pending--;
+      this.#processQueue();
+      if (this.#pending === 0 && this.#size === 0) {
+        this.#resolveIdleWaiters();
+      }
+    }
+  }
+  #resolveIdleWaiters() {
+    while (this.#idleResolvers.length > 0) {
+      const resolve = this.#idleResolvers.shift();
+      if (resolve) {
+        resolve();
+      }
+    }
+  }
+  async onIdle() {
+    if (this.#pending === 0 && this.#size === 0) {
+      return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+      this.#idleResolvers.push(resolve);
+    });
+  }
+  clear({ resetCounters = true } = {}) {
+    this.#queue = [];
+    this.#size = 0;
+    if (resetCounters) {
+      this.#completed = 0;
+      this.#failed = 0;
+    }
+    if (this.#pending === 0) {
+      this.#resolveIdleWaiters();
+    }
+  }
+  get completed() {
+    return this.#completed;
+  }
+  get failed() {
+    return this.#failed;
+  }
+  get pending() {
+    return this.#pending;
+  }
+  get size() {
+    return this.#size;
+  }
+};
+var AsyncQueueWithId = class extends AsyncQueue {
+  constructor(options) {
+    super(options);
+  }
+  add(fn, options) {
+    return super.add(fn, options);
+  }
+  resultifyAdd(fn, options) {
+    return super.resultifyAdd(fn, options);
+  }
+};
+function createAsyncQueue(options) {
+  return new AsyncQueue(options);
+}
+function createAsyncQueueWithId(options) {
+  return new AsyncQueueWithId(options);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createAsyncQueue,
+  createAsyncQueueWithId
+});

package/lib/asyncQueue.d.cts

@@ -0,0 +1,56 @@
+import * as evtmitter from 'evtmitter';
+import { ResultValidErrors, Result } from 't-result';
+
+type AsyncQueueOptions = {
+    concurrency?: number;
+    signal?: AbortSignal;
+    timeout?: number;
+};
+type AddOptions<I> = {
+    signal?: AbortSignal;
+    timeout?: number;
+    id?: I;
+};
+type RunCtx<I> = {
+    signal?: AbortSignal;
+    id?: I;
+};
+declare class AsyncQueue<T, E extends ResultValidErrors = Error, I = undefined> {
+    #private;
+    events: evtmitter.Emitter<{
+        error: {
+            id: I;
+            error: E | Error;
+        };
+        complete: {
+            id: I;
+            value: T;
+        };
+        start: {
+            id: I;
+        };
+    }>;
+    constructor({ concurrency, signal, timeout: taskTimeout, }?: AsyncQueueOptions);
+    add(fn: ((ctx: RunCtx<I>) => Promise<Result<T, E>> | Result<T, E>) | Promise<Result<T, E>>, options?: AddOptions<I>): Promise<Result<T, E | Error>>;
+    resultifyAdd(fn: ((ctx: RunCtx<I>) => Promise<T> | T) | Promise<T>, options?: AddOptions<I>): Promise<Result<T, E | Error>>;
+    onIdle(): Promise<void>;
+    clear({ resetCounters }?: {
+        resetCounters?: boolean;
+    }): void;
+    get completed(): number;
+    get failed(): number;
+    get pending(): number;
+    get size(): number;
+}
+type AddOptionsWithId<I> = Omit<AddOptions<I>, 'id'> & {
+    id: I;
+};
+declare class AsyncQueueWithId<T, I, E extends ResultValidErrors = Error> extends AsyncQueue<T, E, I> {
+    constructor(options?: AsyncQueueOptions);
+    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 createAsyncQueueWithId<T, I, E extends ResultValidErrors = Error>(options?: AsyncQueueOptions): AsyncQueueWithId<T, I, E>;
+
+export { createAsyncQueue, createAsyncQueueWithId };

package/lib/asyncQueue.d.ts

@@ -0,0 +1,56 @@
+import * as evtmitter from 'evtmitter';
+import { ResultValidErrors, Result } from 't-result';
+
+type AsyncQueueOptions = {
+    concurrency?: number;
+    signal?: AbortSignal;
+    timeout?: number;
+};
+type AddOptions<I> = {
+    signal?: AbortSignal;
+    timeout?: number;
+    id?: I;
+};
+type RunCtx<I> = {
+    signal?: AbortSignal;
+    id?: I;
+};
+declare class AsyncQueue<T, E extends ResultValidErrors = Error, I = undefined> {
+    #private;
+    events: evtmitter.Emitter<{
+        error: {
+            id: I;
+            error: E | Error;
+        };
+        complete: {
+            id: I;
+            value: T;
+        };
+        start: {
+            id: I;
+        };
+    }>;
+    constructor({ concurrency, signal, timeout: taskTimeout, }?: AsyncQueueOptions);
+    add(fn: ((ctx: RunCtx<I>) => Promise<Result<T, E>> | Result<T, E>) | Promise<Result<T, E>>, options?: AddOptions<I>): Promise<Result<T, E | Error>>;
+    resultifyAdd(fn: ((ctx: RunCtx<I>) => Promise<T> | T) | Promise<T>, options?: AddOptions<I>): Promise<Result<T, E | Error>>;
+    onIdle(): Promise<void>;
+    clear({ resetCounters }?: {
+        resetCounters?: boolean;
+    }): void;
+    get completed(): number;
+    get failed(): number;
+    get pending(): number;
+    get size(): number;
+}
+type AddOptionsWithId<I> = Omit<AddOptions<I>, 'id'> & {
+    id: I;
+};
+declare class AsyncQueueWithId<T, I, E extends ResultValidErrors = Error> extends AsyncQueue<T, E, I> {
+    constructor(options?: AsyncQueueOptions);
+    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 createAsyncQueueWithId<T, I, E extends ResultValidErrors = Error>(options?: AsyncQueueOptions): AsyncQueueWithId<T, I, E>;
+
+export { createAsyncQueue, createAsyncQueueWithId };

package/lib/asyncQueue.js

@@ -0,0 +1,201 @@
+import {
+  defer
+} from "./chunk-DFXNVEH6.js";
+import {
+  isPromise
+} from "./chunk-3XCS7FVO.js";
+
+// src/asyncQueue.ts
+import { evtmitter } from "evtmitter";
+import {
+  isResult,
+  Result,
+  resultify,
+  unknownToError
+} from "t-result";
+var AsyncQueue = class {
+  #queue = [];
+  #pending = 0;
+  #size = 0;
+  #concurrency;
+  #completed = 0;
+  #failed = 0;
+  #idleResolvers = [];
+  events = evtmitter();
+  #signal;
+  #taskTimeout;
+  constructor({
+    concurrency = 1,
+    signal,
+    timeout: taskTimeout
+  } = {}) {
+    this.#concurrency = concurrency;
+    this.#signal = signal;
+    this.#taskTimeout = taskTimeout;
+  }
+  #enqueue(task) {
+    this.#queue.push(task);
+    this.#size++;
+  }
+  add(fn, options) {
+    const deferred = defer();
+    const taskTimeout = this.#taskTimeout ?? options?.timeout;
+    const task = {
+      run: async (ctx) => {
+        if (isPromise(fn)) {
+          return fn;
+        }
+        return await fn(ctx);
+      },
+      resolve: deferred.resolve,
+      reject: deferred.reject,
+      signal: options?.signal,
+      id: options?.id,
+      timeout: taskTimeout
+    };
+    this.#enqueue(task);
+    this.#processQueue();
+    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);
+  }
+  async #processQueue() {
+    if (this.#pending >= this.#concurrency || this.#queue.length === 0) {
+      return;
+    }
+    const task = this.#queue.shift();
+    if (!task) {
+      return;
+    }
+    this.#pending++;
+    this.#size--;
+    const signals = [];
+    if (task.signal) {
+      signals.push(task.signal);
+    }
+    if (this.#signal) {
+      signals.push(this.#signal);
+    }
+    if (task.timeout) {
+      signals.push(AbortSignal.timeout(task.timeout));
+    }
+    const signal = signals.length > 1 ? AbortSignal.any(signals) : signals[0];
+    let abortListener;
+    const signalAbortPromise = new Promise((_, reject) => {
+      if (signal) {
+        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 });
+      }
+    });
+    try {
+      const taskRunPromise = task.run({ signal, id: task.id });
+      this.events.emit("start", { id: task.id });
+      const result = await Promise.race([taskRunPromise, signalAbortPromise]);
+      if (isResult(result)) {
+        task.resolve(result);
+        if (result.error) {
+          this.#failed++;
+          this.events.emit("error", { id: task.id, error: result.error });
+        } else {
+          this.#completed++;
+          this.events.emit("complete", { id: task.id, value: result.value });
+        }
+      } else {
+        const error = new Error("Response not a Result");
+        task.resolve(Result.err(error));
+        this.#failed++;
+        this.events.emit("error", {
+          id: task.id,
+          error: unknownToError(error)
+        });
+      }
+    } catch (error) {
+      task.resolve(Result.err(error));
+      this.#failed++;
+      this.events.emit("error", { id: task.id, error: unknownToError(error) });
+    } finally {
+      if (signal && abortListener) {
+        signal.removeEventListener("abort", abortListener);
+      }
+      this.#pending--;
+      this.#processQueue();
+      if (this.#pending === 0 && this.#size === 0) {
+        this.#resolveIdleWaiters();
+      }
+    }
+  }
+  #resolveIdleWaiters() {
+    while (this.#idleResolvers.length > 0) {
+      const resolve = this.#idleResolvers.shift();
+      if (resolve) {
+        resolve();
+      }
+    }
+  }
+  async onIdle() {
+    if (this.#pending === 0 && this.#size === 0) {
+      return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+      this.#idleResolvers.push(resolve);
+    });
+  }
+  clear({ resetCounters = true } = {}) {
+    this.#queue = [];
+    this.#size = 0;
+    if (resetCounters) {
+      this.#completed = 0;
+      this.#failed = 0;
+    }
+    if (this.#pending === 0) {
+      this.#resolveIdleWaiters();
+    }
+  }
+  get completed() {
+    return this.#completed;
+  }
+  get failed() {
+    return this.#failed;
+  }
+  get pending() {
+    return this.#pending;
+  }
+  get size() {
+    return this.#size;
+  }
+};
+var AsyncQueueWithId = class extends AsyncQueue {
+  constructor(options) {
+    super(options);
+  }
+  add(fn, options) {
+    return super.add(fn, options);
+  }
+  resultifyAdd(fn, options) {
+    return super.resultifyAdd(fn, options);
+  }
+};
+function createAsyncQueue(options) {
+  return new AsyncQueue(options);
+}
+function createAsyncQueueWithId(options) {
+  return new AsyncQueueWithId(options);
+}
+export {
+  createAsyncQueue,
+  createAsyncQueueWithId
+};

package/lib/cache.js

@@ -2,10 +2,10 @@ import {
   durationObjToMs
 } from "./chunk-5MNYPLZI.js";
 import "./chunk-HTCYUMDR.js";
+import "./chunk-II4R3VVX.js";
 import {
   isPromise
 } from "./chunk-3XCS7FVO.js";
-import "./chunk-II4R3VVX.js";
 
 // src/cache.ts
 function cachedGetter(getter) {

package/lib/chunk-DFXNVEH6.js

@@ -0,0 +1,14 @@
+// src/promiseUtils.ts
+function defer() {
+  let resolve;
+  let reject;
+  const promise = new Promise((_resolve, _reject) => {
+    resolve = _resolve;
+    reject = _reject;
+  });
+  return { resolve, reject, promise };
+}
+
+export {
+  defer
+};

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
 };