kontroll 0.1.2 → 0.1.4

package/README.md

@@ -11,6 +11,7 @@
 ## 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]
 - **Clearable**: you can stop pending timers by calling the returned clearer function or use the `clear(key)` function.
 - **Promise aware**: avoid duplicated call if your promise haven't settled.
 
@@ -79,13 +80,15 @@ In you wish them to have the same timer, you can manually set `options.key` like
 
 <!-- Badges -->
 
-[npm-version-src]: https://img.shields.io/npm/v/kontroll?style=flat&colorA=18181B&colorB=F0DB4F
+[npm-version-src]: https://img.shields.io/npm/v/kontroll?labelColor=18181B&color=F0DB4F
 [npm-version-href]: https://npmjs.com/package/kontroll
-[npm-downloads-src]: https://img.shields.io/npm/dm/kontroll?style=flat&colorA=18181B&colorB=F0DB4F
+[npm-downloads-src]: https://img.shields.io/npm/dm/kontroll?labelColor=18181B&color=F0DB4F
 [npm-downloads-href]: https://npmjs.com/package/kontroll
-[codecov-src]: https://img.shields.io/codecov/c/gh/namesmt/kontroll/main?style=flat&colorA=18181B&colorB=F0DB4F
+[codecov-src]: https://img.shields.io/codecov/c/gh/namesmt/kontroll/main?labelColor=18181B&color=F0DB4F
 [codecov-href]: https://codecov.io/gh/namesmt/kontroll
-[license-src]: https://img.shields.io/github/license/namesmt/kontroll.svg?style=flat&colorA=18181B&colorB=F0DB4F
+[license-src]: https://img.shields.io/github/license/namesmt/kontroll.svg?labelColor=18181B&color=F0DB4F
 [license-href]: https://github.com/namesmt/kontroll/blob/main/LICENSE
-[bundlejs-src]: https://deno.bundlejs.com/badge?q=kontroll@0.1.0&colorA=18181B&colorB=F0DB4F
-[bundlejs-href]: https://bundlejs.com/?q=klona
+[bundlejs-src]: https://img.shields.io/bundlejs/size/kontroll?labelColor=18181B&color=F0DB4F
+[bundlejs-href]: https://bundlejs.com/?q=kontroll
+[jsDocs-src]: https://img.shields.io/badge/Check_out-jsDocs.io---?labelColor=18181B&color=F0DB4F
+[jsDocs-href]: https://www.jsdocs.io/package/kontroll

package/dist/index.d.ts

@@ -0,0 +1,129 @@
+type Fn<T = void> = () => T;
+type FnWithArgs<T = void> = (...args: any) => T;
+interface KontrollStore {
+    [x: keyof any]: {
+        timer: ReturnType<typeof setTimeout>;
+        callback: Fn;
+        trailing?: [FnWithArgs, ...any];
+    };
+}
+declare function clear(callback: Fn): void;
+declare function clear(key: keyof KontrollStore): void;
+type KontrollClearer = Fn;
+interface KontrollBaseOptions {
+    /**
+     * Specify a known key if needed
+     * @default string // .toString() of the inputted callback
+     */
+    key?: keyof KontrollStore;
+}
+interface KontrollCountdownOptions extends KontrollBaseOptions {
+    /**
+     * Replaces the current timed callback
+     * @default false
+     */
+    replace?: boolean;
+}
+/**
+ * Countdown for a period of ms then execute the first/replaced callback, based on `options.replace`.
+ * Calls while the timer haven't finished are dropped.
+ * ---
+ *
+ * Example
+ * ```
+ * countdown(1000, doSum(1), { key: 'eg' })
+ * // 500ms passed
+ * countdown(1000, doSum(2))
+ * // 500ms passed
+ * // Result: 1
+ * ```
+ * ---
+ *
+ * Example with `options.replace=true`:
+ * ```
+ * countdown(1000, doSum(1))
+ * // 500ms passed
+ * countdown(1000, doSum(2), { replace: true })
+ * // 500ms passed
+ * // Result: 2
+ * ```
+ */
+declare function countdown(ms: number, callback: Fn, options?: KontrollCountdownOptions): KontrollClearer;
+interface KontrollDebounceOptions extends KontrollBaseOptions {
+    /**
+     * Avoiding initial wait for first call
+     * @default false
+     */
+    leading?: boolean;
+}
+/**
+ * Creates a timer that will execute the callback upon finish, calls while the timer haven't finished recreates the timer.
+ * If `options.leading`, execute callback immediately for initial call.
+ * ---
+ *
+ * Example:
+ * ```
+ * debounce(1000, doSum(1))
+ * // 500ms passed
+ * debounce(1000, doSum(2))
+ * // 1000ms passed
+ * // Result: 2
+ * ```
+ * ---
+ *
+ * Example with `options.leading`:
+ * ```
+ * debounce(1000, doSum(1), { leading: true })
+ * // Result: 1
+ * // 500ms passed
+ * debounce(1000, doSum(2), { leading: true }) // leading doesn't matter anymore in this timer scope
+ * // 500ms passed
+ * debounce(1000, doSum(3))
+ * // 1000ms passed
+ * // Result: 3
+ * ```
+ */
+declare function debounce(ms: number, callback: Fn, options?: KontrollDebounceOptions): KontrollClearer;
+interface KontrollThrottleOptions extends KontrollBaseOptions {
+    /**
+     * Perform additional execution with last received arguments
+     * @default false
+     */
+    trailing?: boolean;
+}
+/**
+ * Executes the callback, and bypass any subsequent calls for a period of ms.
+ * Calls while the timer haven't finished are dropped.
+ * If `options.trailing` and calls while the timer haven't finished are received,
+ * an additional execution with last received arguments is performed.
+ * ---
+ *
+ * Example:
+ * ```
+ * throttle(1000, doSum(1))
+ * // Result: 1
+ * // 500ms passed
+ * throttle(1000, doSum(2))
+ * // 9999ms passed
+ * // (Nothing)
+ * ```
+ * ---
+ *
+ * Example with `options.trailing`:
+ * ```
+ * throttle(1000, doSum(1))
+ * // Result: 1
+ * // 500ms passed
+ * throttle(1000, doSum(2), { trailing: true })
+ * // 500ms passed
+ * // Result: 2
+ * // A timer is also created, so calls after that are still dropped:
+ * throttle(1000, doSum(3))
+ * // 9999ms passed
+ * // (Nothing)
+ * ```
+ *
+ */
+declare function throttle(ms: number, callback: Fn, options?: KontrollThrottleOptions): KontrollClearer;
+
+export { type KontrollBaseOptions, type KontrollClearer, type KontrollCountdownOptions, type KontrollDebounceOptions, type KontrollStore, type KontrollThrottleOptions, clear, countdown, debounce, throttle };

package/package.json

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