kontroll 1.0.4 → 1.1.0

package/README.md

@@ -9,6 +9,7 @@
 **kontroll** ("control") is a tiny, dead-simple package for function behavior controls like debounce, countdown, throttle (limit).
 
 ## Features
+
 - **100% coverage!**
 - **Self-explained**: for real, every functions and options have TSDoc comments to explain their behavior plus examples at a **hover** *(based on your IDE)*, apart from the already intuitive logic path.
   - [![jsDocs.io][jsDocs-src]][jsDocs-href]
@@ -16,6 +17,7 @@
 - **Promise aware**: avoid duplicated call if your promise haven't settled.
 
 ## Usage
+
 ### Install package:
 ```sh
 # npm
@@ -28,52 +30,61 @@ yarn add kontroll
 pnpm install kontroll
 ```
 
-### Import:
+### Import and use:
+
 ```js
 // This package exports ESM only.
 import {
   clear,
   countdown, // Can be understand as throttle no leading (execute at end of throttle instead of lead)
   debounce,
+  getInstance,
   throttle,
 } from 'kontroll'
 
 const doSum = (...numbers) => console.log(numbers.reduce((acc, cur) => acc + cur, 0))
-const makeDoSum = (...numbers) => () => doSum(numbers)
+const createDoSum = (...numbers) => () => doSum(numbers)
 
-const clearCountdown = countdown(1000, makeDoSum(1, 2), { key: 'defined', replace: false })
-const clearDebounce = debounce(1000, makeDoSum(3, 4), { key: 34, leading: false })
-const resetThrottle = throttle(1000, makeDoSum(5, 6), { trailing: false })
+const clearCountdown = countdown(1000, createDoSum(1, 2), { key: 'defined', replace: false })
+const clearDebounce = debounce(1000, createDoSum(3, 4), { key: 34, leading: false })
+const resetThrottle = throttle(1000, createDoSum(5, 6), { trailing: false })
+
+const debounceInstance = getInstance(34) // { timer: Timeout, callback: <fn>, finishing: false }
 ```
 
 ## **Notice**
+
 ### `key` behavior
+
 Kontroll follows a key-first strategy, as long as things share the same key, they share the same timer.
 
 If a `options.key` is not present, key are taken as `callback.toString()`.
 
-<!-- Explaining the basic for sleep derived beginner :> -->
-If you call something like:
+*While `kontroll` supports a key-less usage, its recommended to set your key for production code, for better performance and expected behavior.*
+
+The following cases are debounced as their callback body is the same:
 ```js
-// // * Case 1, (arrow) function with unchanged/variable-only body
+// * Case 1, (arrow) function with unchanged/variable-only body
 debounce(1000, () => console.log(variable))
 
-// // * Case 2, declared function
-debounce(1000, makeDoSum(1, 2))
-// For declared function, it's parameter could be changed and still share the same key.
-debounce(1000, makeDoSum(2, 3))
+// * Case 2, callback / function returned by a function
+const sumOneTwo = createDoSum(1, 2)
+debounce(1000, sumOneTwo) // All this
+debounce(1000, createDoSum(3, 4)) // 3 lines are
+debounce(1000, createDoSum(5, 6)) // same key
 ```
-multiple times,  
-The callback are properly debounced, because they have the same callback body.
 
-But be noticed, for something like:
+Be notice, for something like
 ```js
 debounce(1000, () => console.log('hi'))
 debounce(1000, () => console.log('hello'))
 ```
-The automated key are different for the two calls (because they have different callback body), so they are timed separately.  
+The automated key are different for the two calls (because they have different callback body), so they are timed separately.
+
 In you wish them to have the same timer, you can manually set `options.key` like: `debounce(1000, () => {}, { key: 'KEY' })`
 
