@ls-stack/utils 3.17.1 → 3.19.0

package/lib/timers.d.ts

@@ -0,0 +1,110 @@
+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.
+ *
+ * @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.
+ *
+ * @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.
+ *
+ * @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();
+ * ```
+ */
+declare function createDebouncedTimeout(ms: number, callback: () => void): {
+    call: () => void;
+    clean: CleanupTimer;
+};
+/**
+ * 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.
+ *
+ * @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
+ *
+ * @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;
+    maxWaitMs: number;
+    callback: (value: T) => void;
+    checkIntervalMs?: number;
+}): CleanupTimer;
+
+export { type CleanupTimer, createDebouncedTimeout, createInterval, createTimeout, createWaitUntil };

package/lib/timers.js

@@ -0,0 +1,65 @@
+// src/timers.ts
+function createTimeout(ms, callback) {
+  const timeoutId = setTimeout(callback, ms);
+  let isCleaned = false;
+  return () => {
+    if (isCleaned) return;
+    clearTimeout(timeoutId);
+    isCleaned = true;
+  };
+}
+function createInterval(ms, callback) {
+  const intervalId = setInterval(callback, ms);
+  let isCleaned = false;
+  return () => {
+    if (isCleaned) return;
+    clearInterval(intervalId);
+    isCleaned = true;
+  };
+}
+function createDebouncedTimeout(ms, callback) {
+  let cleanupTimer = null;
+  return {
+    clean: () => {
+      cleanupTimer?.();
+    },
+    call: () => {
+      cleanupTimer?.();
+      cleanupTimer = createTimeout(ms, () => {
+        callback();
+      });
+    }
+  };
+}
+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?.();
+  };
+}
+export {
+  createDebouncedTimeout,
+  createInterval,
+  createTimeout,
+  createWaitUntil
+};

package/lib/tsResult.js

@@ -5,8 +5,8 @@ import {
   isFunction,
   isObject,
   isPromise
-} from "./chunk-WS4WEVHU.js";
-import "./chunk-SSKW673U.js";
+} from "./chunk-C2SVCIWE.js";
+import "./chunk-JF2MDHOJ.js";
 
 // src/tsResult.ts
 function okUnwrapOr() {

package/lib/typeGuards.cjs

@@ -25,7 +25,8 @@ __export(typeGuards_exports, {
   isNonEmptyArray: () => isNonEmptyArray,
   isObject: () => isObject,
   isPlainObject: () => isPlainObject,
-  isPromise: () => isPromise
+  isPromise: () => isPromise,
+  isTruthy: () => isTruthy
 });
 module.exports = __toCommonJS(typeGuards_exports);
 function isObject(value) {
@@ -54,6 +55,9 @@ function isNonEmptyArray(value) {
 function arrayHasAtLeastXItems(array, minLength) {
   return array.length >= minLength;
 }
+function isTruthy(value) {
+  return !!value;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   arrayHasAtLeastXItems,
@@ -61,5 +65,6 @@ function arrayHasAtLeastXItems(array, minLength) {
   isNonEmptyArray,
   isObject,
   isPlainObject,
-  isPromise
+  isPromise,
+  isTruthy
 });

package/lib/typeGuards.d.cts

@@ -105,5 +105,6 @@ declare function arrayHasAtLeastXItems<T>(array: T[], minLength: 2): array is [T
 declare function arrayHasAtLeastXItems<T>(array: T[], minLength: 3): array is [T, T, T, ...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 };
+export { type NonEmptyArray, arrayHasAtLeastXItems, isFunction, isNonEmptyArray, isObject, isPlainObject, isPromise, isTruthy };

package/lib/typeGuards.d.ts

@@ -105,5 +105,6 @@ declare function arrayHasAtLeastXItems<T>(array: T[], minLength: 2): array is [T
 declare function arrayHasAtLeastXItems<T>(array: T[], minLength: 3): array is [T, T, T, ...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 };
+export { type NonEmptyArray, arrayHasAtLeastXItems, isFunction, isNonEmptyArray, isObject, isPlainObject, isPromise, isTruthy };

package/lib/typeGuards.js

@@ -4,13 +4,15 @@ import {
   isNonEmptyArray,
   isObject,
   isPlainObject,
-  isPromise
-} from "./chunk-SSKW673U.js";
+  isPromise,
+  isTruthy
+} from "./chunk-JF2MDHOJ.js";
 export {
   arrayHasAtLeastXItems,
   isFunction,
   isNonEmptyArray,
   isObject,
   isPlainObject,
-  isPromise
+  isPromise,
+  isTruthy
 };

package/lib/typingFnUtils.cjs

@@ -44,7 +44,11 @@ function asType(value) {
   return value;
 }
 function narrowStringToUnion(key, union) {
-  if (key && union.includes(key)) {
+  if (!key) return void 0;
+  if (union instanceof Set) {
+    return union.has(key) ? key : void 0;
+  }
+  if (union.includes(key)) {
     return key;
   }
   return void 0;

package/lib/typingFnUtils.d.cts

@@ -10,7 +10,7 @@ declare function typedObjectKeys<T extends Record<string, unknown>>(obj: T): (ke
 /** a safe way to cast types, use to substitute the `as Type` */
 declare function asType<T = unknown>(value: T): T;
 /** narrow a string to a union of strings */
-declare function narrowStringToUnion<const T extends string>(key: string | undefined | null, union: T[]): T | undefined;
+declare function narrowStringToUnion<const T extends string>(key: string | undefined | null, union: T[] | readonly T[] | Set<T>): T | undefined;
 /**
  * Type helper to check if a type is a subtype of another type.
  *

package/lib/typingFnUtils.d.ts

@@ -10,7 +10,7 @@ declare function typedObjectKeys<T extends Record<string, unknown>>(obj: T): (ke
 /** a safe way to cast types, use to substitute the `as Type` */
 declare function asType<T = unknown>(value: T): T;
 /** narrow a string to a union of strings */
-declare function narrowStringToUnion<const T extends string>(key: string | undefined | null, union: T[]): T | undefined;
+declare function narrowStringToUnion<const T extends string>(key: string | undefined | null, union: T[] | readonly T[] | Set<T>): T | undefined;
 /**
  * Type helper to check if a type is a subtype of another type.
  *

package/lib/typingFnUtils.js

@@ -12,7 +12,11 @@ function asType(value) {
   return value;
 }
 function narrowStringToUnion(key, union) {
-  if (key && union.includes(key)) {
+  if (!key) return void 0;
+  if (union instanceof Set) {
+    return union.has(key) ? key : void 0;
+  }
+  if (union.includes(key)) {
     return key;
   }
   return void 0;

package/lib/yamlStringify.js

@@ -1,14 +1,14 @@
+import {
+  bytesToHumanReadable
+} from "./chunk-IATIXMCE.js";
 import {
   truncateString
 } from "./chunk-4REIIZQY.js";
 import {
   isObject,
   isPlainObject
-} from "./chunk-WS4WEVHU.js";
-import "./chunk-SSKW673U.js";
-import {
-  bytesToHumanReadable
-} from "./chunk-IATIXMCE.js";
+} from "./chunk-C2SVCIWE.js";
+import "./chunk-JF2MDHOJ.js";
 
 // src/yamlStringify.ts
 function yamlStringify(obj, {

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "@ls-stack/utils",
-  "description": "Typescript utils",
-  "version": "3.17.1",
+  "description": "Universal TypeScript utilities for browser and Node.js",
+  "version": "3.19.0",
   "license": "MIT",
   "files": [
-    "lib"
+    "lib",
+    "docs"
   ],
   "repository": "github:lucasols/utils",
+  "homepage": "https://github.com/lucasols/utils/tree/main/packages/utils",
   "author": "Lucas Santos",
   "type": "module",
   "sideEffects": false,
@@ -34,6 +36,10 @@
       "import": "./lib/asyncQueue.js",
       "require": "./lib/asyncQueue.cjs"
     },
+    "./awaitDebounce": {
+      "import": "./lib/awaitDebounce.js",
+      "require": "./lib/awaitDebounce.cjs"
+    },
     "./cache": {
       "import": "./lib/cache.js",
       "require": "./lib/cache.cjs"
@@ -78,6 +84,10 @@
       "import": "./lib/exhaustiveMatch.js",
       "require": "./lib/exhaustiveMatch.cjs"
     },
+    "./getAutoIncrementId": {
+      "import": "./lib/getAutoIncrementId.js",
+      "require": "./lib/getAutoIncrementId.cjs"
+    },
     "./getCompositeKey": {
       "import": "./lib/getCompositeKey.js",
       "require": "./lib/getCompositeKey.cjs"
@@ -150,10 +160,18 @@
       "import": "./lib/testUtils.js",
       "require": "./lib/testUtils.cjs"
     },
+    "./throttle": {
+      "import": "./lib/throttle.js",
+      "require": "./lib/throttle.cjs"
+    },
     "./time": {
       "import": "./lib/time.js",
       "require": "./lib/time.cjs"
     },
+    "./timers": {
+      "import": "./lib/timers.js",
+      "require": "./lib/timers.cjs"
+    },
     "./tsResult": {
       "import": "./lib/tsResult.js",
       "require": "./lib/tsResult.cjs"
@@ -183,6 +201,7 @@
     "node": ">=20.0.0"
   },
   "devDependencies": {
+    "@eslint/js": "^9.18.0",
     "@ls-stack/extended-lint": "^0.20.1",
     "@types/eslint": "^9.6.1",
     "@types/eslint__js": "^8.42.3",
@@ -217,16 +236,11 @@
     "lint": "pnpm tsc && pnpm eslint",
     "tsc": "tsc -p tsconfig.prod.json",
     "tsc:watch": "tsc -p tsconfig.prod.json --watch",
-    "eslint": "CI=true eslint src/ scripts/ --color --max-warnings=0",
-    "build": "pnpm test && pnpm lint && pnpm build:no-test && pnpm run docs && pnpm run docs:commit && pnpm build:update-exports",
-    "build:no-test": "tsup",
-    "build:update-exports": "tsm --no-warnings scripts/updatePackageExports.ts",
-    "build-test": "tsup --config tsup.test.config.ts",
-    "pre-publish": "./scripts/check-if-is-sync.sh && pnpm build",
-    "test:console-fmt": "tsm --no-warnings scripts/testConsoleFmt.ts",
+    "eslint": "CI=true eslint src/ --color --max-warnings=0 --fix",
+    "format": "prettier --write .",
+    "build": "tsup",
     "bench:deepEqual": "tsm --no-warnings benchmarks/deepEqual.ts",
     "docs": "typedoc",
-    "docs:watch": "typedoc --watch",
-    "docs:commit": "git add docs && git diff --cached --quiet docs || git commit -m 'docs: update docs'"
+    "docs:watch": "typedoc --watch"
   }
 }