@ls-stack/utils 3.63.0 → 3.66.0

package/dist/promiseUtils.d.mts

@@ -0,0 +1,9 @@
+//#region src/promiseUtils.d.ts
+type Deferred<T> = {
+  resolve: (value: T | PromiseLike<T>) => void;
+  reject: (reason: unknown) => void;
+  promise: Promise<T>;
+};
+declare function defer<T = void>(): Deferred<T>;
+//#endregion
+export { defer };

package/dist/promiseUtils.mjs

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

package/dist/regexUtils.d.mts

@@ -0,0 +1,18 @@
+//#region src/regexUtils.d.ts
+declare function getRegexMatches(string: string, regex: RegExp): {
+  groups: (string | undefined)[];
+  fullMatch: string | undefined;
+};
+declare function getRegexMatchAll(str: string, regexp: RegExp): Generator<{
+  groups: (string | undefined)[];
+  fullMatch: string;
+  namedGroups: {
+    [key: string]: string;
+  } | undefined;
+  start: number;
+  end: number;
+  prevEnd: number;
+}, void, unknown>;
+declare function escapeRegExp(value: string): string;
+//#endregion
+export { escapeRegExp, getRegexMatchAll, getRegexMatches };

package/dist/regexUtils.mjs

@@ -0,0 +1,34 @@
+//#region src/regexUtils.ts
+function getRegexMatches(string, regex) {
+	const [fullMatch, ...groups] = regex.exec(string) || [void 0];
+	return {
+		groups,
+		fullMatch
+	};
+}
+function* getRegexMatchAll(str, regexp) {
+	const flags = regexp.global ? regexp.flags : `${regexp.flags}g`;
+	const re = new RegExp(regexp, flags);
+	let match;
+	let lastIndex = 0;
+	while (match = re.exec(str)) {
+		const [fullMatch, ...groups] = match;
+		const prevLastIndex = lastIndex;
+		lastIndex = re.lastIndex;
+		yield {
+			groups,
+			fullMatch,
+			namedGroups: match.groups,
+			start: match.index,
+			end: lastIndex,
+			prevEnd: prevLastIndex
+		};
+	}
+}
+const SPECIAL_REGEX_CHARS = /[.*+?^${}()|[\]\\]/g;
+function escapeRegExp(value) {
+	return value.replace(SPECIAL_REGEX_CHARS, "\\$&");
+}
+
+//#endregion
+export { escapeRegExp, getRegexMatchAll, getRegexMatches };

package/dist/{retryOnError.d.cts → retryOnError.d.mts}

@@ -1,26 +1,27 @@
-import { ResultValidErrors, Result } from 't-result';
+import { Result, ResultValidErrors } from "t-result";
 
+//#region src/retryOnError.d.ts
 /** Configuration options for retryOnError function. */
 type RetryOptions = {
-    /** Delay between retries in milliseconds or function returning delay */
-    delayBetweenRetriesMs?: number | ((retry: number) => number);
-    /**
-     * Function to determine if retry should happen, receives error and duration
-     * of last attempt
-     */
-    retryCondition?: (error: Error, lastAttempt: {
-        duration: number;
-        retry: number;
-    }) => boolean;
-    /** Optional ID for debug logging */
-    debugId?: string;
-    /** Disable retries */
-    disableRetries?: boolean;
-    /** Function to call when retry happens */
-    onRetry?: (error: Error, lastAttempt: {
-        duration: number;
-        retry: number;
-    }) => void;
+  /** Delay between retries in milliseconds or function returning delay */
+  delayBetweenRetriesMs?: number | ((retry: number) => number);
+  /**
+   * Function to determine if retry should happen, receives error and duration
+   * of last attempt
+   */
+  retryCondition?: (error: Error, lastAttempt: {
+    duration: number;
+    retry: number;
+  }) => boolean;
+  /** Optional ID for debug logging */
+  debugId?: string;
+  /** Disable retries */
+  disableRetries?: boolean;
+  /** Function to call when retry happens */
+  onRetry?: (error: Error, lastAttempt: {
+    duration: number;
+    retry: number;
+  }) => void;
 };
 /**
  * Retries a function on error with configurable retry logic.
@@ -44,8 +45,8 @@ type RetryOptions = {
  *   error
  */
 declare function retryOnError<T>(fn: (ctx: {
-    /** Current retry count, (0 for first attempt) */
-    retry: number;
+  /** Current retry count, (0 for first attempt) */
+  retry: number;
 }) => Promise<T>, maxRetries: number, options?: RetryOptions, retry?: number, originalMaxRetries?: number): Promise<T>;
 /**
  * Retries a result function on error with configurable retry logic.
@@ -64,20 +65,20 @@ declare function retryOnError<T>(fn: (ctx: {
  *   error
  */
 declare function retryResultOnError<T, E extends ResultValidErrors>(fn: (ctx: {
-    /** Current retry count, (0 for first attempt) */
-    retry: number;
+  /** Current retry count, (0 for first attempt) */
+  retry: number;
 }) => Promise<Result<T, E>>, maxRetries: number, options?: {
-    delayBetweenRetriesMs?: number | ((retry: number) => number);
-    retryCondition?: (error: E, lastAttempt: {
-        duration: number;
-        retry: number;
-    }) => boolean;
-    debugId?: string;
-    disableRetries?: boolean;
-    onRetry?: (error: E, lastAttempt: {
-        duration: number;
-        retry: number;
-    }) => void;
+  delayBetweenRetriesMs?: number | ((retry: number) => number);
+  retryCondition?: (error: E, lastAttempt: {
+    duration: number;
+    retry: number;
+  }) => boolean;
+  debugId?: string;
+  disableRetries?: boolean;
+  onRetry?: (error: E, lastAttempt: {
+    duration: number;
+    retry: number;
+  }) => void;
 }, __retry?: number, __originalMaxRetries?: number): Promise<Result<T, E>>;
