@ls-stack/utils 3.63.0 → 3.66.0

package/dist/{concurrentCalls.d.ts → concurrentCalls.d.mts}

@@ -1,61 +1,66 @@
-import { ResultValidErrors, Result } from 't-result';
+import { Result, ResultValidErrors } from "t-result";
 
+//#region src/concurrentCalls.d.ts
 declare class ConcurrentCallsAggregateError extends AggregateError {
-    errors: ResultValidErrors[];
-    total: number;
-    failed: number;
-    constructor(errors: ResultValidErrors[], total: number, failed: number);
+  errors: ResultValidErrors[];
+  total: number;
+  failed: number;
+  constructor(errors: ResultValidErrors[], total: number, failed: number);
 }
 declare class ConcurrentCallsWithMetadataAggregateError<M extends ValidMetadata> extends AggregateError {
-    errors: ResultValidErrors[];
-    errorsWithMetadata: {
-        error: ResultValidErrors;
-        metadata: M;
-    }[];
-    total: number;
-    failed: number;
-    constructor(errors: {
-        error: ResultValidErrors;
-        metadata: M;
-    }[], total: number, failed: number);
+  errors: ResultValidErrors[];
+  errorsWithMetadata: {
+    error: ResultValidErrors;
+    metadata: M;
+  }[];
+  total: number;
+  failed: number;
+  constructor(errors: {
+    error: ResultValidErrors;
+    metadata: M;
+  }[], total: number, failed: number);
 }
 type ValidMetadata = string | number | boolean | Record<string, unknown>;
 type RunProps = {
-    delayStart?: (index: number) => number;
+  delayStart?: (index: number) => number;
 };
 type SucceededCall<R, M> = {
-    value: R;
-    metadata: M;
+  value: R;
+  metadata: M;
 };
 type FailedCall<M, E extends ResultValidErrors = Error> = {
-    metadata: M;
-    error: E;
+  metadata: M;
+  error: E;
 };
 type Action<R, E extends ResultValidErrors> = () => Promise<Result<R, E>>;
 type SettledResultWithMetadata<R, M, E extends ResultValidErrors = Error> = {
-    ok: true;
-    value: R;
-    metadata: M;
-    error: false;
+  ok: true;
+  value: R;
+  metadata: M;
+  error: false;
 } | {
-    ok: false;
-    error: E;
-    metadata: M;
+  ok: false;
+  error: E;
+  metadata: M;
 };
 declare class ConcurrentCalls<R = unknown, E extends ResultValidErrors = Error> {
-    #private;
-    allowResultify: boolean;
-    constructor(allowResultify: boolean);
-    add(...calls: Action<R, E>[]): this;
-    resultifyAdd(...calls: ((() => R) | (() => Promise<R>))[]): this;
-    runAll({ delayStart }?: RunProps): Promise<Result<R[], E>>;
-    runAllSettled({ delayStart }?: RunProps): Promise<{
-        allFailed: boolean;
-        failures: E[];
-        succeeded: R[];
-        total: number;
-        aggregatedError: ConcurrentCallsAggregateError | null;
-    }>;
+  #private;
+  allowResultify: boolean;
+  constructor(allowResultify: boolean);
+  add(...calls: Action<R, E>[]): this;
+  resultifyAdd(...calls: ((() => R) | (() => Promise<R>))[]): this;
+  runAll({
+    delayStart
+  }?: RunProps): Promise<Result<R[], E>>;
+  runAllSettled({
+    delayStart
+  }?: RunProps): Promise<{
+    allFailed: boolean;
+    failures: E[];
+    succeeded: R[];
+    total: number;
+    aggregatedError: ConcurrentCallsAggregateError | null;
+  }>;
 }
 /**
  * Executes multiple asynchronous calls concurrently and collects the results in
@@ -65,28 +70,32 @@ declare class ConcurrentCalls<R = unknown, E extends ResultValidErrors = Error>
  */
 declare function concurrentCalls<R = unknown>(): ConcurrentCalls<R, Error>;
 declare class ConcurrentCallsWithMetadata<M extends ValidMetadata, R = unknown, E extends ResultValidErrors = Error> {
-    #private;
-    allowResultify: boolean;
-    constructor(allowResultify: boolean);
-    add(...calls: {
-        fn: Action<R, E>;
-        metadata: M;
-    }[]): this;
-    resultifyAdd(...items: {
-        fn: (() => R) | (() => Promise<R>);
-        metadata: M;
-    }[]): this;
-    runAll({ delayStart }?: RunProps): Promise<Result<SucceededCall<R, M>[], FailedCall<M, E>>>;
-    runAllSettled({ delayStart }?: RunProps): Promise<{
-        allFailed: boolean;
-        /** @deprecated Use failures property instead */
-        failed: FailedCall<M, E>[];
-        failures: FailedCall<M, E>[];
-        succeeded: SucceededCall<R, M>[];
-        total: number;
-        results: SettledResultWithMetadata<R, M, E>[];
-        aggregatedError: ConcurrentCallsWithMetadataAggregateError<M> | null;
-    }>;
+  #private;
+  allowResultify: boolean;
+  constructor(allowResultify: boolean);
+  add(...calls: {
+    fn: Action<R, E>;
+    metadata: M;
+  }[]): this;
+  resultifyAdd(...items: {
+    fn: (() => R) | (() => Promise<R>);
+    metadata: M;
+  }[]): this;
+  runAll({
+    delayStart
+  }?: RunProps): Promise<Result<SucceededCall<R, M>[], FailedCall<M, E>>>;
+  runAllSettled({
+    delayStart
+  }?: RunProps): Promise<{
+    allFailed: boolean;
+    /** @deprecated Use failures property instead */
+    failed: FailedCall<M, E>[];
+    failures: FailedCall<M, E>[];
+    succeeded: SucceededCall<R, M>[];
+    total: number;
+    results: SettledResultWithMetadata<R, M, E>[];
+    aggregatedError: ConcurrentCallsWithMetadataAggregateError<M> | null;
+  }>;
 }
 /**
  * Executes multiple asynchronous calls concurrently with metadata for each call
@@ -112,5 +121,5 @@ declare function concurrentResultCalls<ResultFn extends (...args: any[]) => Prom
  * @template ResultFn - The type of the result function that will be called.
  */
 declare function concurrentResultsWithMetadata<M extends ValidMetadata, ResultFn extends (...args: any[]) => Promise<Result<unknown, ResultValidErrors>>>(): ConcurrentCallsWithMetadata<M, ValueFromResult<Awaited<ReturnType<ResultFn>>>, ErrorFromResult<Awaited<ReturnType<ResultFn>>>>;
