@ls-stack/utils 3.63.0 → 3.66.0

package/dist/timers.mjs

@@ -0,0 +1,220 @@
+import { defer } from "./promiseUtils.mjs";
+import { Result } from "t-result";
+
+//#region src/timers.ts
+/**
+* Creates a timeout with automatic cleanup capability.
+*
+* Returns a cleanup function that can be called to cancel the timeout. The
+* cleanup function is idempotent - calling it multiple times is safe.
+*
+* @example
+*   ```typescript
+*   const cleanup = createTimeout(1000, () => {
+*     console.log('Timeout completed');
+*   });
+*
+*   // Cancel the timeout before it completes
+*   cleanup();
+*   ```;
+*
+* @param ms - The timeout duration in milliseconds
+* @param callback - The function to execute when the timeout completes
+* @returns A cleanup function that cancels the timeout when called
+*/
+function createTimeout(ms, callback) {
+	const timeoutId = setTimeout(callback, ms);
+	let isCleaned = false;
+	return () => {
+		if (isCleaned) return;
+		clearTimeout(timeoutId);
+		isCleaned = true;
+	};
+}
+/**
+* Creates an interval with automatic cleanup capability.
+*
+* Returns a cleanup function that can be called to cancel the interval. The
+* cleanup function is idempotent - calling it multiple times is safe.
+*
+* @example
+*   ```typescript
+*   const cleanup = createInterval(1000, () => {
+*     console.log('Interval tick');
+*   });
+*
+*   // Stop the interval
+*   cleanup();
+*   ```;
+*
+* @param ms - The interval duration in milliseconds
+* @param callback - The function to execute on each interval tick
+* @returns A cleanup function that cancels the interval when called
+*/
+function createInterval(ms, callback) {
+	const intervalId = setInterval(callback, ms);
+	let isCleaned = false;
+	return () => {
+		if (isCleaned) return;
+		clearInterval(intervalId);
+		isCleaned = true;
+	};
+}
+/**
+* Creates a timeout that prevents concurrent executions.
+*
+* Each call to the `call` function will cancel any previous pending timeout and
+* start a new one. This is useful for debouncing or ensuring only the last call
+* executes after a delay.
+*
+* @example
+*   ```typescript
+*   const { call, clean } = createDebouncedTimeout(1000, () => {
+*     console.log('Only the last call executes');
+*   });
+*
+*   call(); // This will be cancelled
+*   call(); // This will be cancelled
+*   call(); // Only this one will execute after 1000ms
+*
+*   // Or cancel all pending timeouts
+*   clean();
+*   ```;
+*
+* @param ms - The timeout duration in milliseconds
+* @param callback - The function to execute when the timeout completes
+* @returns An object with `call` to trigger the timeout and `clean` to cancel
+*   it
+*/
+function createDebouncedTimeout(ms, callback) {
+	let cleanupTimer = null;
+	return {
+		clean: () => {
+			cleanupTimer?.();
+		},
+		call: () => {
+			cleanupTimer?.();
+			cleanupTimer = createTimeout(ms, () => {
+				callback();
+			});
+		}
+	};
+}
+/**
+* Creates a timeout that waits for a condition to become true.
+*
+* Polls the condition function at regular intervals until it returns a truthy
+* value, then calls the callback with that value. If the condition doesn't
+* become true within the maximum wait time, the timeout expires without calling
+* the callback.
+*
+* @example
+*   ```typescript
+*   const cleanup = createWaitUntil({
+*     condition: () => document.getElementById('myElement'),
+*     maxWaitMs: 5000,
+*     callback: (element) => {
+*       console.log('Element found:', element);
+*     },
+*     checkIntervalMs: 50
+*   });
+*
+*   // Cancel the condition check
+*   cleanup();
+*   ```;
+*
+* @template T - The type of value returned by the condition function when true
+* @param options - Configuration options
+* @param options.condition - Function that returns false or a truthy value when
+*   the condition is met
+* @param options.maxWaitMs - Maximum time to wait for the condition in
+*   milliseconds
+* @param options.callback - Function to call when the condition becomes true
+* @param options.checkIntervalMs - How often to check the condition in
+*   milliseconds (default: 20)
+* @returns A cleanup function that cancels the condition timeout
+*/
+function createWaitUntil({ condition, maxWaitMs, callback, checkIntervalMs = 20 }) {
+	let cleanCheckTimeout = null;
+	let cleanMaxWaitTimeout = null;
+	cleanMaxWaitTimeout = createTimeout(maxWaitMs, () => {
+		cleanCheckTimeout?.();
+	});
+	function check() {
+		const result = condition();
+		if (result) {
+			cleanMaxWaitTimeout?.();
+			callback(result);
+		} else cleanCheckTimeout = createTimeout(checkIntervalMs, check);
+	}
+	check();
+	return () => {
+		cleanMaxWaitTimeout();
+		cleanCheckTimeout?.();
+	};
+}
+async function waitFor(condition, { polling, timeout }) {
+	const { promise, resolve } = defer();
+	let timeoutId = null;
+	let intervalId = null;
+	let rafId = null;
+	let isResolved = false;
+	function cleanup() {
+		if (timeoutId) {
+			clearTimeout(timeoutId);
+			timeoutId = null;
+		}
+		if (intervalId) {
+			clearInterval(intervalId);
+			intervalId = null;
+		}
+		if (rafId && typeof cancelAnimationFrame !== "undefined") {
+			cancelAnimationFrame(rafId);
+			rafId = null;
+		}
+	}
+	function resolveWith(result) {
+		if (isResolved) return;
+		isResolved = true;
+		cleanup();
+		resolve(result);
+	}
+	async function checkCondition() {
+		try {
+			const result = condition();
+			if (result instanceof Promise ? await result : result) {
+				resolveWith(Result.ok(void 0));
+				return true;
+			}
+			return false;
+		} catch (error) {
+			resolveWith(Result.err(/* @__PURE__ */ new Error(`Condition check failed: ${error}`)));
+			return true;
+		}
+	}
+	checkCondition().then((resolved) => {
+		if (resolved) return;
+		timeoutId = setTimeout(() => {
+			resolveWith(Result.err(/* @__PURE__ */ new Error(`Timeout of ${timeout}ms exceeded while waiting for condition`)));
+		}, timeout);
+		if (polling === "raf") {
+			if (typeof requestAnimationFrame === "undefined") {
+				resolveWith(Result.err(/* @__PURE__ */ new Error("requestAnimationFrame is not available in this environment")));
+				return;
+			}
+			function rafCheck() {
+				if (isResolved) return;
+				checkCondition().then((conditionResolved) => {
+					if (!conditionResolved && !isResolved) rafId = requestAnimationFrame(rafCheck);
+				}).catch(() => {});
+			}
+			rafId = requestAnimationFrame(rafCheck);
+		} else intervalId = setInterval(() => {
+			checkCondition().catch(() => {});
+		}, polling);
+	}).catch(() => {});
+	return promise;
+}
+
+//#endregion
+export { createDebouncedTimeout, createInterval, createTimeout, createWaitUntil, waitFor };

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