-
-export { retryOnError, retryResultOnError };
+//#endregion
+export { retryOnError, retryResultOnError };

package/dist/retryOnError.mjs

@@ -0,0 +1,91 @@
+import { sleep } from "./sleep.mjs";
+import { unknownToError } from "t-result";
+
+//#region src/retryOnError.ts
+/**
+* Retries a function on error with configurable retry logic.
+*
+* @example
+*   await retryOnError(
+*     async (ctx) => {
+*       console.log(`Attempt ${ctx.retry + 1}`);
+*       return await fetchData();
+*     },
+*     3,
+*     { delayBetweenRetriesMs: 1000 },
+*   );
+*
+* @param fn - Function to retry that receives context with retry count
+* @param maxRetries - Maximum number of retries
+* @param options - Configuration options
+* @param retry - Internal use only
+* @param originalMaxRetries - Internal use only
+* @returns Promise resolving to the function result or rejecting with the final
+*   error
+*/
+async function retryOnError(fn, maxRetries, options = {}, retry = 0, originalMaxRetries = maxRetries) {
+	const { delayBetweenRetriesMs, retryCondition, disableRetries, onRetry } = options;
+	if (options.debugId) {
+		if (retry > 0) console.info(`Retrying ${options.debugId} (retry ${retry}/${originalMaxRetries}) after error`);
+	}
+	const startTime = Date.now();
+	try {
+		return await fn({ retry });
+	} catch (error) {
+		if (maxRetries > 0 && !disableRetries) {
+			const errorDuration = Date.now() - startTime;
+			const normalizedError = unknownToError(error);
+			if (!(retryCondition ? retryCondition(normalizedError, {
+				duration: errorDuration,
+				retry
+			}) : true)) throw normalizedError;
+			if (onRetry) onRetry(normalizedError, {
+				duration: errorDuration,
+				retry
+			});
+			if (delayBetweenRetriesMs) await sleep(typeof delayBetweenRetriesMs === "function" ? delayBetweenRetriesMs(retry) : delayBetweenRetriesMs);
+			return retryOnError(fn, maxRetries - 1, options, retry + 1, originalMaxRetries);
+		} else throw error;
+	}
+}
+/**
+* Retries a result function on error with configurable retry logic.
+*
+* @param fn - Function to retry that receives context with retry count
+* @param maxRetries - Maximum number of retries
+* @param options - Configuration options
+* @param options.delayBetweenRetriesMs
+* @param options.retryCondition
+* @param options.debugId
+* @param options.disableRetries
+* @param options.onRetry
+* @param __retry - Internal use only
+* @param __originalMaxRetries - Internal use only
+* @returns Promise resolving to the function result or rejecting with the final
+*   error
+*/
+async function retryResultOnError(fn, maxRetries, options = {}, __retry = 0, __originalMaxRetries = maxRetries) {
+	const { delayBetweenRetriesMs, retryCondition, onRetry } = options;
+	if (options.debugId) {
+		if (__retry > 0) console.info(`Retrying ${options.debugId} (retry ${__retry}/${__originalMaxRetries}) after error`);
+	}
+	const startTime = Date.now();
+	const result = await fn({ retry: __retry });
+	if (result.ok) return result;
+	if (maxRetries > 0 && !options.disableRetries) {
+		const errorDuration = Date.now() - startTime;
+		if (!(retryCondition ? retryCondition(result.error, {
+			duration: errorDuration,
+			retry: __retry
+		}) : true)) return result;
+		if (onRetry) onRetry(result.error, {
+			duration: errorDuration,
+			retry: __retry
+		});
+		if (delayBetweenRetriesMs) await sleep(typeof delayBetweenRetriesMs === "function" ? delayBetweenRetriesMs(__retry) : delayBetweenRetriesMs);
+		return retryResultOnError(fn, maxRetries - 1, options, __retry + 1, __originalMaxRetries);
+	} else return result;
+}
+
+//#endregion
+export { retryOnError, retryResultOnError };

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

