moderndash - npm Package Compare versions

Comparing version 0.8.0 to 0.9.0

dist/index.d.ts

@@ -44,3 +44,3 @@ /**
  */
-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>;
@@ -264,2 +264,132 @@
 
+/**
+ * Debouces the decorated function. Only calling it after a specified amount of time has passed without any new calls.
+ *
+ * Look at {@link debounce} for the non-decorator version.
+ *
+ * *Requires TypeScript >=5.0 or `experimentalDecorators` flag enabled.*
+ *
+ * @example
+ * class TestClass {
+ *   @decDebounce(1000)
+ *   testMethod(str: string) {
+ *     console.log("Debounced:", str);
+ *   }
+ * }
+ *
+ * const instance = new TestClass();
+ * 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 const decDebounce: (wait: number) => (target: unknown, key: string, descriptor: PropertyDescriptor) => void;
+
+/**
+ * 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.
+ *
+ * Look at {@link maxCalls} for the non-decorator version.
+ *
+ * *Requires TypeScript >=5.0 or `experimentalDecorators` flag enabled.*
+ *
+ * @example
+ * class TestClass {
+ *  private count = 0;
+ *  @decMaxCalls(2)
+ *  testMethod() {
+ *    return ++this.count;
+ *  }
+ * }
+ * const instance = new TestClass();
+ * 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;
+
+/**
+ * Memoizes the decorated function.
+ * The cache key is either determined by the provided resolver or by the arguments used in the memoized function.
+ *
+ * **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.
+ *
+ * Look at {@link memoize} for the non-decorator version.
+ *
+ * *Requires TypeScript >=5.0 or `experimentalDecorators` flag enabled.*
+ *
+ * @example
+ * 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 const decMemoize: (options?: {
+    resolver?: ((...args: unknown[]) => string | symbol) | undefined;
+    ttl?: number | undefined;
+} | undefined) => (target: unknown, key: string, descriptor: PropertyDescriptor) => void;
+
+/**
+ * Only invokes the decorated function after it's called more than `n` times.
+ *
+ * Look at {@link minCalls} for the non-decorator version.
+ *
+ * *Requires TypeScript >=5.0 or `experimentalDecorators` flag enabled.*
+ * @example
+ * class TestClass {
+ *   @decAfter(2)
+ *   testMethod() {
+ *     return 1;
+ *   }
+ * }
+ * const instance = new TestClass();
+ * instance.testMethod(); // => undefined
+ * instance.testMethod(); // => undefined
+ * instance.testMethod(); // => 1
+ *
+ * @param n The number of calls before the decorated function is invoked.
+ */
+declare const decMinCalls: (n: number) => (target: unknown, key: string, descriptor: PropertyDescriptor) => void;
+
+/**
+ * The decorated function is invoked at most once per every `wait` milliseconds.
+ *
+ * Look at {@link throttle} for the non-decorator version.
+ *
+ * *Requires TypeScript >=5.0 or `experimentalDecorators` flag enabled.*
+ *
+ * @example
+ * 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 decThrottle: (wait: number) => (target: unknown, key: string, descriptor: PropertyDescriptor) => void;
+
 type Tail<T extends unknown[]> = T extends [infer _Head, ...infer Tail] ? Tail : never;
@@ -295,7 +425,28 @@ /**
 
-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 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;
+};
 
@@ -313,3 +464,3 @@ /**
  * // Allow addCount to be invoked twice.
- * const limitAddCount = maxCalls(2, addCount)
+ * const limitAddCount = maxCalls(addCount, 2)
  *
@@ -325,41 +476,21 @@ * limitAddCount() // => 1
 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.
+ * Creates a function that memoizes the result of `func`.
+ * The cache key is either determined by the provided resolver or by the arguments used in the memoized function.
  *
- * Look at {@link maxCalls} for the non-decorator version.
+ * 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.
  *
- * *Requires TypeScript >=5.0 or `experimentalDecorators` flag enabled.*
+ * **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.
  *
- * @example
- * class TestClass {
- *  private count = 0;
- *  @decMaxCalls(2)
- *  testMethod() {
- *    return ++this.count;
- *  }
- * }
- * const instance = new TestClass();
- * instance.testMethod(); // => 1
- * instance.testMethod(); // => 2
- * instance.testMethod(); // => 2
+ * This function can be used as a decorator with {@link decMemoize}.
  *
- */
-declare const 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 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`.
- *
  * @example
  * const object = { 'a': 1, 'b': 2 }
  *
- * const values = memoize(values)
+ * const values = memoize(Object.values, { ttl: 1000 })
  * values(object)
@@ -371,18 +502,20 @@ * // => [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 = 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;
@@ -408,30 +541,20 @@ };
  */
-declare function minCalls<TFunc extends GenericFunction<TFunc>>(func: TFunc, n: number): (this: ThisParameterType<TFunc>, ...args: Parameters<TFunc>) => ReturnType<TFunc> | undefined;
+declare function minCalls<TFunc extends GenericFunction<TFunc>>(func: TFunc, n: number): (this: unknown, ...args: Parameters<TFunc>) => ReturnType<TFunc> | undefined;
+
 /**
- * Only invokes the decorated function after it's called more than `n` times.
+ * Generates a function that invokes the given function at most once per every `wait` milliseconds.
  *
- * Look at {@link minCalls} for the non-decorator version.
- *
- * *Requires TypeScript >=5.0 or `experimentalDecorators` flag enabled.*
+ * This function can be used as a decorator with {@link decThrottle}.
  * @example
- * class TestClass {
- *   @decAfter(2)
- *   testMethod() {
- *     return 1;
- *   }
- * }
- * const instance = new TestClass();
- * instance.testMethod(); // => undefined
- * instance.testMethod(); // => undefined
- * instance.testMethod(); // => 1
+ * const throttled = throttle(() => console.log("Throttled!"), 1000);
  *
- * @param runAfter The number of calls before the decorated function is invoked.
+ * 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 const decMinCalls: (n: number) => (target: unknown, key: string, descriptor: PropertyDescriptor) => void;
+declare function throttle<TFunc extends GenericFunction<TFunc>>(func: TFunc, wait: number): TFunc;
 
-declare function throttle<TFunc extends GenericFunction<TFunc>>(func: TFunc, wait?: number, options?: {
-    leading?: boolean;
-    trailing?: boolean;
-}): (this: ThisParameterType<TFunc>, ...args: Parameters<TFunc>) => ReturnType<TFunc>;
-
 /**
@@ -932,2 +1055,2 @@ * Invokes a function `n` times, returning an array of the results of
 
-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 };

dist/index.js

@@ -226,90 +226,25 @@ // src/array/chunk.ts
 // 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);
+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;
     }
-    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);
-    }
-    return result;
-  }
-  debounced.cancel = cancel;
-  debounced.flush = flush;
+    func.apply(this, args);
+  };
   return debounced;
 }
 
+// src/decorator/decDebounce.ts
+var decDebounce = toDecorator(debounce);
+
 // src/function/maxCalls.ts
@@ -327,2 +262,4 @@ function maxCalls(func, n) {
 }
+
+// src/decorator/decMaxCalls.ts
 var decMaxCalls = toDecorator(maxCalls);
@@ -332,3 +269,5 @@
 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();
@@ -338,6 +277,9 @@ const memoizedFunc = function(...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;
@@ -349,2 +291,5 @@ };
 
+// src/decorator/decMemonize.ts
+var decMemoize = toDecorator(memoize);
+
 // src/function/minCalls.ts
@@ -360,13 +305,21 @@ function minCalls(func, n) {
 }
+
+// src/decorator/decMinCalls.ts
 var decMinCalls = toDecorator(minCalls);
 
 // 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
+var decThrottle = toDecorator(throttle);
+
 // src/function/times.ts
@@ -693,4 +646,7 @@ function times(func, n) {
   deburr,
+  decDebounce,
   decMaxCalls,
+  decMemoize,
   decMinCalls,
+  decThrottle,
   difference,
@@ -697,0 +653,0 @@ dropRightWhile,

package.json

@@ -51,3 +51,3 @@ {
   },
-  "version": "0.8.0"
+  "version": "0.9.0"
 }

No alert changes

Improved metrics

Total package byte prevSize

206328

increased by1.82%

Lines of code

2337

increased by0.99%

No dependency changes