@@ -1,38 +1,41 @@
+//#region src/tsResult.d.ts
 type Ok<T> = {
-    ok: true;
-    error: false;
-    value: T;
+  ok: true;
+  error: false;
+  value: T;
 } & AnyResultMethods;
 type AnyResultMethods = Record<ResultMethodsKeys, never>;
 /** @deprecated Use `t-result` library instead. */
 type ResultValidErrors = Error | Record<string, unknown> | unknown[] | readonly unknown[] | true;
 type Err<E extends ResultValidErrors> = {
-    ok: false;
-    error: E;
-    /** @deprecated Use `t-result` library instead. */
-    errorResult: () => Err<E>;
+  ok: false;
+  error: E;
+  /** @deprecated Use `t-result` library instead. */
+  errorResult: () => Err<E>;
 } & AnyResultMethods;
 type ResultMethods<T, E extends ResultValidErrors> = {
-    /** @deprecated Use `t-result` library instead. */
-    unwrapOrNull: () => T | null;
-    /** @deprecated Use `t-result` library instead. */
-    unwrapOr: <R extends T>(defaultValue: R) => T | R;
-    /** @deprecated Use `t-result` library instead. */
-    unwrap: () => T;
-    /** @deprecated Use `t-result` library instead. */
-    mapOk: <NewValue>(mapFn: (value: T) => NewValue) => Result<NewValue, E>;
-    /** @deprecated Use `t-result` library instead. */
-    mapErr: <NewError extends ResultValidErrors>(mapFn: (error: E) => NewError) => Result<T, NewError>;
-    /** @deprecated Use `t-result` library instead. */
-    mapOkAndErr: <NewValue, NewError extends ResultValidErrors>(mapFns: {
-        ok: (value: T) => NewValue;
-        err: (error: E) => NewError;
-    }) => Result<NewValue, NewError>;
-    /** @deprecated Use `t-result` library instead. */
-    ifOk: (fn: (value: T) => void) => Result<T, E>;
-    /** @deprecated Use `t-result` library instead. */
-    ifErr: (fn: (error: E) => void) => Result<T, E>;
+  /** @deprecated Use `t-result` library instead. */
+  unwrapOrNull: () => T | null;
+  /** @deprecated Use `t-result` library instead. */
+  unwrapOr: <R extends T>(defaultValue: R) => T | R;
+  /** @deprecated Use `t-result` library instead. */
+  unwrap: () => T;
+  /** @deprecated Use `t-result` library instead. */
+  mapOk: <NewValue>(mapFn: (value: T) => NewValue) => Result<NewValue, E>;
+  /** @deprecated Use `t-result` library instead. */
+  mapErr: <NewError extends ResultValidErrors>(mapFn: (error: E) => NewError) => Result<T, NewError>;
+  /** @deprecated Use `t-result` library instead. */
+  mapOkAndErr: <NewValue, NewError extends ResultValidErrors>(mapFns: {
+    ok: (value: T) => NewValue;
+    err: (error: E) => NewError;
+  }) => Result<NewValue, NewError>;
+  /** @deprecated Use `t-result` library instead. */
+  ifOk: (fn: (value: T) => void) => Result<T, E>;
+  /** @deprecated Use `t-result` library instead. */
+  ifErr: (fn: (error: E) => void) => Result<T, E>;
 };
