moderndash 0.8.0 → 0.10.0

package/dist/index.d.ts

@@ -41,7 +41,7 @@ type MinimumTwoArrays<TInput> = [TInput[], TInput[], ...TInput[][]];
  * @description Generic function type, should fit any function
  * @typeParam TFunc - The input function type
  */
-type GenericFunction<TFunc extends (...args: any) => any> = (...args: Parameters<TFunc>) => ReturnType<TFunc>;
+type GenericFunction<TFunc extends (...args: any) => void> = (...args: Parameters<TFunc>) => ReturnType<TFunc>;
 type PlainObject$1 = Record<PropertyKey, unknown>;
 
 /**
@@ -260,64 +260,31 @@ declare function takeWhile<TArr>(array: TArr[], predicate: (elem: TArr) => boole
  */
 declare function unique<TInput>(array: TInput[], compareFn?: (a: TInput, b: TInput) => boolean): TInput[];
 
-type Tail<T extends unknown[]> = T extends [infer _Head, ...infer Tail] ? Tail : never;
 /**
- * Transforms a function that takes a function as first argument into a decorator function.
+ * Debouces the decorated function. Only calling it after a specified amount of time has passed without any new calls.
  *
- * @example
- * function log(func: Function, message: string) {
- *   return function (...args: unknown[]) {
- *     console.log(message);
- *     return func(...args);
- *   };
- * }
+ * Look at {@link debounce} for the non-decorator version.
  *
- * const logger = toDecorator(log);
+ * *Requires TypeScript >=5.0 or `experimentalDecorators` flag enabled.*
  *
+ * @example
+ * ```typescript
  * class TestClass {
- *   @logger("Hello world!")
- *   testMethod() {
- *     return 1;
+ *   @decDebounce(1000)
+ *   testMethod(str: string) {
+ *     console.log("Debounced:", str);
  *   }
  * }
  *
  * const instance = new TestClass();
- * instance.testMethod();
- * // => Log "Hello World" and return 1
- *
- * @param func - The function to transform.
- * @returns A decorator function that can be used to decorate a method.
+ * instance.testMethod("Hello");
+ * instance.testMethod("World");
+ * // => Only the second invocation of `debouncedSayHello` is executed, after a delay of 1000ms.
+ * ```
+ * @param wait - Milliseconds to wait before invoking the decorated function after the last invocation.
  */
-declare function toDecorator<TFunc extends GenericFunction<TFunc>>(func: TFunc): (...args: Tail<Parameters<TFunc>>) => (target: unknown, key: string, descriptor: PropertyDescriptor) => void;
+declare function decDebounce(wait: number): (target: unknown, key: string, descriptor: PropertyDescriptor) => void;
 
-declare function debounce<TFunc extends GenericFunction<TFunc>>(fn: TFunc, wait?: number, options?: {
-    leading?: boolean;
-    maxWait?: number;
-    trailing?: boolean;
-}): (this: ThisParameterType<TFunc>, ...args: Parameters<TFunc>) => ReturnType<TFunc>;
-
-/**
- * Creates a function that invokes the given function as long as it's called `<= n` times.
- *
- * Subsequent calls to the created function return the result of the last `func` invocation.
- *
- * This function can be used as a decorator with {@link decMaxCalls}.
- * @example
- * let count = 0;
- * const addCount = () => ++count;
- *
- * // Allow addCount to be invoked twice.
- * const limitAddCount = maxCalls(2, addCount)
- *
- * limitAddCount() // => 1
- * limitAddCount() // => 2
- * limitAddCount() // => 2
- * // => `limitAddCount` is invoked twice and the result is cached.
- * @param n - The number of calls before the cached result is returned.
- * @param func - The function to restrict.
- * @returns Returns the new restricted function.
- */
-declare function maxCalls<TFunc extends GenericFunction<TFunc>>(func: TFunc, n: number): TFunc;
 /**
  * Only invokes the decorated function as long as it's called `<= n` times.
  * Subsequent calls to the decorated function return the result of the last invocation.
@@ -327,6 +294,7 @@ declare function maxCalls<TFunc extends GenericFunction<TFunc>>(func: TFunc, n:
  * *Requires TypeScript >=5.0 or `experimentalDecorators` flag enabled.*
  *
  * @example
+ * ```typescript
  * class TestClass {
  *  private count = 0;
  *  @decMaxCalls(2)
@@ -338,68 +306,91 @@ declare function maxCalls<TFunc extends GenericFunction<TFunc>>(func: TFunc, n:
  * instance.testMethod(); // => 1
  * instance.testMethod(); // => 2
  * instance.testMethod(); // => 2
- *
+ * ```
+ * @param n - The number of calls before the cached result is returned.
  */
