perfect-debounce 0.0.0 → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 - UnJS
+
+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,92 @@
+# perfect-debounce
+
+[![npm version][npm-version-src]][npm-version-href]
+[![npm downloads][npm-downloads-src]][npm-downloads-href]
+[![Github Actions][github-actions-src]][github-actions-href]
+[![Codecov][codecov-src]][codecov-href]
+
+> An improved debounce function with Promise support.
+
+- Well tested debounce implementation
+- Native Promise support
+- Avoid duplicate calls while promise is being resolved
+- Configurable `trailing` and `leading` behavior
+
+## Usage
+
+Install package:
+
+```sh
+# npm
+npm install perfect-debounce
+
+# yarn
+yarn install perfect-debounce
+
+# pnpm
+pnpm install perfect-debounce
+```
+
+Import:
+
+```js
+// ESM
+import { debounce } from 'perfect-debounce'
+
+// CommonJS
+const { debounce } = require('perfect-debounce')
+```
+
+Debounce function:
+
+```js
+const debounced = debounce(async () => {
+  // Some heavy stuff
+}, 25)
+```
+
+When calling `debounced`, it will wait at least for `25ms` as configured before actually calling our function. This helps to avoid multiple calls.
+
+To avoid initial wait, we can set `leading: true` option. It will cause function to be immediately called if there is no other call:
+
+```js
+const debounced = debounce(async () => {
+  // Some heavy stuff
+}, 25, { leading: true })
+```
+
+If executing async function takes longer than debounce value, duplicate calls will be still prevented a last call will happen. To disable this behavior, we can set `trailing: false` option:
+
+```js
+const debounced = debounce(async () => {
+  // Some heavy stuff
+}, 25, { trailing: false })
+```
+
+## 💻 Development
+
+- Clone this repository
+- Enable [Corepack](https://github.com/nodejs/corepack) using `corepack enable` (use `npm i -g corepack` for Node.js < 16.10)
+- Install dependencies using `yarn install`
+- Run interactive tests using `yarn dev`
+
+## License
+
+Made with 💛
+
+Based on [sindresorhus/p-debounce](https://github.com/sindresorhus/p-debounce).
+
+Published under [MIT License](./LICENSE).
+
+<!-- Badges -->
+[npm-version-src]: https://img.shields.io/npm/v/perfect-debounce?style=flat-square
+[npm-version-href]: https://npmjs.com/package/perfect-debounce
+
+[npm-downloads-src]: https://img.shields.io/npm/dm/perfect-debounce?style=flat-square
+[npm-downloads-href]: https://npmjs.com/package/perfect-debounce
+
+[github-actions-src]: https://img.shields.io/github/workflow/status/unjs/perfect-debounce/ci/main?style=flat-square
+[github-actions-href]: https://github.com/unjs/perfect-debounce/actions?query=workflow%3Aci
+
+[codecov-src]: https://img.shields.io/codecov/c/gh/unjs/perfect-debounce/main?style=flat-square
+[codecov-href]: https://codecov.io/gh/unjs/perfect-debounce

package/dist/index.cjs

@@ -0,0 +1,61 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+const DEBOUNCE_DEFAULTS = {
+  trailing: true
+};
+function debounce(fn, wait, options = {}) {
+  options = { ...DEBOUNCE_DEFAULTS, ...options };
+  if (!Number.isFinite(wait)) {
+    throw new TypeError("Expected `wait` to be a finite number");
+  }
+  let leadingValue;
+  let timeout;
+  let resolveList = [];
+  let currentPromise;
+  let trailingArgs;
+  const applyFn = async (_this, args) => {
+    currentPromise = _applyPromised(fn, _this, args);
+    currentPromise.finally(() => {
+      currentPromise = null;
+      if (options.trailing && trailingArgs && !timeout) {
+        const promise = applyFn(_this, trailingArgs);
+        trailingArgs = null;
+        return promise;
+      }
+    });
+    return currentPromise;
+  };
+  return function(...args) {
+    if (currentPromise) {
+      if (options.trailing) {
+        trailingArgs = args;
+      }
+      return currentPromise;
+    }
+    return new Promise((resolve) => {
+      const shouldCallNow = !timeout && options.leading;
+      clearTimeout(timeout);
+      timeout = setTimeout(() => {
+        timeout = null;
+        const promise = options.leading ? leadingValue : applyFn(this, args);
+        for (const _resolve of resolveList) {
+          _resolve(promise);
+        }
+        resolveList = [];
+      }, wait);
+      if (shouldCallNow) {
+        leadingValue = applyFn(this, args);
+        resolve(leadingValue);
+      } else {
+        resolveList.push(resolve);
+      }
+    });
+  };
+}
+async function _applyPromised(fn, _this, args) {
+  return await fn.apply(_this, args);
+}
+
+exports.debounce = debounce;

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+interface DebounceOptions {
+    /**
+    Call the `fn` on the [leading edge of the timeout](https://css-tricks.com/debouncing-throttling-explained-examples/#article-header-id-1).
+    Meaning immediately, instead of waiting for `wait` milliseconds.
+    @default false
+    */
+    readonly leading?: boolean;
+    /**
+    Call the `fn` on trailing edge with last used arguments. Result of call is from previous call.
+    @default false
+    */
+    readonly trailing?: boolean;
+}
+/**
+Debounce functions
+@param fn - Promise-returning/async function to debounce.
+@param wait - Milliseconds to wait before calling `fn`.
+@returns A function that delays calling `fn` until after `wait` milliseconds have elapsed since the last time it was called.
+@example
+```
+import pDebounce from 'p-debounce';
+const expensiveCall = async input => input;
+const debouncedFn = pDebounce(expensiveCall, 200);
+for (const number of [1, 2, 3]) {
+  console.log(await debouncedFn(number));
+}
+//=> 3
+//=> 3
+//=> 3
+```
+*/
+declare function debounce<ArgumentsType extends unknown[], ReturnType>(fn: (...args: ArgumentsType) => PromiseLike<ReturnType> | ReturnType, wait: number, options?: DebounceOptions): (...args: any[]) => Promise<unknown>;
+
+export { DebounceOptions, debounce };

package/dist/index.mjs

@@ -0,0 +1,57 @@
+const DEBOUNCE_DEFAULTS = {
+  trailing: true
+};
+function debounce(fn, wait, options = {}) {
+  options = { ...DEBOUNCE_DEFAULTS, ...options };
+  if (!Number.isFinite(wait)) {
+    throw new TypeError("Expected `wait` to be a finite number");
+  }
+  let leadingValue;
+  let timeout;
+  let resolveList = [];
+  let currentPromise;
+  let trailingArgs;
+  const applyFn = async (_this, args) => {
+    currentPromise = _applyPromised(fn, _this, args);
+    currentPromise.finally(() => {
+      currentPromise = null;
+      if (options.trailing && trailingArgs && !timeout) {
+        const promise = applyFn(_this, trailingArgs);
+        trailingArgs = null;
+        return promise;
+      }
+    });
+    return currentPromise;
+  };
+  return function(...args) {
+    if (currentPromise) {
+      if (options.trailing) {
+        trailingArgs = args;
+      }
+      return currentPromise;
+    }
+    return new Promise((resolve) => {
+      const shouldCallNow = !timeout && options.leading;
+      clearTimeout(timeout);
+      timeout = setTimeout(() => {
+        timeout = null;
+        const promise = options.leading ? leadingValue : applyFn(this, args);
+        for (const _resolve of resolveList) {
+          _resolve(promise);
+        }
+        resolveList = [];
+      }, wait);
+      if (shouldCallNow) {
+        leadingValue = applyFn(this, args);
+        resolve(leadingValue);
+      } else {
+        resolveList.push(resolve);
+      }
+    });
+  };
+}
+async function _applyPromised(fn, _this, args) {
+  return await fn.apply(_this, args);
+}
+
+export { debounce };

package/package.json

@@ -1,5 +1,41 @@
 {
- "name": "perfect-debounce",
- "version": "0.0.0",
- "license": "MIT"
-}
+  "name": "perfect-debounce",
+  "version": "0.0.1",
+  "description": "",
+  "repository": "unjs/perfect-debounce",
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "unbuild",
+    "dev": "vitest dev",
+    "lint": "eslint --ext .ts,.js,.mjs,.cjs .",
+    "prepack": "unbuild",
+    "release": "yarn test && standard-version && git push --follow-tags && npm publish",
+    "test": "vitest run --coverage"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@nuxtjs/eslint-config-typescript": "latest",
+    "c8": "latest",
+    "eslint": "latest",
+    "in-range": "^3.0.0",
+    "standard-version": "latest",
+    "time-span": "^5.0.0",
+    "typescript": "latest",
+    "unbuild": "latest",
+    "vitest": "latest"
+  }
+}