+/** @deprecated Use `t-result` library instead. */
+type Result<T, E extends ResultValidErrors = Error> = (Omit<Ok<T>, ResultMethodsKeys> | Omit<Err<E>, ResultMethodsKeys>) & ResultMethods<T, E>;
 type ResultMethodsKeys = keyof ResultMethods<any, any>;
 /** @deprecated Use `t-result` library instead. */
 declare function ok(): Ok<void>;
@@ -54,23 +57,24 @@ declare function unknownToResultError(error: unknown): Err<Error>;
  */
 declare function asyncUnwrap<T>(result: Promise<Result<T, ResultValidErrors>>): Promise<T>;
 declare function asyncMap<T, E extends ResultValidErrors>(resultPromise: Promise<Result<T, E>>): {
-    err: <NewError extends ResultValidErrors>(mapFn: (error: E) => NewError) => Promise<Result<T, NewError>>;
-    ok: <NewValue>(mapFn: (value: T) => NewValue) => Promise<Result<NewValue, E>>;
-    okAndErr: <NewValue, NewError extends ResultValidErrors>({ ok: mapFn, err: mapErrFn, }: {
-        ok: (value: T) => NewValue;
-        err: (error: E) => NewError;
-    }) => Promise<Result<NewValue, NewError>>;
+  err: <NewError extends ResultValidErrors>(mapFn: (error: E) => NewError) => Promise<Result<T, NewError>>;
+  ok: <NewValue>(mapFn: (value: T) => NewValue) => Promise<Result<NewValue, E>>;
+  okAndErr: <NewValue, NewError extends ResultValidErrors>({
+    ok: mapFn,
+    err: mapErrFn
+  }: {
+    ok: (value: T) => NewValue;
+    err: (error: E) => NewError;
+  }) => Promise<Result<NewValue, NewError>>;
 };
 /** @deprecated Use `t-result` library instead. */