-declare const decMaxCalls: (n: number) => (target: unknown, key: string, descriptor: PropertyDescriptor) => void;
+declare function decMaxCalls(n: number): (target: unknown, key: string, descriptor: PropertyDescriptor) => void;
 
 /**
  * Creates a function that memoizes the result of `func`.
- * If `resolver` is provided, it determines the cache key for storing the result based on the arguments provided to the memoized function.
- * By default, all arguments provided to the memoized function are used as the map cache key.
+ * The cache key is either determined by the provided resolver or by the arguments used in the memoized function.
  *
- * The cache is exposed as the `cache` property on the memoized
- * function. Its creation may be customized by replacing the `memoize.Cache`
- * constructor with one whose instances implement the
- * [`Map`](http://ecma-international.org/ecma-262/7.0/#sec-properties-of-the-map-prototype-object)
- * method interface of `clear`, `delete`, `get`, `has`, and `set`.
+ * The cache is exposed as the `cache` property on the memoized function.
+ * Its creation may be customized by replacing the `memoize.cache` value.
+ * The new cache must implement `get` and `set` methods like the built-in `Map` constructors.
+ *
+ * **Options:**
+ * - `resolver` A function that determines the cache key for storing the result based on the arguments provided.
+ * - `ttl` sets the time to live for the cache in milliseconds. After `ttl` milliseconds, the next call to the memoized function will result in a cache miss.
+ *
+ * This function can be used as a decorator with {@link decMemoize}.
  *
  * @example
+ * ```typescript
  * const object = { 'a': 1, 'b': 2 }
  *
- * const values = memoize(values)
+ * const values = memoize(Object.values, { ttl: 1000 })
  * values(object)
  * // => [1, 2]
  *
  * values(object)
  * // => [1, 2]
  *
- * object.a = 2
- * values(object)
- * // => [2, 2]
+ * setTimeout(() => values(object), 1000)
+ * // => [1, 2] (cache miss after 1 second)
  *
- * // Modify the result cache.
- * values.cache.set(object, ['a', 'b'])
- * values(object)
- * // => ['a', 'b']
+ * // Replace `memoize.cache`.
+ * memoize.cache = new WeakMap()
  *
- * // Replace `memoize.Cache`.
- * memoize.Cache = WeakMap
+ * // This is the default way to create cache keys.
+ * const defaultResolver = (...args: unknown[]) => JSON.stringify(args);
+ * ```
  * @param func - The function to have its output memoized.
- * @param resolver - The function to resolve the cache key.
- * @returns  Returns the new memoized function.
+ * @param options - The options object with optional `resolver` and `ttl` parameters.
+ * @param options.resolver - A function that determines the cache key for storing the result based on the arguments provided.
+ * @param options.ttl - The time to live for the cache in milliseconds.
+ * @returns Returns the new memoized function.
  */
