@ls-stack/utils 3.18.0 → 3.20.0

package/lib/throttle.d.ts

@@ -0,0 +1,89 @@
+import { DebouncedFunc } from './debounce.js';
+import { __LEGIT_ANY_FUNCTION__ } from './saferTyping.js';
+
+interface ThrottleSettings {
+    /**
+     * Specify invoking on the leading edge of the timeout.
+     * @default true
+     */
+    leading?: boolean;
+    /**
+     * Specify invoking on the trailing edge of the timeout.
+     * @default true
+     */
+    trailing?: boolean;
+}
+/**
+ * Creates a throttled function that only invokes the provided function at most once per every `wait` milliseconds.
+ * The throttled function comes with a `cancel` method to cancel delayed invocations and a `flush` method to immediately invoke them.
+ *
+ * Throttling is useful for rate-limiting events that fire frequently, like scroll or resize handlers.
+ * Unlike debouncing, throttling guarantees the function is called at regular intervals.
+ *
+ * @template T - The type of the function to throttle
+ * @param func - The function to throttle
+ * @param wait - The number of milliseconds to throttle invocations to
+ * @param options - The options object
+ * @param options.leading - Specify invoking on the leading edge of the timeout (default: true)
+ * @param options.trailing - Specify invoking on the trailing edge of the timeout (default: true)
+ * @returns Returns the new throttled function
+ *
+ * @example
+ * ```ts
+ * const throttledSave = throttle(saveData, 1000);
+ *
+ * // Will only call saveData at most once per second
+ * throttledSave();
+ * throttledSave();
+ * throttledSave();
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Only invoke on trailing edge
+ * const throttledHandler = throttle(handleScroll, 100, { leading: false });
+ * ```
+ */
+declare function throttle<T extends __LEGIT_ANY_FUNCTION__>(func: T, wait: number, options?: ThrottleSettings): DebouncedFunc<T>;
+/**
+ * Creates a factory for throttled functions that caches throttled instances based on function arguments.
+ * Each unique set of arguments gets its own throttled function instance, allowing for fine-grained
+ * throttling control per argument combination.
+ *
+ * This is useful when you want to throttle calls to the same function but with different parameters
+ * independently. For example, throttling API calls per user ID or throttling UI updates per component.
+ *
+ * @template T - The type of arguments the callback function accepts
+ * @template R - The return type of the callback function
+ * @param wait - The number of milliseconds to throttle invocations to
+ * @param callback - The function to throttle
+ * @param options - The throttle options (leading/trailing behavior)
+ * @returns An object with a `call` method that accepts the callback arguments
+ *
+ * @example
+ * ```ts
+ * const apiThrottle = createThrottledFunctionFactory(
+ *   1000,
+ *   (userId: string, action: string) => callAPI(userId, action)
+ * );
+ *
+ * // Each user gets their own throttled instance
+ * apiThrottle.call('user1', 'update'); // Executes immediately
+ * apiThrottle.call('user2', 'update'); // Executes immediately (different user)
+ * apiThrottle.call('user1', 'update'); // Throttled (same user)
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Throttle UI updates per component
+ * const updateThrottle = createThrottledFunctionFactory(
+ *   100,
+ *   (componentId: string, data: any) => updateComponent(componentId, data)
+ * );
+ * ```
+ */
+declare function createThrottledFunctionFactory<T extends string | number | null | undefined | boolean, R>(wait: number, callback: (...args: T[]) => R, options?: ThrottleSettings): {
+    call: (...args: T[]) => R | undefined;
+};
+
+export { createThrottledFunctionFactory, throttle };

package/lib/throttle.js

@@ -0,0 +1,38 @@
+import {
+  debounce
+} from "./chunk-NW5H5EW7.js";
+import {
+  EnhancedMap
+} from "./chunk-7CQPOM5I.js";
+import "./chunk-C2SVCIWE.js";
+import "./chunk-JF2MDHOJ.js";
+
+// src/throttle.ts
+function throttle(func, wait, options) {
+  let leading = true;
+  let trailing = true;
+  if (options) {
+    leading = "leading" in options ? !!options.leading : leading;
+    trailing = "trailing" in options ? !!options.trailing : trailing;
+  }
+  return debounce(func, wait, { leading, maxWait: wait, trailing });
+}
+function createThrottledFunctionFactory(wait, callback, options) {
+  const cache = new EnhancedMap();
+  return {
+    call: (...args) => {
+      const key = args.map(
+        (arg) => arg === void 0 ? "__UNDEFINED__" : JSON.stringify(arg)
+      ).join(",");
+      const cachedFunction = cache.getOrInsert(
+        key,
+        () => throttle(callback, wait, options)
+      );
+      return cachedFunction(...args);
+    }
+  };
+}
+export {
+  createThrottledFunctionFactory,
+  throttle
+};

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.18.0",
+  "description": "Universal TypeScript utilities for browser and Node.js",
+  "version": "3.20.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,6 +160,10 @@
       "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"
@@ -187,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",
@@ -221,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"
   }
 }