-type Result<T, E extends ResultValidErrors = Error> = (Omit<Ok<T>, ResultMethodsKeys> | Omit<Err<E>, ResultMethodsKeys>) & ResultMethods<T, E>;
-/** @deprecated Use `t-result` library instead. */
 declare const Result: {
-    ok: typeof ok;
-    err: typeof err;
-    unknownToError: typeof unknownToResultError;
-    asyncUnwrap: typeof asyncUnwrap;
-    asyncMap: typeof asyncMap;
-    getOkErr: typeof getOkErr;
+  ok: typeof ok;
+  err: typeof err;
+  unknownToError: typeof unknownToResultError;
+  asyncUnwrap: typeof asyncUnwrap;
+  asyncMap: typeof asyncMap;
+  getOkErr: typeof getOkErr;
 };
 /**
  * @deprecated Use `t-result` library instead.
@@ -97,12 +101,12 @@ declare function resultify<T, E extends ResultValidErrors = Error>(fn: Promise<T
 declare function unknownToError(error: unknown): Error;
 /** @deprecated Use `t-result` library instead. */
 type TypedResult<T, E extends ResultValidErrors = Error> = {
-    /** @deprecated Use `t-result` library instead. */
-    ok: (value: T) => Ok<T>;
-    /** @deprecated Use `t-result` library instead. */
-    err: (error: E) => Err<E>;
-    /** @deprecated Use `t-result` library instead. */
-    _type: Result<T, E>;
+  /** @deprecated Use `t-result` library instead. */
+  ok: (value: T) => Ok<T>;
+  /** @deprecated Use `t-result` library instead. */
+  err: (error: E) => Err<E>;
+  /** @deprecated Use `t-result` library instead. */
+  _type: Result<T, E>;
 };
 /** @deprecated Use `t-result` library instead. */
 type GetTypedResult<R extends Result<any, any>> = TypedResult<R extends Result<infer T, any> ? T : never, R extends Result<any, infer E> ? E : never>;
@@ -110,5 +114,5 @@ declare function getOkErr<F extends (...args: any[]) => Promise<Result<any, any>
 declare function getOkErr<F extends (...args: any[]) => Result<any, any>>(): TypedResult<ReturnType<F> extends Result<infer T, any> ? T : never, ReturnType<F> extends Result<any, infer E> ? E : never>;
 declare function getOkErr<R extends Result<any, any>>(): TypedResult<R extends Result<infer T, any> ? T : never, R extends Result<any, infer E> ? E : never>;
 declare function getOkErr<T, E extends ResultValidErrors = Error>(): TypedResult<T, E>;
-
-export { type GetTypedResult, Result, type ResultValidErrors, type TypedResult, err, ok, resultify, unknownToError };
+//#endregion
+export { GetTypedResult, Result, ResultValidErrors, TypedResult, err, ok, resultify, unknownToError };

package/dist/tsResult.mjs