-declare function memoize<TFunc extends GenericFunction<TFunc>, Cache extends Map<string | symbol, ReturnType<TFunc>>>(func: TFunc, resolver?: ((...args: Parameters<TFunc>) => string | symbol)): TFunc & {
+declare function memoize<TFunc extends GenericFunction<TFunc>, Cache extends Map<string | symbol, [ReturnType<TFunc>, number]>>(func: TFunc, options?: {
+    resolver?: (...args: Parameters<TFunc>) => string | symbol;
+    ttl?: number;
+}): TFunc & {
     cache: Cache;
 };
 
 /**
- * Creates a function that invokes the given function once it's called more than `n` times.
- * Returns undefined until the minimum call count is reached.
+ * Memoizes the decorated function.
+ * The cache key is either determined by the provided resolver or by the arguments used in the memoized function.
  *
- * This function can be used as a decorator with {@link decMinCalls}.
- * @example
- * const caution = () => console.log("Caution!");
- * const minCalls = after(caution, 2);
+ * **Options:**
+ * - `resolver` A function that determines the cache key for storing the result based on the arguments provided.
+ * - `ttl` sets the time to live for the cache in milliseconds. After `ttl` milliseconds, the next call to the memoized function will result in a cache miss.
  *
- * minCalls()
- * minCalls()
- * minCalls()
- * // => `caution` is invoked on the third call.
- * @param n The number of calls before the given function is invoked.
- * @param func The function to restrict.
- * @returns Returns the new restricted function.
+ * Look at {@link memoize} for the non-decorator version.
+ *
+ * *Requires TypeScript >=5.0 or `experimentalDecorators` flag enabled.*
+ *
+ * @example
+ * ```typescript
+ * class TestClass {
+ *   @decMemoize({ ttl: 1000 })
+ *   testMethod(a: number, b: number) {
+ *     return a + b;
+ *   }
+ * }
+ * const instance = new TestClass();
+ * instance.testMethod(1, 2); // => 3
+ * instance.testMethod(1, 2); // => 3 (cached)
+ *
+ * // After 1 second:
+ * instance.testMethod(1, 2); // => 3 (cache miss)
+ * ```
+ * @param options - The options object.
+ * @param options.resolver - A function that determines the cache key for storing the result based on the arguments provided.
+ * @param options.ttl - The time to live for the cache in milliseconds.
  */
-declare function minCalls<TFunc extends GenericFunction<TFunc>>(func: TFunc, n: number): (this: ThisParameterType<TFunc>, ...args: Parameters<TFunc>) => ReturnType<TFunc> | undefined;
+declare function decMemoize(options?: Parameters<typeof memoize>[1]): (target: unknown, key: string, descriptor: PropertyDescriptor) => void;
+
 /**
  * Only invokes the decorated function after it's called more than `n` times.
  *
@@ -407,6 +398,7 @@ declare function minCalls<TFunc extends GenericFunction<TFunc>>(func: TFunc, n:
  *
  * *Requires TypeScript >=5.0 or `experimentalDecorators` flag enabled.*
  * @example
+ * ```typescript
  * class TestClass {
  *   @decAfter(2)
  *   testMethod() {
@@ -417,15 +409,150 @@ declare function minCalls<TFunc extends GenericFunction<TFunc>>(func: TFunc, n:
  * instance.testMethod(); // => undefined
  * instance.testMethod(); // => undefined
  * instance.testMethod(); // => 1
+ * ```
+ * @param n The number of calls before the decorated function is invoked.
+ */
+declare function decMinCalls(n: number): (target: unknown, key: string, descriptor: PropertyDescriptor) => void;
+
+/**
+ * The decorated function is invoked at most once per every `wait` milliseconds.
  *
- * @param runAfter The number of calls before the decorated function is invoked.
+ * Look at {@link throttle} for the non-decorator version.
+ *
+ * *Requires TypeScript >=5.0 or `experimentalDecorators` flag enabled.*
+ *
+ * @example
+ * ```typescript
+ * class TestClass {
+ *   @decThrottle(1000)
+ *   testMethod() {
+ *     console.log("Throttled!");
+ *   }
+ * }
+ *
+ * const instance = new TestClass();
+ * instance.testMethod(); // => "Throttled!" is logged once per second.
+ * instance.testMethod(); // nothing happens
+ * ```
+ * @param wait - The number of milliseconds to wait between invocations.
  */
-declare const decMinCalls: (n: number) => (target: unknown, key: string, descriptor: PropertyDescriptor) => void;
+declare function decThrottle(wait: number): (target: unknown, key: string, descriptor: PropertyDescriptor) => void;
 
-declare function throttle<TFunc extends GenericFunction<TFunc>>(func: TFunc, wait?: number, options?: {
-    leading?: boolean;
-    trailing?: boolean;
-}): (this: ThisParameterType<TFunc>, ...args: Parameters<TFunc>) => ReturnType<TFunc>;
+type Tail<T extends unknown[]> = T extends [infer _Head, ...infer Tail] ? Tail : never;
+/**
+ * Transforms a function that takes a function as first argument into a decorator function.
+ *
+ * @example
+ * ```typescript
+ * function log(func: Function, message: string) {
+ *   return function (...args: unknown[]) {
+ *     console.log(message);
+ *     return func(...args);
+ *   };
+ * }
+ *
+ * const logger = toDecorator(log);
+ *
+ * class TestClass {
+ *   @logger("Hello world!")
+ *   testMethod() {
+ *     return 1;
+ *   }
+ * }
+ *
+ * const instance = new TestClass();
+ * instance.testMethod();
+ * // => Log "Hello World" and return 1
+ * ```
+ * @param func - The function to transform.
+ * @returns A decorator function that can be used to decorate a method.
+ */
+declare function toDecorator<TFunc extends GenericFunction<TFunc>>(func: TFunc): (...args: Tail<Parameters<TFunc>>) => (target: unknown, key: string, descriptor: PropertyDescriptor) => void;
+
+/**
+ * Creates a debounced version of a function. Only calling it after a specified amount of time has passed without any new calls.
+ *
+ * ----
+ *
+ * **Methods:**
+ * - `cancel` will cancel the next invocation of the debounced function.
+ * - `flush` will immediately invoke the debounced function and cancel any pending invocations.
+ *
+ * This function can be used as a decorator with {@link decDebounce}.
+ *
+ * @example
+ * const sayHello = (name: string) => console.log(`Hello, ${name}!`);
+ * const debouncedSayHello = debounce(sayHello, 1000);
+ *
+ * debouncedSayHello("John");
+ * debouncedSayHello("Jane");
+ * // => Only the second invocation of `debouncedSayHello` is executed, after a delay of 1000ms.
+ * @param func - The function to debounce.
+ * @param wait - The number of milliseconds to wait before invoking `func`.
+ * @returns A debounced version of `func` with `cancel` and `flush` methods.
+ */
+declare function debounce<TFunc extends GenericFunction<TFunc>>(func: TFunc, wait: number): TFunc & {
+    cancel: () => void;
+    flush: () => void;
+};
+
+/**
+ * Creates a function that invokes the given function as long as it's called `<= n` times.
+ *
+ * Subsequent calls to the created function return the result of the last `func` invocation.
+ *
+ * This function can be used as a decorator with {@link decMaxCalls}.
+ * @example
+ * let count = 0;
+ * const addCount = () => ++count;
+ *
+ * // Allow addCount to be invoked twice.
+ * const limitAddCount = maxCalls(addCount, 2)
+ *
+ * limitAddCount() // => 1
+ * limitAddCount() // => 2
+ * limitAddCount() // => 2
+ * // => `limitAddCount` is invoked twice and the result is cached.
+ * @param n - The number of calls before the cached result is returned.
+ * @param func - The function to restrict.
+ * @returns Returns the new restricted function.
+ */
+declare function maxCalls<TFunc extends GenericFunction<TFunc>>(func: TFunc, n: number): TFunc;
+
+/**
+ * Creates a function that invokes the given function once it's called more than `n` times.
+ * Returns undefined until the minimum call count is reached.
+ *
+ * This function can be used as a decorator with {@link decMinCalls}.
+ * @example
+ * const caution = () => console.log("Caution!");
+ * const minCalls = after(caution, 2);
+ *
+ * minCalls()
+ * minCalls()
+ * minCalls()
+ * // => `caution` is invoked on the third call.
+ * @param n The number of calls before the given function is invoked.
+ * @param func The function to restrict.
+ * @returns Returns the new restricted function.
+ */
+declare function minCalls<TFunc extends GenericFunction<TFunc>>(func: TFunc, n: number): (this: unknown, ...args: Parameters<TFunc>) => ReturnType<TFunc> | undefined;
+
+/**
+ * Generates a function that invokes the given function at most once per every `wait` milliseconds.
+ *
+ * This function can be used as a decorator with {@link decThrottle}.
+ * @example
+ * const throttled = throttle(() => console.log("Throttled!"), 1000);
+ *
+ * throttled();
+ * throttled();
+ * // => "Throttled!" is logged once per second.
+ * @param func - The function to throttle.
+ * @param wait - The number of milliseconds to throttle invocations to.
+ * @returns Returns the new throttled function.
+ */
+declare function throttle<TFunc extends GenericFunction<TFunc>>(func: TFunc, wait: number): TFunc;
 
 /**
  * Invokes a function `n` times, returning an array of the results of
@@ -922,4 +1049,4 @@ declare function isPlainObject(value: unknown): value is PlainObject$1;
  */
 declare function isUrl(str: string): boolean;
 
-export { PlainObject, Queue, camelCase, capitalize, chunk, count, debounce, deburr, decMaxCalls, decMinCalls, difference, dropRightWhile, dropWhile, escapeHtml, escapeRegExp, group, intersection, isEmpty, isEqual, isPlainObject, isUrl, kebabCase, maxCalls, memoize, merge, minCalls, omit, pascalCase, pick, races, retry, sample, set, shuffle, sleep, snakeCase, sort, startCase, stripSpecial, takeRightWhile, takeWhile, throttle, timeout, times, toDecorator, unescapeHtml, unique };
+export { PlainObject, Queue, camelCase, capitalize, chunk, count, debounce, deburr, decDebounce, decMaxCalls, decMemoize, decMinCalls, decThrottle, difference, dropRightWhile, dropWhile, escapeHtml, escapeRegExp, group, intersection, isEmpty, isEqual, isPlainObject, isUrl, kebabCase, maxCalls, memoize, merge, minCalls, omit, pascalCase, pick, races, retry, sample, set, shuffle, sleep, snakeCase, sort, startCase, stripSpecial, takeRightWhile, takeWhile, throttle, timeout, times, toDecorator, unescapeHtml, unique };

package/dist/index.js

@@ -223,94 +223,31 @@ function toDecorator(func) {
 }
 
 // src/function/debounce.ts
-function debounce(fn, wait = 0, options = {}) {
-  let lastArgs;
-  let lastThis;
-  let result;
-  let timerId;
-  let lastCallTime;
-  let lastInvokeTime = 0;
-  const maxing = options.maxWait ?? false;
-  const leading = options.leading ?? false;
-  const trailing = options.trailing ?? true;
-  const maxWait = options.maxWait ?? 0;
-  function invokeFunc(time) {
-    const args = lastArgs;
-    const thisArg = lastThis;
-    lastArgs = lastThis = void 0;
-    lastInvokeTime = time;
-    result = fn.apply(thisArg, args);
-    return result;
-  }
-  function leadingEdge(time) {
-    lastInvokeTime = time;
-    timerId = setTimeout(timerExpired, wait);
-    return leading ? invokeFunc(time) : result;
-  }
-  function remainingWait(time) {
-    const timeSinceLastCall = time - lastCallTime;
-    const timeSinceLastInvoke = time - lastInvokeTime;
-    const timeWaiting = wait - timeSinceLastCall;
-    return maxing ? Math.min(timeWaiting, maxWait - timeSinceLastInvoke) : timeWaiting;
-  }
-  function shouldInvoke(time) {
-    if (lastCallTime === void 0)
-      return true;
-    const timeSinceLastCall = time - lastCallTime;
-    const timeSinceLastInvoke = time - lastInvokeTime;
-    return timeSinceLastCall >= wait || timeSinceLastCall < 0 || maxing && timeSinceLastInvoke >= maxWait;
-  }
-  function timerExpired() {
-    const time = Date.now();
-    if (shouldInvoke(time)) {
-      return trailingEdge(time);
-    }
-    timerId = setTimeout(timerExpired, remainingWait(time));
-  }
-  function trailingEdge(time) {
-    timerId = void 0;
-    if (trailing && lastArgs) {
-      return invokeFunc(time);
-    }
-    lastArgs = lastThis = void 0;
-    return result;
-  }
-  function cancel() {
-    if (timerId !== void 0) {
-      clearTimeout(timerId);
-    }
-    lastInvokeTime = 0;
-    lastArgs = lastCallTime = lastThis = timerId = void 0;
-  }
-  function flush() {
-    return timerId === void 0 ? result : trailingEdge(Date.now());
-  }
-  function debounced(...args) {
-    const time = Date.now();
-    const isInvoking = shouldInvoke(time);
-    lastArgs = args;
-    lastThis = this;
-    lastCallTime = time;
-    if (isInvoking) {
-      if (timerId === void 0) {
-        return leadingEdge(lastCallTime);
-      }
-      if (maxing) {
-        clearTimeout(timerId);
-        timerId = setTimeout(timerExpired, wait);
-        return invokeFunc(lastCallTime);
-      }
-    }
-    if (timerId === void 0) {
-      timerId = setTimeout(timerExpired, wait);
+function debounce(func, wait) {
+  let timeoutId;
+  const debounced = function(...args) {
+    clearTimeout(timeoutId);
+    timeoutId = setTimeout(() => func.apply(this, args), wait);
+  };
+  debounced.cancel = function() {
+    clearTimeout(timeoutId);
+    timeoutId = void 0;
+  };
+  debounced.flush = function(...args) {
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+      timeoutId = void 0;
     }
-    return result;
-  }
-  debounced.cancel = cancel;
-  debounced.flush = flush;
+    func.apply(this, args);
+  };
   return debounced;
 }
 
+// src/decorator/decDebounce.ts
+function decDebounce(wait) {
+  return toDecorator(debounce)(wait);
+}
+
 // src/function/maxCalls.ts
 function maxCalls(func, n) {
   let count2 = 0;
@@ -323,25 +260,39 @@ function maxCalls(func, n) {
     return result;
   };
 }
-var decMaxCalls = toDecorator(maxCalls);
+
+// src/decorator/decMaxCalls.ts
+function decMaxCalls(n) {
+  return toDecorator(maxCalls)(n);
+}
 
 // src/function/memoize.ts
 var defaultResolver = (...args) => JSON.stringify(args);
-function memoize(func, resolver = defaultResolver) {
+function memoize(func, options = {}) {
+  const resolver = options.resolver ?? defaultResolver;
+  const ttl = options.ttl;
   const cache = /* @__PURE__ */ new Map();
   const memoizedFunc = function(...args) {
     const key = resolver(...args);
     if (cache.has(key)) {
-      return cache.get(key);
+      const [cacheResult, cacheTime] = cache.get(key);
+      if (ttl === void 0 || Date.now() - cacheTime < ttl) {
+        return cacheResult;
+      }
     }
     const result = func.apply(this, args);
-    cache.set(key, result);
+    cache.set(key, [result, Date.now()]);
     return result;
   };
   memoizedFunc.cache = cache;
   return memoizedFunc;
 }
 
+// src/decorator/decMemonize.ts
+function decMemoize(options = {}) {
+  return toDecorator(memoize)(options);
+}
+
 // src/function/minCalls.ts
 function minCalls(func, n) {
   let count2 = 1;
@@ -352,15 +303,27 @@ function minCalls(func, n) {
     count2 += 1;
   };
 }
-var decMinCalls = toDecorator(minCalls);
+
+// src/decorator/decMinCalls.ts
+function decMinCalls(n) {
+  return toDecorator(minCalls)(n);
+}
 
 // src/function/throttle.ts
-function throttle(func, wait = 0, options = {}) {
-  return debounce(func, wait, {
-    leading: options.leading ?? true,
-    maxWait: wait,
-    trailing: options.trailing ?? true
-  });
+function throttle(func, wait) {
+  let inThrottle = false;
+  return function(...args) {
+    if (!inThrottle) {
+      func.apply(this, args);
+      inThrottle = true;
+      setTimeout(() => inThrottle = false, wait);
+    }
+  };
+}
+
+// src/decorator/decThrottle.ts
+function decThrottle(wait) {
+  return toDecorator(throttle)(wait);
 }
 
 // src/function/times.ts
@@ -684,8 +647,11 @@ export {
   count,
   debounce,
   deburr,
+  decDebounce,
   decMaxCalls,
+  decMemoize,
   decMinCalls,
+  decThrottle,
   difference,
   dropRightWhile,
   dropWhile,