kontroll 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 NamesMT <https://github.com/namesmt>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,72 @@
+# kontroll [![NPM version](https://img.shields.io/npm/v/kontroll?color=a1b858&label=)](https://www.npmjs.com/package/kontroll)
+
+**kontroll** ("control") is a small, 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.
+- **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.
+
+## Usage
+### Install package:
+```sh
+# npm
+npm install kontroll
+
+# yarn
+yarn add kontroll
+
+# pnpm (recommended)
+pnpm install kontroll
+```
+
+### Import:
+```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,
+  throttle,
+} from 'kontroll'
+
+const doSum = (...numbers) => console.log(numbers.reduce((acc, cur) => acc + cur, 0))
+const makeDoSum = (...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 })
+```
+
+## **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:
+```js
+// * 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, input could be changed.
+debounce(1000, makeDoSum(2, 3))
+```
+multiple times,  
+The callback are properly debounced, because they have the same callback body.
+
+But be noticed, 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.  
+In you wish them to have the same timer, you can manually set `options.key` like: `debounce(1000, () => {}, { key: 'KEY' })`
+
+## License
+
+[MIT](./LICENSE) License © 2023 [NamesMT](https://github.com/NamesMT)

package/dist/index.d.mts

@@ -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/dist/index.mjs

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

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "kontroll",
+  "type": "module",
+  "version": "0.1.0",
+  "packageManager": "pnpm@8.12.0",
+  "description": "",
+  "author": "NamesMT <dangquoctrung123@gmail.com>",
+  "license": "MIT",
+  "funding": "https://github.com/sponsors/namesmt",
+  "homepage": "https://github.com/namesmt/kontroll#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/namesmt/kontroll.git"
+  },
+  "bugs": "https://github.com/namesmt/kontroll/issues",
+  "keywords": [],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "source": "./src/index.ts",
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "start": "NODE_ENV=dev tsx src/index.ts",
+    "watch": "NODE_ENV=dev tsx watch src/index.ts",
+    "stub": "unbuild --stub",
+    "dev": "pnpm run watch",
+    "play": "pnpm run stub && pnpm run --filter playground dev",
+    "play:useBuild": "pnpm run build && pnpm run --filter playground dev",
+    "lint": "eslint .",
+    "test": "vitest",
+    "test:types": "tsc --noEmit --skipLibCheck",
+    "check": "pnpm lint && pnpm test:types && vitest run --coverage",
+    "build": "unbuild",
+    "release": "pnpm dlx changelogen@latest --release --push --publish",
+    "prepare": "simple-git-hooks",
+    "prepublishOnly": "pnpm run build"
+  },
+  "dependencies": {
+    "consola": "^3.2.3",
+    "std-env": "^3.6.0"
+  },
+  "devDependencies": {
+    "@antfu/eslint-config": "^2.4.4",
+    "@types/node": "^20.10.4",
+    "@unocss/eslint-plugin": "^0.58.0",
+    "@vitest/coverage-v8": "^1.0.4",
+    "eslint": "^8.55.0",
+    "lint-staged": "^15.2.0",
+    "simple-git-hooks": "^2.9.0",
+    "tsx": "^4.6.2",
+    "typescript": "^5.3.3",
+    "unbuild": "^2.0.0",
+    "vitest": "^1.0.4"
+  },
+  "pnpm": {
+    "overrides": {
+      "hasown": "npm:@nolyfill/hasown@latest"
+    }
+  },
+  "simple-git-hooks": {
+    "pre-commit": "pnpm lint-staged"
+  },
+  "lint-staged": {
+    "*": "eslint --fix"
+  }
+}