@@ -0,0 +1,142 @@
+import { a as isFunction, c as isPromise, o as isObject } from "./assertions-qMxfVhSu.mjs";
+import { safeJsonStringify } from "./safeJson.mjs";
+
+//#region src/tsResult.ts
+function okUnwrapOr() {
+	return this.value;
+}
+function okMap(mapFn) {
+	return this.ok ? ok(mapFn(this.value)) : this;
+}
+function errMap(mapFn) {
+	return this.ok ? this : err(mapFn(this.error));
+}
+function mapOkAndErr({ ok: mapFn, err: mapErrFn }) {
+	return this.ok ? ok(mapFn(this.value)) : err(mapErrFn(this.error));
+}
+function returnResult() {
+	return this;
+}
+function okOnOk(fn) {
+	if (this.ok) fn(this.value);
+	return this;
+}
+function errOnErr(fn) {
+	if (!this.ok) fn(this.error);
+	return this;
+}
+/**
+* @deprecated Use `t-result` library instead.
+* @param value
+*/
+function ok(value = void 0) {
+	return {
+		ok: true,
+		error: false,
+		value,
+		unwrapOrNull: okUnwrapOr,
+		unwrapOr: okUnwrapOr,
+		unwrap: okUnwrapOr,
+		mapOk: okMap,
+		mapErr: returnResult,
+		mapOkAndErr,
+		ifOk: okOnOk,
+		ifErr: returnResult
+	};
+}
+/**
+* @deprecated Use `t-result` library instead.
+* @param error
+*/
+function err(error) {
+	return {
+		ok: false,
+		error,
+		errorResult() {
+			return err(error);
+		},
+		unwrapOrNull: () => null,
+		unwrapOr: (defaultValue) => defaultValue,
+		unwrap: (() => {
+			if (error instanceof Error) throw error;
+			throw unknownToError(error);
+		}),
+		mapOk: returnResult,
+		mapErr: errMap,
+		mapOkAndErr,
+		ifOk: returnResult,
+		ifErr: errOnErr
+	};
+}
+function unknownToResultError(error) {
+	return err(unknownToError(error));
+}
+/**
+* Unwraps a promise result
+*
+* @param result
+*/
+async function asyncUnwrap(result) {
+	const unwrapped = await result;
+	if (unwrapped.ok) return unwrapped.value;
+	if (unwrapped.error instanceof Error) throw unwrapped.error;
+	throw unknownToError(unwrapped.error);
+}
+function asyncMap(resultPromise) {
+	return {
+		err: async (mapFn) => {
+			const result = await resultPromise;
+			return result.ok ? ok(result.value) : err(mapFn(result.error));
+		},
+		ok: async (mapFn) => {
+			const result = await resultPromise;
+			return result.ok ? ok(mapFn(result.value)) : err(result.error);
+		},
+		okAndErr: async ({ ok: mapFn, err: mapErrFn }) => {
+			const result = await resultPromise;
+			return result.ok ? ok(mapFn(result.value)) : err(mapErrFn(result.error));
+		}
+	};
+}
+/** @deprecated Use `t-result` library instead. */
+const Result = {
+	ok,
+	err,
+	unknownToError: unknownToResultError,
+	asyncUnwrap,
+	asyncMap,
+	getOkErr
+};
+function resultify(fn, errorNormalizer) {
+	if (!isFunction(fn)) return fn.then((value) => ok(value)).catch((error) => err(errorNormalizer ? errorNormalizer(error) : unknownToError(error)));
+	try {
+		const result = fn();
+		if (isPromise(result)) return result.then((value) => ok(value)).catch((error) => err(errorNormalizer ? errorNormalizer(error) : unknownToError(error)));
+		return ok(result);
+	} catch (error) {
+		return err(errorNormalizer ? errorNormalizer(error) : unknownToError(error));
+	}
+}
+/**
+* @deprecated Use `t-result` library instead.
+* @param error
+*/
+function unknownToError(error) {
+	if (error instanceof Error) return error;
+	if (typeof error === "string") return new Error(error);
+	if (isObject(error)) return new Error("message" in error && error.message && typeof error.message === "string" ? error.message : safeJsonStringify(error) ?? "unknown", { cause: error });
+	return new Error(safeJsonStringify(error) ?? "unknown", { cause: error });
+}
+const typedResult = {
+	ok,
+	err,
+	get _type() {
+		throw new Error("usage as value is not allowed");
+	}
+};
+function getOkErr() {
+	return typedResult;
+}
+
+//#endregion
+export { Result, err, ok, resultify, unknownToError };

package/dist/typeGuards-B1mzA-Rz.mjs