@@ -1,16 +1,17 @@
+//#region src/runShellCmd.d.ts
 type CmdResult = {
-    label: string | null;
-    out: string;
-    error: boolean;
-    stdout: string;
-    stderr: string;
+  label: string | null;
+  out: string;
+  error: boolean;
+  stdout: string;
+  stderr: string;
 };
 type RunCmdOptions = {
-    mock?: CmdResult;
-    silent?: boolean | 'timeOnly';
-    cwd?: string;
-    throwOnError?: boolean;
-    noCiColorForce?: boolean;
+  mock?: CmdResult;
+  silent?: boolean | 'timeOnly';
+  cwd?: string;
+  throwOnError?: boolean;
+  noCiColorForce?: boolean;
 };
 /**
  * @deprecated This utility has been moved to @ls-stack/node-utils. Please
@@ -30,7 +31,13 @@ type RunCmdOptions = {
  * @param root0.cwd
  * @param root0.noCiColorForce
  */
-declare function runCmd(label: string | null, command: string | string[], { mock, silent, throwOnError, cwd, noCiColorForce, }?: RunCmdOptions): Promise<CmdResult>;
+declare function runCmd(label: string | null, command: string | string[], {
+  mock,
+  silent,
+  throwOnError,
+  cwd,
+  noCiColorForce
+}?: RunCmdOptions): Promise<CmdResult>;
 /**
  * @deprecated This utility has been moved to @ls-stack/node-utils. Please
  *   update your imports:
@@ -59,8 +66,10 @@ declare function concurrentCmd(label: string, cmd: string | string[], onResult:
  * @param root0
  * @param root0.silent
  */