+Note: the storage to check the key is set globally, if you use `kontroll` in your library, you should prefix the key with your package name.
+
 ## License
 
 [MIT](./LICENSE) License © 2024 [NamesMT](https://github.com/NamesMT)

package/dist/index.d.mts

@@ -1,15 +1,32 @@
 type Fn<T = void> = () => T;
 type FnWithArgs<T = void> = (...args: any) => T;
 interface KontrollStore {
-    [x: PropertyKey]: {
-        timer: ReturnType<typeof setTimeout>;
-        callback: Fn<any | Promise<any>>;
-        trailing?: [FnWithArgs, ...any];
-        finishing?: boolean;
-    };
+    [x: PropertyKey]: KontrollInstance;
+}
+interface KontrollInstance {
+    timer: ReturnType<typeof setTimeout>;
+    callback: Fn<any | Promise<any>>;
+    trailing?: [FnWithArgs, ...any];
+    finishing?: boolean;
 }
 declare function clear(callback: Fn): void;
 declare function clear(key: keyof KontrollStore): void;
+/**
+ * Returns the {@link KontrollInstance} for the given key, if exists.
+ *
+ * Could be useful to check if a promise is executing and not settled.
+ *
+ * ---
+ *
+ * Example
+ * ```
+ * debounce(1, async => await sleep(1000), { key: '1sec' })
+ * // 500ms passed
+ * getInstance('1sec')
+ * // Result: `KontrollInstance` ({ timer: Timeout, callback: <fn>, finishing: true })
+ * ```
+ */
+declare function getInstance(key: keyof KontrollStore): KontrollInstance | undefined;
 type KontrollClearer = Fn;
 interface KontrollBaseOptions {
     /**
@@ -138,5 +155,5 @@ interface KontrollThrottleOptions extends KontrollBaseOptions {
  */
 declare function throttle(ms: number, callback: Fn, { key, trailing }?: KontrollThrottleOptions): KontrollClearer;
 
-export { clear, countdown, debounce, throttle };
-export type { KontrollBaseOptions, KontrollClearer, KontrollCountdownOptions, KontrollDebounceOptions, KontrollStore, KontrollThrottleOptions };
+export { clear, countdown, debounce, getInstance, throttle };
+export type { KontrollBaseOptions, KontrollClearer, KontrollCountdownOptions, KontrollDebounceOptions, KontrollInstance, KontrollStore, KontrollThrottleOptions };

package/dist/index.d.ts

@@ -1,15 +1,32 @@
 type Fn<T = void> = () => T;
 type FnWithArgs<T = void> = (...args: any) => T;
 interface KontrollStore {
-    [x: PropertyKey]: {
-        timer: ReturnType<typeof setTimeout>;
-        callback: Fn<any | Promise<any>>;
-        trailing?: [FnWithArgs, ...any];
-        finishing?: boolean;
-    };
+    [x: PropertyKey]: KontrollInstance;
+}
+interface KontrollInstance {
+    timer: ReturnType<typeof setTimeout>;
+    callback: Fn<any | Promise<any>>;
+    trailing?: [FnWithArgs, ...any];
+    finishing?: boolean;
 }
 declare function clear(callback: Fn): void;
 declare function clear(key: keyof KontrollStore): void;
+/**
+ * Returns the {@link KontrollInstance} for the given key, if exists.
+ *
+ * Could be useful to check if a promise is executing and not settled.
+ *
+ * ---
+ *
+ * Example
+ * ```
+ * debounce(1, async => await sleep(1000), { key: '1sec' })
+ * // 500ms passed
+ * getInstance('1sec')
+ * // Result: `KontrollInstance` ({ timer: Timeout, callback: <fn>, finishing: true })
+ * ```
+ */
+declare function getInstance(key: keyof KontrollStore): KontrollInstance | undefined;
 type KontrollClearer = Fn;
 interface KontrollBaseOptions {
     /**
@@ -138,5 +155,5 @@ interface KontrollThrottleOptions extends KontrollBaseOptions {
  */
 declare function throttle(ms: number, callback: Fn, { key, trailing }?: KontrollThrottleOptions): KontrollClearer;
 
-export { clear, countdown, debounce, throttle };
-export type { KontrollBaseOptions, KontrollClearer, KontrollCountdownOptions, KontrollDebounceOptions, KontrollStore, KontrollThrottleOptions };
+export { clear, countdown, debounce, getInstance, throttle };
+export type { KontrollBaseOptions, KontrollClearer, KontrollCountdownOptions, KontrollDebounceOptions, KontrollInstance, KontrollStore, KontrollThrottleOptions };

package/dist/index.mjs

@@ -1 +1 @@
-const e={};function c(i){const t=typeof i=="function"?i.toString():i;e[t]&&(clearTimeout(e[t].timer),delete e[t])}function u(i){return()=>{c(i)}}async function a(i){if(e[i]){e[i].finishing=!0;const t=e[i].trailing;await e[i].callback(),c(i),t&&t[0](...t.slice(1))}}function l(i,t,n){if(e[n]?.finishing)return u(n);const r=setTimeout(()=>{a(n)},i);return e[n]={timer:r,callback:t},u(n)}function g(i,t,{key:n=t.toString(),replace:r}={}){return e[n]?(r&&(e[n].callback=t),u(n)):l(i,t,n)}function s(i,t,{key:n=t.toString(),leading:r}={}){if(e[n]&&!e[n].finishing)c(n);else if(r)return f(i,t,{key:n});return l(i,t,n)}function f(i,t,{key:n=t.toString(),trailing:r}={}){return e[n]?(r&&(e[n].trailing=[f,i,t,{key:n}]),u(n)):(t(),l(i,()=>{},n))}export{c as clear,g as countdown,s as debounce,f as throttle};
+const t={};function c(n){const e=typeof n=="function"?n.toString():n;t[e]&&(clearTimeout(t[e].timer),delete t[e])}function a(n){return t[n]}function u(n){return()=>{c(n)}}async function s(n){if(t[n]){t[n].finishing=!0;const e=t[n].trailing;await t[n].callback(),c(n),e&&e[0](...e.slice(1))}}function o(n,e,i){if(t[i]?.finishing)return u(i);const r=setTimeout(()=>{s(i)},n);return t[i]={timer:r,callback:e},u(i)}function g(n,e,{key:i=e.toString(),replace:r}={}){return t[i]?(r&&(t[i].callback=e),u(i)):o(n,e,i)}function k(n,e,{key:i=e.toString(),leading:r}={}){if(t[i]&&!t[i].finishing)c(i);else if(r)return f(n,e,{key:i});return o(n,e,i)}function f(n,e,{key:i=e.toString(),trailing:r}={}){if(t[i])return r&&(t[i].trailing=[f,n,e,{key:i}]),u(i);const l=e();return o(n,()=>l,i)}export{c as clear,g as countdown,k as debounce,a as getInstance,f as throttle};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kontroll",
   "type": "module",
-  "version": "1.0.4",
+  "version": "1.1.0",
   "packageManager": "pnpm@10.8.0",
   "description": "kontroll (\"control\") is a tiny, dead-simple package for function behavior controls like debounce, countdown, throttle (limit).",
   "author": "NamesMT <dangquoctrung123@gmail.com>",