@@ -0,0 +1,128 @@
+//#region src/typeGuards.ts
+/**
+* Type guard to check if a value is a plain object (not null, not an array).
+*
+* Returns true if the value is an object that is not null and not an array.
+* This is useful for distinguishing between objects and other types.
+*
+* @example
+*   ```typescript
+*   if (isObject(value)) {
+*     // TypeScript knows value is Record<string, unknown>
+*     console.log(value.someProperty);
+*   }
+*
+*   isObject({});           // true
+*   isObject({ a: 1 });     // true
+*   isObject(null);         // false
+*   isObject([]);           // false
+*   isObject('string');     // false
+*   ```;
+*
+* @param value - The value to check
+* @returns True if the value is a plain object, false otherwise
+*/
+function isObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Type guard to check if a value is a function.
+*
+* Returns true if the value is a function of any kind (regular function, arrow
+* function, method, constructor, etc.).
+*
+* @example
+*   ```typescript
+*   if (isFunction(value)) {
+*     // TypeScript knows value is (...args: any[]) => any
+*     const result = value();
+*   }
+*
+*   isFunction(() => {});           // true
+*   isFunction(function() {});      // true
+*   isFunction(Math.max);           // true
+*   isFunction('string');           // false
+*   isFunction({});                 // false
+*   ```;
+*
+* @param value - The value to check
+* @returns True if the value is a function, false otherwise
+*/
+function isFunction(value) {
+	return typeof value === "function";
+}
+/**
+* Type guard to check if a value is a Promise or thenable object.
+*
+* Returns true if the value is an object with a `then` method that is a
+* function. This covers both native Promises and thenable objects that
+* implement the Promise interface.
+*
+* @example
+*   ```typescript
+*   if (isPromise(value)) {
+*     // TypeScript knows value is Promise<unknown>
+*     const result = await value;
+*   }
+*
+*   isPromise(Promise.resolve());           // true
+*   isPromise(new Promise(() => {}));       // true
+*   isPromise({ then: () => {} });          // true
+*   isPromise({ then: 'not a function' });  // false
+*   isPromise('string');                    // false
+*   ```;
+*
+* @param value - The value to check
+* @returns True if the value is a Promise or thenable, false otherwise
+*/
+function isPromise(value) {
+	return isObject(value) && "then" in value && isFunction(value.then);
+}
+/**
+* Type guard to check if a value is a plain object (created by Object literal
+* or Object constructor).
+*
+* Returns true if the value is a plain object - an object created by the Object
+* constructor or object literal syntax. This excludes instances of classes,
+* built-in objects like Date, RegExp, etc.
+*
+* @example
+*   ```typescript
+*   if (isPlainObject(value)) {
+*     // TypeScript knows value is Record<string, unknown>
+*     console.log(Object.keys(value));
+*   }
+*
+*   isPlainObject({});                    // true
+*   isPlainObject({ a: 1 });              // true
+*   isPlainObject(Object.create(null));   // true
+*   isPlainObject(new Date());            // false
+*   isPlainObject(/regex/);               // false
+*   isPlainObject(new MyClass());         // false
+*   isPlainObject([]);                    // false
+*   ```;
+*
+* @param value - The value to check
+* @returns True if the value is a plain object, false otherwise
+*/
+function isPlainObject(value) {
+	if (!value || typeof value !== "object") return false;
+	const proto = Object.getPrototypeOf(value);
+	if (proto === null) return true;
+	const Ctor = Object.hasOwnProperty.call(proto, "constructor") && proto.constructor;
+	if (Ctor === Object) return true;
+	const objectCtorString = Object.prototype.constructor.toString();
+	return typeof Ctor == "function" && Function.toString.call(Ctor) === objectCtorString;
+}
+function isNonEmptyArray(value) {
+	return value.length > 0;
+}
+function arrayHasAtLeastXItems(array, minLength) {
+	return array.length >= minLength;
+}
+function isTruthy(value) {
+	return !!value;
+}
+
+//#endregion
+export { isPlainObject as a, isObject as i, isFunction as n, isPromise as o, isNonEmptyArray as r, isTruthy as s, arrayHasAtLeastXItems as t };

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

@@ -1,3 +1,4 @@
+//#region src/typeGuards.d.ts
 /**
  * Type guard to check if a value is a plain object (not null, not an array).
  *
@@ -107,5 +108,5 @@ declare function arrayHasAtLeastXItems<T>(array: T[], minLength: 3): array is [T
 declare function arrayHasAtLeastXItems<T>(array: T[], minLength: 4): array is [T, T, T, T, ...T[]];
 declare function arrayHasAtLeastXItems<T>(array: T[], minLength: 5): array is [T, T, T, T, T, ...T[]];
 declare function isTruthy<T>(value: T): value is Exclude<T, null | undefined | false | 0 | '' | 0n>;
-
-export { type NonEmptyArray, arrayHasAtLeastXItems, isFunction, isNonEmptyArray, isObject, isPlainObject, isPromise, isTruthy };
+//#endregion
+export { NonEmptyArray, arrayHasAtLeastXItems, isFunction, isNonEmptyArray, isObject, isPlainObject, isPromise, isTruthy };

package/dist/typeGuards.mjs

@@ -0,0 +1,3 @@
+import { a as isPlainObject, i as isObject, n as isFunction, o as isPromise, r as isNonEmptyArray, s as isTruthy, t as arrayHasAtLeastXItems } from "./typeGuards-B1mzA-Rz.mjs";
+
+export { arrayHasAtLeastXItems, isFunction, isNonEmptyArray, isObject, isPlainObject, isPromise, isTruthy };