-declare function runCmdUnwrap(label: string | null, command: string | string[], { silent, }?: {
-    silent?: boolean | 'timeOnly';
+declare function runCmdUnwrap(label: string | null, command: string | string[], {
+  silent
+}?: {
+  silent?: boolean | 'timeOnly';
 }): Promise<string>;
 /**
  * @deprecated This utility has been moved to @ls-stack/node-utils. Please
@@ -86,5 +95,5 @@ declare function runCmdSilent(command: string | string[]): Promise<CmdResult>;
  * @param command
  */
 declare function runCmdSilentUnwrap(command: string | string[]): Promise<string>;
-
-export { concurrentCmd, runCmd, runCmdSilent, runCmdSilentUnwrap, runCmdUnwrap };
+//#endregion
+export { concurrentCmd, runCmd, runCmdSilent, runCmdSilentUnwrap, runCmdUnwrap };

package/dist/runShellCmd.mjs

@@ -0,0 +1,151 @@
+import { spawn } from "child_process";
+
+//#region src/runShellCmd.ts
+/**
+* @deprecated This utility has been moved to @ls-stack/node-utils. Please
+*   update your imports:
+*
+*       // Old (deprecated)
+*       import { runCmd } from '@ls-stack/utils/runShellCmd';
+*
+*       // New (preferred)
+*       import { runCmd } from '@ls-stack/node-utils/runShellCmd';
+* @param label
+* @param command
+* @param root0
+* @param root0.mock
+* @param root0.silent
+* @param root0.throwOnError
+* @param root0.cwd
+* @param root0.noCiColorForce
+*/
+function runCmd(label, command, { mock, silent, throwOnError, cwd = process.cwd(), noCiColorForce } = {}) {
+	if (mock) return Promise.resolve(mock);
+	if (label && (!silent || silent === "timeOnly")) {
+		console.log(`----${label}----`);
+		console.time("✅");
+	}
+	return new Promise((resolve) => {
+		const [cmd = "", ...args] = Array.isArray(command) ? command.flatMap((item) => item.startsWith("$") ? item.replace("$", "").split(" ") : item) : command.split(" ");
+		const child = spawn(cmd, args, {
+			cwd,
+			env: noCiColorForce ? void 0 : {
+				...process.env,
+				CLICOLOR_FORCE: "1"
+			}
+		});
+		let stdout = "";
+		let stderr = "";
+		let out = "";
+		child.stdout.on("data", (data) => {
+			stdout += String(data);
+			out += String(data);
+			if (!silent) console.log(String(data));
+		});
+		child.stderr.on("data", (data) => {
+			stderr += String(data);
+			out += String(data);
+			if (!silent) console.log(String(data));
+		});
+		child.on("close", (code) => {
+			const hasError = code !== 0;
+			if (!silent || silent === "timeOnly") {
+				if (!hasError) console.timeEnd("✅");
+				console.log("\n");
+			}
+			if (throwOnError && hasError) {
+				if (silent) {
+					if (label) console.log(`----${label}----`);
+					else console.trace();
+					console.error(stderr);
+				}
+				process.exit(1);
+			}
+			resolve({
+				label,
+				out,
+				stderr,
+				stdout,
+				error: hasError
+			});
+		});
+	});
+}
+/**
+* @deprecated This utility has been moved to @ls-stack/node-utils. Please
+*   update your imports:
+*
+*       // Old (deprecated)
+*       import { concurrentCmd } from '@ls-stack/utils/runShellCmd';
+*
+*       // New (preferred)
+*       import { concurrentCmd } from '@ls-stack/node-utils/runShellCmd';
+* @param label
+* @param cmd
+* @param onResult
+*/
+async function concurrentCmd(label, cmd, onResult) {
+	const start = Date.now();
+	const result = await runCmd(label, cmd, { silent: true });
+	onResult(result);
+	const elapsedSeconds = (Date.now() - start) / 1e3;
+	console.log(`${result.error ? "🔴" : "✅"} ${result.label} (${elapsedSeconds.toFixed(1)}s)`);
+	return () => {
+		if (result.error) {
+			console.log(`❌ ${result.label} errors:`);
+			console.log(result.out);
+			console.log("\n");
+		}
+	};
+}
+/**
+* @deprecated This utility has been moved to @ls-stack/node-utils. Please
+*   update your imports:
+*
+*       // Old (deprecated)
+*       import { runCmdUnwrap } from '@ls-stack/utils/runShellCmd';
+*
+*       // New (preferred)
+*       import { runCmdUnwrap } from '@ls-stack/node-utils/runShellCmd';
+* @param label
+* @param command
+* @param root0
+* @param root0.silent
+*/
+async function runCmdUnwrap(label, command, { silent } = {}) {
+	return (await runCmd(label, command, {
+		silent,
+		throwOnError: true
+	})).stdout;
+}
+/**
+* @deprecated This utility has been moved to @ls-stack/node-utils. Please
+*   update your imports:
+*
+*       // Old (deprecated)
+*       import { runCmdSilent } from '@ls-stack/utils/runShellCmd';
+*
+*       // New (preferred)
+*       import { runCmdSilent } from '@ls-stack/node-utils/runShellCmd';
+* @param command
+*/
+function runCmdSilent(command) {
+	return runCmd(null, command, { silent: true });
+}
+/**
+* @deprecated This utility has been moved to @ls-stack/node-utils. Please
+*   update your imports:
+*
+*       // Old (deprecated)
+*       import { runCmdSilentUnwrap } from '@ls-stack/utils/runShellCmd';
+*
+*       // New (preferred)
+*       import { runCmdSilentUnwrap } from '@ls-stack/node-utils/runShellCmd';
+* @param command
+*/
+function runCmdSilentUnwrap(command) {
+	return runCmdUnwrap(null, command, { silent: true });
+}
+
+//#endregion
+export { concurrentCmd, runCmd, runCmdSilent, runCmdSilentUnwrap, runCmdUnwrap };

package/dist/{safeJson.d.cts → safeJson.d.mts}

@@ -1,3 +1,4 @@
+//#region src/safeJson.d.ts
 /**
  * JSON.stringify can throw if the value is circular or contains functions, this
  * function catches those errors and returns undefined
@@ -12,5 +13,5 @@ declare function safeJsonStringify(value: unknown): string | undefined;
  * @param value
  */
 declare function safeJsonParse(value: string): unknown;
-
-export { safeJsonParse, safeJsonStringify };
+//#endregion
+export { safeJsonParse, safeJsonStringify };

package/dist/safeJson.mjs

@@ -0,0 +1,30 @@
+//#region src/safeJson.ts
+/**
+* JSON.stringify can throw if the value is circular or contains functions, this
+* function catches those errors and returns undefined
+*
+* @param value
+*/
+function safeJsonStringify(value) {
+	try {
+		return JSON.stringify(value);
+	} catch (_) {
+		return;
+	}
+}
+/**
+* JSON.parse can throw if the value is not valid JSON, this function catches
+* those errors and returns undefined
+*
+* @param value
+*/
+function safeJsonParse(value) {
+	try {
+		return JSON.parse(value);
+	} catch (_) {
+		return;
+	}
+}
+
+//#endregion
+export { safeJsonParse, safeJsonStringify };

package/dist/{saferTyping.d.cts → saferTyping.d.mts}

@@ -1,8 +1,10 @@
+//#region src/saferTyping.d.ts
 /**
  * Use this only when you have 100% of certainty that this will not break the
  * types
  */
 type __LEGIT_ANY__ = any;
+type __FIX_THIS_TYPING__ = any;
 type __LEGIT_ANY_FUNCTION__ = (...params: any) => __LEGIT_ANY__;
 /** An empty object type, equivalent to `{}` but with safer typing */
 type EmptyObject = Record<string, never>;
@@ -36,12 +38,11 @@ declare function __LEGIT_CAST__<T, V = unknown>(value: V): T;
  */
 declare function __REFINE_CAST__<T>(value: T): <R extends T>() => R;
 declare function __FIX_THIS_CASTING__<T>(value: unknown): T;
-type __FIX_THIS_TYPING__ = any;
 declare function __FIX_THIS_TYPING__(value: unknown): __LEGIT_ANY__;
 /**
  * Any type that is not a primitive (number, string, boolean, null, undefined,
  * symbol, bigint, ...) Equivalent to `object` type
  */
 type AnyNonPrimitiveValue = object;
-
-export { type AnyNonPrimitiveValue, type EmptyObject, __FIX_THIS_CASTING__, __FIX_THIS_TYPING__, __LEGIT_ANY_CAST__, type __LEGIT_ANY_FUNCTION__, type __LEGIT_ANY__, __LEGIT_CAST__, __REFINE_CAST__ };
+//#endregion
+export { AnyNonPrimitiveValue, EmptyObject, __FIX_THIS_CASTING__, __FIX_THIS_TYPING__, __LEGIT_ANY_CAST__, __LEGIT_ANY_FUNCTION__, __LEGIT_ANY__, __LEGIT_CAST__, __REFINE_CAST__ };

package/dist/saferTyping.mjs

@@ -0,0 +1,45 @@
+//#region src/saferTyping.ts
+/**
+* Cast a value to `any` type. Use this when you have legit usage of `any`
+* casting.
+*
+* @template V (optional) - When used enforces that the casted value is
+*   assignable to the type V, use it for safer casts
+* @param value
+*/
+function __LEGIT_ANY_CAST__(value) {
+	return value;
+}
+/**
+* Cast a value to a specific type T. Use this when you have legit usage of type
+* assertion.
+*
+* @template T - The type to cast to
+* @template V (optional) - When used enforces that the casted value is
+*   assignable to the type V, use it for safer casts
+* @param value
+*/
+function __LEGIT_CAST__(value) {
+	return value;
+}
+/**
+* Refine a value to a specific type T. Use this when you have legit usage of
+* type assertion.
+*
+* @template T - The type to cast to
+* @template V (optional) - When used enforces that the casted value is
+*   assignable to the type V, use it for safer casts
+* @param value
+*/
+function __REFINE_CAST__(value) {
+	return () => value;
+}
+function __FIX_THIS_CASTING__(value) {
+	return value;
+}
+function __FIX_THIS_TYPING__(value) {
+	return value;
+}
+
+//#endregion
+export { __FIX_THIS_CASTING__, __FIX_THIS_TYPING__, __LEGIT_ANY_CAST__, __LEGIT_CAST__, __REFINE_CAST__ };

package/dist/serializeXML.d.mts

@@ -0,0 +1,23 @@
+//#region src/serializeXML.d.ts
+type XMLNode = {
+  type?: 'node';
+  name: string;
+  attrs?: Record<string, string | number | boolean | null | undefined>;
+  children?: (XMLNode | null | undefined | false)[] | string;
+  escapeText?: boolean;
+} | {
+  type: 'comment';
+  content: string;
+  escapeText?: boolean;
+} | {
+  type: 'emptyLine';
+};
+type SerializeOptions = {
+  indent?: number | string;
+  escapeText?: boolean;
+  validateTagName?: boolean;
+  invalidNodes?: 'throw' | 'reject';
+};
+declare function serializeXML(node: XMLNode | (XMLNode | null | undefined | false)[], options?: SerializeOptions): string;
+//#endregion
+export { SerializeOptions, XMLNode, serializeXML };