@ls-stack/utils 3.39.0 → 3.41.0

package/dist/timers.d.ts

@@ -2,69 +2,70 @@ type CleanupTimer = () => void;
 /**
  * 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.
+ * 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
- *
- * @example
- * ```typescript
- * const cleanup = createTimeout(1000, () => {
- *   console.log('Timeout completed');
- * });
- *
- * // Cancel the timeout before it completes
- * cleanup();
- * ```
  */
 declare function createTimeout(ms: number, callback: () => void): CleanupTimer;
 /**
  * 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.
+ * 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
- *
- * @example
- * ```typescript
- * const cleanup = createInterval(1000, () => {
- *   console.log('Interval tick');
- * });
- *
- * // Stop the interval
- * cleanup();
- * ```
  */
 declare function createInterval(ms: number, callback: () => void): CleanupTimer;
 /**
  * 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.
+ * 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
- *
- * @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();
- * ```
+ * @returns An object with `call` to trigger the timeout and `clean` to cancel
+ *   it
  */
 declare function createDebouncedTimeout(ms: number, callback: () => void): {
     call: () => void;
@@ -73,32 +74,36 @@ declare function createDebouncedTimeout(ms: number, callback: () => void): {
 /**
  * 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.
+ * 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.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)
+ * @param options.checkIntervalMs - How often to check the condition in
+ *   milliseconds (default: 20)
  * @returns A cleanup function that cancels the condition timeout
- *
- * @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();
- * ```
  */
 declare function createWaitUntil<T extends NonNullable<unknown>>({ condition, maxWaitMs, callback, checkIntervalMs, }: {
     condition: () => false | T;

package/dist/tsResult.d.cts

@@ -37,18 +37,19 @@ type ResultMethodsKeys = keyof ResultMethods<any, any>;
 /** @deprecated Use `t-result` library instead. */
 declare function ok(): Ok<void>;
 /**
- * @param value
  * @deprecated Use `t-result` library instead.
+ * @param value
  */
 declare function ok<T>(value: T): Ok<T>;
 /**
- * @param error
  * @deprecated Use `t-result` library instead.
+ * @param error
  */
 declare function err<E extends ResultValidErrors>(error: E): Err<E>;
 declare function unknownToResultError(error: unknown): Err<Error>;
 /**
  * Unwraps a promise result
+ *
  * @param result
  */
 declare function asyncUnwrap<T>(result: Promise<Result<T, ResultValidErrors>>): Promise<T>;
@@ -72,26 +73,26 @@ declare const Result: {
     getOkErr: typeof getOkErr;
 };
 /**
+ * @deprecated Use `t-result` library instead.
  * @param fn
  * @param errorNormalizer
- * @deprecated Use `t-result` library instead.
  */
 declare function resultify<T, E extends ResultValidErrors = Error>(fn: () => T extends Promise<any> ? never : T, errorNormalizer?: (err: unknown) => E): Result<T, E>;
 /**
+ * @deprecated Use `t-result` library instead.
  * @param fn
  * @param errorNormalizer
- * @deprecated Use `t-result` library instead.
  */
 declare function resultify<T, E extends ResultValidErrors = Error>(fn: () => Promise<T>, errorNormalizer?: (err: unknown) => E): Promise<Result<Awaited<T>, E>>;
 /**
+ * @deprecated Use `t-result` library instead.
  * @param fn
  * @param errorNormalizer
- * @deprecated Use `t-result` library instead.
  */
 declare function resultify<T, E extends ResultValidErrors = Error>(fn: Promise<T>, errorNormalizer?: (err: unknown) => E): Promise<Result<T, E>>;
 /**
- * @param error
  * @deprecated Use `t-result` library instead.
+ * @param error
  */
 declare function unknownToError(error: unknown): Error;
 /** @deprecated Use `t-result` library instead. */

package/dist/tsResult.d.ts

@@ -37,18 +37,19 @@ type ResultMethodsKeys = keyof ResultMethods<any, any>;
 /** @deprecated Use `t-result` library instead. */
 declare function ok(): Ok<void>;
 /**
- * @param value
  * @deprecated Use `t-result` library instead.
+ * @param value
  */
 declare function ok<T>(value: T): Ok<T>;
 /**
- * @param error
  * @deprecated Use `t-result` library instead.
+ * @param error
  */
 declare function err<E extends ResultValidErrors>(error: E): Err<E>;
 declare function unknownToResultError(error: unknown): Err<Error>;
 /**
  * Unwraps a promise result
+ *
  * @param result
  */
 declare function asyncUnwrap<T>(result: Promise<Result<T, ResultValidErrors>>): Promise<T>;
@@ -72,26 +73,26 @@ declare const Result: {
     getOkErr: typeof getOkErr;
 };
 /**
+ * @deprecated Use `t-result` library instead.
  * @param fn
  * @param errorNormalizer
- * @deprecated Use `t-result` library instead.
  */
 declare function resultify<T, E extends ResultValidErrors = Error>(fn: () => T extends Promise<any> ? never : T, errorNormalizer?: (err: unknown) => E): Result<T, E>;
 /**
+ * @deprecated Use `t-result` library instead.
  * @param fn
  * @param errorNormalizer
- * @deprecated Use `t-result` library instead.
  */
 declare function resultify<T, E extends ResultValidErrors = Error>(fn: () => Promise<T>, errorNormalizer?: (err: unknown) => E): Promise<Result<Awaited<T>, E>>;
 /**
+ * @deprecated Use `t-result` library instead.
  * @param fn
  * @param errorNormalizer
- * @deprecated Use `t-result` library instead.
  */
 declare function resultify<T, E extends ResultValidErrors = Error>(fn: Promise<T>, errorNormalizer?: (err: unknown) => E): Promise<Result<T, E>>;
 /**
- * @param error
  * @deprecated Use `t-result` library instead.
+ * @param error
  */
 declare function unknownToError(error: unknown): Error;
 /** @deprecated Use `t-result` library instead. */

package/dist/typeGuards.d.cts

@@ -4,98 +4,99 @@
  * 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
- *
- * @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
- * ```
  */
 declare function isObject(value: unknown): value is Record<string, unknown>;
 /**
  * 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.).
+ * 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
- *
- * @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
- * ```
  */
 declare function isFunction(value: unknown): value is (...args: any[]) => any;
 /**
  * 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.
+ * 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
- *
- * @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
- * ```
  */
 declare function isPromise(value: unknown): value is Promise<unknown>;
 /**
- * Type guard to check if a value is a plain object (created by Object literal or Object constructor).
+ * 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
- *
- * @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
- * ```
  */
 declare function isPlainObject(value: any): value is Record<string, unknown>;
 type NonEmptyArray<T> = [T, ...T[]];

package/dist/typeGuards.d.ts

@@ -4,98 +4,99 @@
  * 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
- *
- * @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
- * ```
  */
 declare function isObject(value: unknown): value is Record<string, unknown>;
 /**
  * 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.).
+ * 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
- *
- * @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
- * ```
  */
 declare function isFunction(value: unknown): value is (...args: any[]) => any;
 /**
  * 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.
+ * 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
- *
- * @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
- * ```
  */
 declare function isPromise(value: unknown): value is Promise<unknown>;
 /**
- * Type guard to check if a value is a plain object (created by Object literal or Object constructor).
+ * 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
- *
- * @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
- * ```
  */
 declare function isPlainObject(value: any): value is Record<string, unknown>;
 type NonEmptyArray<T> = [T, ...T[]];

package/dist/typeUtils.d.cts

@@ -4,6 +4,10 @@ type PartialRecord<K extends keyof any, T> = {
 type NonPartial<T> = {
     [K in keyof Required<T>]: T[K];
 };
+/**
+ * @deprecated Use `ObjKeysWithValuesOfType` from `@ls-stack/utils/typeUtils`
+ *   instead
+ */
 type ObjKeysWithValuesOfType<Obj extends Record<PropertyKey, unknown>, ValueType> = {
     [K in keyof Obj]: Obj[K] extends ValueType ? K : never;
 }[keyof Obj];
@@ -26,12 +30,14 @@ type DeepReplaceValueImpl<T, ReplaceType, NewType, SkipPaths extends string | un
     [K in keyof T]: DeepReplaceValueImpl<T[K], ReplaceType, NewType, SkipPaths, SkipType, BuildPath<Path, K>>;
 } : T;
 /**
- * Replaces all values that extends `ReplaceType` with `NewType` in a deeply nested object or array.
+ * Replaces all values that extends `ReplaceType` with `NewType` in a deeply
+ * nested object or array.
  *
  * @template T - The object or array to replace values in.
  * @template ReplaceType - The type to replace.
  * @template NewType - The new type to replace with.
- * @template SkipPaths - The paths to skip in transverse. e.g. 'a.b.c' | 'array[*].b'
+ * @template SkipPaths - The paths to skip in transverse. e.g. 'a.b.c' |
+ *   'array[*].b'
  * @template SkipTypes - The types to skip in transverse and replace.
  */
 type DeepReplaceValue<T, ReplaceType, NewType, SkipPaths extends string | undefined = undefined, SkipTypes = DefaultSkipTransverseDeepReplace> = DeepReplaceValueImpl<T, ReplaceType, NewType, SkipPaths, SkipTypes>;
@@ -39,8 +45,16 @@ type KeysWithUndefinedValues<T extends Record<string, unknown>> = {
     [K in keyof T]: undefined extends T[K] ? K : never;
 }[keyof T];
 /**
- * Marks all possible undefined values as partial at the root level of the object.
+ * Marks all possible undefined values as partial at the root level of the
+ * object.
  */
 type PartialPossiblyUndefinedValues<T extends Record<string, unknown>> = Prettify<Partial<Pick<T, KeysWithUndefinedValues<T>>> & Omit<T, KeysWithUndefinedValues<T>>>;
+type PickUndefinedKeys<T> = {
+    [K in keyof T]: undefined extends T[K] ? K : never;
+}[keyof T];
+type PickRequiredKeys<T> = {
+    [K in keyof T]: undefined extends T[K] ? never : K;
+}[keyof T];
+type MakeUndefinedKeysOptional<T> = Prettify<Partial<Pick<T, PickUndefinedKeys<T>>> & Pick<T, PickRequiredKeys<T>>>;
 
-export type { DeepPrettify, DeepReplaceValue, DefaultSkipTransverseDeepReplace, IsAny, NonPartial, ObjKeysWithValuesOfType, PartialPossiblyUndefinedValues, PartialRecord, Prettify };
+export type { DeepPrettify, DeepReplaceValue, DefaultSkipTransverseDeepReplace, IsAny, MakeUndefinedKeysOptional, NonPartial, ObjKeysWithValuesOfType, PartialPossiblyUndefinedValues, PartialRecord, Prettify };