-
-export { ConcurrentCallsAggregateError, ConcurrentCallsWithMetadataAggregateError, concurrentCalls, concurrentCallsWithMetadata, concurrentResultCalls, concurrentResultsWithMetadata };
+//#endregion
+export { ConcurrentCallsAggregateError, ConcurrentCallsWithMetadataAggregateError, concurrentCalls, concurrentCallsWithMetadata, concurrentResultCalls, concurrentResultsWithMetadata };

package/dist/concurrentCalls.mjs

@@ -0,0 +1,295 @@
+import { i as isObject, o as isPromise } from "./typeGuards-B1mzA-Rz.mjs";
+import { i as invariant } from "./assertions-qMxfVhSu.mjs";
+import { truncateArray } from "./arrayUtils.mjs";
+import { safeJsonStringify } from "./safeJson.mjs";
+import { sleep } from "./sleep.mjs";
+import { C as truncateString } from "./stringUtils-DjhWOiYn.mjs";
+import { Result, resultify, unknownToError } from "t-result";
+
+//#region src/concurrentCalls.ts
+function formatErrorMessagesWithCounts(messages, failed, total) {
+	const errorMessageCounts = /* @__PURE__ */ new Map();
+	for (const message of messages) errorMessageCounts.set(message, (errorMessageCounts.get(message) || 0) + 1);
+	return `${failed}/${total} calls failed:\n${truncateArray(Array.from(errorMessageCounts.entries()).map(([message, count]) => count > 1 ? `${message} (${count}x)` : message), 5, "...").join("\n")}`;
+}
+var ConcurrentCallsAggregateError = class extends AggregateError {
+	errors = [];
+	total = 0;
+	failed = 0;
+	constructor(errors, total, failed) {
+		const message = formatErrorMessagesWithCounts(errors.map((error) => `- ${truncateString(error instanceof Error ? error.message : safeJsonStringify(error) ?? "???", 100)}`), failed, total);
+		super(errors, message);
+		this.errors = errors;
+		this.total = total;
+		this.failed = failed;
+	}
+};
+var ConcurrentCallsWithMetadataAggregateError = class extends AggregateError {
+	errors = [];
+	errorsWithMetadata = [];
+	total = 0;
+	failed = 0;
+	constructor(errors, total, failed) {
+		const message = formatErrorMessagesWithCounts(errors.map(({ error, metadata }) => {
+			let metadataPrefix = typeof metadata === "string" || typeof metadata === "number" || typeof metadata === "boolean" ? `${metadata}: ` : "";
+			try {
+				const isArray = Array.isArray(metadata);
+				if (isObject(metadata) || isArray) {
+					const stringifiedMetadata = JSON.stringify(metadata);
+					if (stringifiedMetadata.length < 30) metadataPrefix = `${stringifiedMetadata}: `;
+					else metadataPrefix = `[${isArray ? "Array" : "Object"} metadata]: `;
+				}
+			} catch (_) {}
+			return `- ${metadataPrefix}${truncateString(error instanceof Error ? error.message : safeJsonStringify(error) ?? "???", 100)}`;
+		}), failed, total);
+		const errorInstances = errors.map((e) => e.error);
+		super(errorInstances, message);
+		this.errors = errorInstances;
+		this.errorsWithMetadata = errors;
+		this.total = total;
+		this.failed = failed;
+	}
+};
+var ConcurrentCalls = class {
+	#pendingCalls = [];
+	#alreadyRun = false;
+	allowResultify = true;
+	constructor(allowResultify) {
+		this.allowResultify = allowResultify;
+	}
+	add(...calls) {
+		this.#pendingCalls.push(...calls);
+		return this;
+	}
+	resultifyAdd(...calls) {
+		if (!this.allowResultify) throw new Error("resultifyAdd is not allowed when using concurrentResults");
+		const processedCalls = calls.map((call) => {
+			return async () => {
+				try {
+					const valueOrPromise = call();
+					const value = isPromise(valueOrPromise) ? await valueOrPromise : valueOrPromise;
+					return Result.ok(value);
+				} catch (err$1) {
+					return Result.err(unknownToError(err$1));
+				}
+			};
+		});
+		return this.add(...processedCalls);
+	}
+	async runAll({ delayStart } = {}) {
+		invariant(!this.#alreadyRun, "Already run");
+		this.#alreadyRun = true;
+		try {
+			const asyncResults = await Promise.all(this.#pendingCalls.map(async (fn, i) => {
+				try {
+					if (delayStart) await sleep(delayStart(i));
+					const result = await fn();
+					if (!result.ok) throw result.error;
+					return result.value;
+				} catch (exception) {
+					throw unknownToError(exception);
+				}
+			}));
+			return Result.ok(asyncResults);
+		} catch (exception) {
+			return Result.err(unknownToError(exception));
+		} finally {
+			this.#pendingCalls = [];
+		}
+	}
+	async runAllSettled({ delayStart } = {}) {
+		invariant(!this.#alreadyRun, "Already run");
+		this.#alreadyRun = true;
+		const total = this.#pendingCalls.length;
+		const settledResults = await Promise.allSettled(this.#pendingCalls.map(async (callOrPromise, i) => {
+			try {
+				if (delayStart) await sleep(delayStart(i));
+				const result = await callOrPromise();
+				if (!result.ok) throw result.error;
+				return result.value;
+			} catch (exception) {
+				throw unknownToError(exception);
+			}
+		}));
+		const succeeded = [];
+		const failed = [];
+		for (const settledResult of settledResults) if (settledResult.status === "fulfilled") succeeded.push(settledResult.value);
+		else failed.push(settledResult.reason);
+		const allFailed = failed.length === total;
+		const aggregatedError = failed.length > 0 ? new ConcurrentCallsAggregateError(failed, total, failed.length) : null;
+		this.#pendingCalls = [];
+		return {
+			succeeded,
+			failures: failed,
+			allFailed,
+			total,
+			aggregatedError
+		};
+	}
+};
+/**
+* Executes multiple asynchronous calls concurrently and collects the results in
+* a easier to use format.
+*
+* @template R - The type of the result value.
+*/
+function concurrentCalls() {
+	return new ConcurrentCalls(true);
+}
+var ConcurrentCallsWithMetadata = class {
+	#pendingCalls = [];
+	#alreadyRun = false;
+	allowResultify = true;
+	constructor(allowResultify) {
+		this.allowResultify = allowResultify;
+	}
+	add(...calls) {
+		invariant(!this.#alreadyRun, "Cannot add calls after execution has started.");
+		this.#pendingCalls.push(...calls);
+		return this;
+	}
+	resultifyAdd(...items) {
+		if (!this.allowResultify) throw new Error("resultifyAdd is not allowed when using concurrentResultsWithMetadata");
+		const processedItems = items.map(({ fn, metadata }) => {
+			const cb = () => resultify(async () => {
+				const valueOrPromise = fn();
+				return isPromise(valueOrPromise) ? await valueOrPromise : valueOrPromise;
+			});
+			return {
+				fn: cb,
+				metadata
+			};
+		});
+		return this.add(...processedItems);
+	}
+	async runAll({ delayStart } = {}) {
+		invariant(!this.#alreadyRun, "Already run");
+		this.#alreadyRun = true;
+		const currentCalls = [...this.#pendingCalls];
+		this.#pendingCalls = [];
+		try {
+			const successfulResults = [];
+			for (let i = 0; i < currentCalls.length; i++) {
+				const call = currentCalls[i];
+				try {
+					if (delayStart) await sleep(delayStart(i));
+					const result = await call.fn();
+					if (!result.ok) throw {
+						metadata: call.metadata,
+						error: result.error
+					};
+					successfulResults.push({
+						value: result.value,
+						metadata: call.metadata
+					});
+				} catch (exception) {
+					if (typeof exception === "object" && exception !== null && "metadata" in exception && "error" in exception && exception.metadata === call.metadata) throw exception;
+					else throw {
+						metadata: call.metadata,
+						error: unknownToError(exception)
+					};
+				}
+			}
+			return Result.ok(successfulResults);
+		} catch (errorPayload) {
+			return Result.err(errorPayload);
+		}
+	}
+	async runAllSettled({ delayStart } = {}) {
+		invariant(!this.#alreadyRun, "Already run");
+		this.#alreadyRun = true;
+		const currentCalls = [...this.#pendingCalls];
+		this.#pendingCalls = [];
+		const total = currentCalls.length;
+		if (total === 0) return {
+			succeeded: [],
+			failed: [],
+			failures: [],
+			results: [],
+			allFailed: false,
+			total: 0,
+			aggregatedError: null
+		};
+		const settledOutcomes = await Promise.allSettled(currentCalls.map(async (call, i) => {
+			try {
+				if (delayStart) await sleep(delayStart(i));
+				const result = await call.fn();
+				if (!result.ok) throw result.error;
+				return result.value;
+			} catch (innerException) {
+				throw unknownToError(innerException);
+			}
+		}));
+		const succeededProcessing = [];
+		const failedProcessing = [];
+		const resultsProcessing = [];
+		for (let i = 0; i < settledOutcomes.length; i++) {
+			const outcome = settledOutcomes[i];
+			const { metadata } = currentCalls[i];
+			if (outcome.status === "fulfilled") {
+				const value = outcome.value;
+				succeededProcessing.push({
+					value,
+					metadata
+				});
+				resultsProcessing.push({
+					ok: true,
+					value,
+					metadata,
+					error: false
+				});
+			} else {
+				const error = outcome.reason;
+				failedProcessing.push({
+					error,
+					metadata
+				});
+				resultsProcessing.push({
+					ok: false,
+					error,
+					metadata
+				});
+			}
+		}
+		return {
+			succeeded: succeededProcessing,
+			failed: failedProcessing,
+			failures: failedProcessing,
+			results: resultsProcessing,
+			allFailed: failedProcessing.length === total,
+			total,
+			aggregatedError: failedProcessing.length > 0 ? new ConcurrentCallsWithMetadataAggregateError(failedProcessing, total, failedProcessing.length) : null
+		};
+	}
+};
+/**
+* Executes multiple asynchronous calls concurrently with metadata for each call
+* and collects the results in a easier to use format.
+*
+* @template M - The type of the call metadata.
+* @template R - The type of the result value.
+*/
+function concurrentCallsWithMetadata() {
+	return new ConcurrentCallsWithMetadata(true);
+}
+/**
+* Executes multiple asynchronous result calls concurrently and collects the
+* results in a easier to use format.
+*
+* @template R - The type of the result function that will be called.
+*/
+function concurrentResultCalls() {
+	return new ConcurrentCalls(false);
+}
+/**
+* Executes multiple asynchronous result calls concurrently with metadata for
+* each call and collects the results in a easier to use format.
+*
+* @template ResultFn - The type of the result function that will be called.
+*/
+function concurrentResultsWithMetadata() {
+	return new ConcurrentCallsWithMetadata(false);
+}
+
+//#endregion
+export { ConcurrentCallsAggregateError, ConcurrentCallsWithMetadataAggregateError, concurrentCalls, concurrentCallsWithMetadata, concurrentResultCalls, concurrentResultsWithMetadata };

package/dist/consoleFmt.d.mts

@@ -0,0 +1,55 @@
+//#region src/consoleFmt.d.ts
+declare const colorToCodeASCII: {
+  red: string;
+  green: string;
+  yellow: string;
+  blue: string;
+  magenta: string;
+  cyan: string;
+  white: string;
+  black: string;
+  gray: string;
+  brightRed: string;
+  brightGreen: string;
+  brightYellow: string;
+  brightBlue: string;
+  brightMagenta: string;
+  brightCyan: string;
+  brightWhite: string;
+};
+/** @deprecated Use `styleText` from `node:util` instead. */
+declare function consoleColors(color: keyof typeof colorToCodeASCII, text: string): string;
+/** @deprecated Use `styleText` from `node:util` instead. */
+declare function bold(text: string): string;
+/** @deprecated Use `styleText` from `node:util` instead. */
+declare function underline(text: string): string;
+declare const bgColorToCodeASCII: {
+  red: string;
+  green: string;
+  yellow: string;
+  blue: string;
+  magenta: string;
+  cyan: string;
+  white: string;
+  black: string;
+  gray: string;
+  brightRed: string;
+  brightGreen: string;
+  brightYellow: string;
+  brightBlue: string;
+  brightMagenta: string;
+  brightCyan: string;
+  brightWhite: string;
+};
+/** @deprecated Use `styleText` from `node:util` instead. */
+declare function bgColor(color: keyof typeof bgColorToCodeASCII, text: string): string;
+/** @deprecated Use `styleText` from `node:util` instead. */
+declare const consoleFmt: {
+  /** @deprecated Use `styleText` from `node:util` instead. */
+  color: typeof consoleColors;
+  bold: typeof bold;
+  underline: typeof underline;
+  bgColor: typeof bgColor;
+};
+//#endregion
+export { consoleFmt };

package/dist/consoleFmt.mjs

@@ -0,0 +1,63 @@
+//#region src/consoleFmt.ts
+const colorToCodeASCII = {
+	red: "\x1B[31m",
+	green: "\x1B[32m",
+	yellow: "\x1B[33m",
+	blue: "\x1B[34m",
+	magenta: "\x1B[35m",
+	cyan: "\x1B[36m",
+	white: "\x1B[37m",
+	black: "\x1B[30m",
+	gray: "\x1B[90m",
+	brightRed: "\x1B[91m",
+	brightGreen: "\x1B[92m",
+	brightYellow: "\x1B[93m",
+	brightBlue: "\x1B[94m",
+	brightMagenta: "\x1B[95m",
+	brightCyan: "\x1B[96m",
+	brightWhite: "\x1B[97m"
+};
+/** @deprecated Use `styleText` from `node:util` instead. */
+function consoleColors(color, text) {
+	return `${colorToCodeASCII[color]}${text}\x1b[0m`;
+}
+/** @deprecated Use `styleText` from `node:util` instead. */
+function bold(text) {
+	return `\x1b[1m${text}\x1b[0m`;
+}
+/** @deprecated Use `styleText` from `node:util` instead. */
+function underline(text) {
+	return `\x1b[4m${text}\x1b[0m`;
+}
+const bgColorToCodeASCII = {
+	red: "\x1B[41m",
+	green: "\x1B[42m",
+	yellow: "\x1B[43m",
+	blue: "\x1B[44m",
+	magenta: "\x1B[45m",
+	cyan: "\x1B[46m",
+	white: "\x1B[47m",
+	black: "\x1B[40m",
+	gray: "\x1B[100m",
+	brightRed: "\x1B[101m",
+	brightGreen: "\x1B[102m",
+	brightYellow: "\x1B[103m",
+	brightBlue: "\x1B[104m",
+	brightMagenta: "\x1B[105m",
+	brightCyan: "\x1B[106m",
+	brightWhite: "\x1B[107m"
+};
+/** @deprecated Use `styleText` from `node:util` instead. */
+function bgColor(color, text) {
+	return `${bgColorToCodeASCII[color]}${text}\x1b[0m`;
+}
+/** @deprecated Use `styleText` from `node:util` instead. */
+const consoleFmt = {
+	color: consoleColors,
+	bold,
+	underline,
+	bgColor
+};
+
+//#endregion
+export { consoleFmt };

package/dist/conversions-DTmwEMIu.mjs

@@ -0,0 +1,12 @@
+//#region src/conversions.ts
+function bytesToHumanReadable(bytes) {
+	if (bytes < 1024) return `${bytes} B`;
+	const kb = bytes / 1024;
+	if (kb < 1024) return `${kb.toFixed(2)} KB`;
+	const mb = kb / 1024;
+	if (mb < 1024) return `${mb.toFixed(2)} MB`;
+	return `${(mb / 1024).toFixed(2)} GB`;
+}
+
+//#endregion
+export { bytesToHumanReadable as t };

package/dist/conversions.d.mts

@@ -0,0 +1,4 @@
+//#region src/conversions.d.ts
+declare function bytesToHumanReadable(bytes: number): string;
+//#endregion
+export { bytesToHumanReadable };

package/dist/conversions.mjs

@@ -0,0 +1,3 @@
+import { t as bytesToHumanReadable } from "./conversions-DTmwEMIu.mjs";
+
+export { bytesToHumanReadable };

package/dist/createThrottleController.d.mts

@@ -0,0 +1,18 @@
+import { DurationObj } from "./time.mjs";
+
+//#region src/createThrottleController.d.ts
+type Options = {
+  maxCalls: number;
+  per: DurationObj;
+  cleanupCheckSecsInterval?: number;
+};
+type ThrottleController = {
+  shouldSkip: (callId?: string | number | (string | number)[]) => boolean;
+};
+declare function createThrottleController({
+  maxCalls,
+  per,
+  cleanupCheckSecsInterval
+}: Options): ThrottleController;
+//#endregion
+export { createThrottleController };

package/dist/createThrottleController.mjs

@@ -0,0 +1,40 @@
+import { p as durationObjToMs } from "./time-sr2lhQRw.mjs";
+import { EnhancedMap } from "./enhancedMap.mjs";
+
+//#region src/createThrottleController.ts
+function createThrottleController({ maxCalls, per, cleanupCheckSecsInterval = 1800 }) {
+	const msInterval = durationObjToMs(per);
+	if (msInterval === 0) throw new Error("Invalid interval");
+	let lastCleanupCheck = Date.now();
+	const windows = new EnhancedMap();
+	function cleanup(checkTime) {
+		if (!(checkTime - lastCleanupCheck > cleanupCheckSecsInterval * 1e3)) return;
+		setTimeout(() => {
+			const now = Date.now();
+			lastCleanupCheck = now;
+			for (const [key, value] of windows) if (now - value.windowStartTime > msInterval) windows.delete(key);
+		}, 2);
+	}
+	return {
+		shouldSkip(callId = "") {
+			const now = Date.now();
+			const serializedCallId = String(callId);
+			const window = windows.getOrInsert(serializedCallId, () => ({
+				windowStartTime: now,
+				calls: 0
+			}));
+			if (now - window.windowStartTime > msInterval) {
+				window.windowStartTime = now;
+				window.calls = 0;
+			}
+			window.calls++;
+			cleanup(now);
+			if (window.calls > maxCalls) return true;
+			return false;
+		},
+		_currentWindows: windows
+	};
+}
+
+//#endregion
+export { createThrottleController };