feat: add useRefDebounced (#579)

* feat: add `useRefDebounced`

* chore: export file

* chore: add tests and docs

* chore: rename to refDebounced

Author: pikax

docs/.vuepress/config.js

@@ -147,6 +147,7 @@ module.exports = {
             ["composable/misc/vmodel", "vModel"],
             ["composable/misc/injectFactory", "injectFactory"],
             ["composable/misc/lockScroll", "lockScroll"],
+            ["composable/misc/refDebounced", "refDebounced"],
           ],
         },
         {

docs/README.md

@@ -82,6 +82,7 @@ Check out the [examples folder](examples) or start hacking on [codesandbox](http
 - [injectFactory](composable/misc/injectFactory) - same as [inject](https://vue-composition-api-rfc.netlify.app/api.html#dependency-injection) but allows you to have a factory as default value
 - [interval](composable/misc/interval) - self-remove `setInterval` on unmount
 - [lockScroll](composable/misc/lockScroll) - `lock-scroll` component
+- [refDebounced](composable/misc/refDebounced) - debounces the update value of a `ref`
 
 ### Storage
 

docs/composable/misc/refDebounced.md

@@ -0,0 +1,31 @@
+# refDebounced
+
+> debounces the update value of a `ref`
+
+## Parameters
+
+```js
+import { refDebounced } from "vue-composable";
+
+refDebounced(delay);
+refDebounced(value, delay);
+```
+
+| Parameters | Type     | Required | Default     | Description    |
+| ---------- | -------- | -------- | ----------- | -------------- |
+| `delay`    | `number` | `true`   |             | debounce delay |
+| `value`    | `T`      | `false`  | `undefined` | initial value  |
+
+## State
+
+The `refDebounced` function retuns a `ref`:
+
+```js
+import { refDebounced } from "vue-composable";
+
+const debouncedValue = refDebounced();
+```
+
+| State          | Type     | Description     |
+| -------------- | -------- | --------------- |
+| debouncedValue | `Ref<T>` | debounced `ref` |

packages/vue-composable/README.md

@@ -81,6 +81,7 @@ Check our [documentation](https://pikax.me/vue-composable/)
 - [injectFactory](https://pikax.me/vue-composable/composable/misc/injectFactory) - same as [inject](https://vue-composition-api-rfc.netlify.app/api.html#dependency-injection) but allows you to have a factory as default value
 - [interval](https://pikax.me/vue-composable/composable/misc/interval) - self-remove `setInterval` on unmount
 - [lockScroll](https://pikax.me/vue-composable/composable/misc/lockScroll) - `lock-scroll` component
+- [refDebounced](https://pikax.me/vue-composable/composable/misc/refDebounced) - debounces the update value of a `ref`
 
 ### Storage
 

packages/vue-composable/__tests__/misc/refDebounced.spec.ts

@@ -0,0 +1,36 @@
+import { refDebounced } from "../../src";
+
+describe("refDebounced", () => {
+  beforeAll(() => {
+    jest.useFakeTimers();
+  });
+  afterAll(() => {
+    jest.useRealTimers();
+  });
+  it("should work", () => {
+    const r = refDebounced("a", 1);
+
+    expect(r.value).toBe("a");
+
+    r.value = "b";
+
+    // should not been updated yet
+    expect(r.value).toBe("a");
+
+    jest.runTimersToTime(2);
+    expect(r.value).toBe("b");
+  });
+
+  it("should allow use only a delay", () => {
+    const r = refDebounced(1);
+    expect(r.value).toBe(undefined);
+
+    r.value = 1;
+
+    // should not been updated yet
+    expect(r.value).toBe(undefined);
+
+    jest.runTimersToTime(2);
+    expect(r.value).toBe(1);
+  });
+});

packages/vue-composable/src/api.2.ts

@@ -21,6 +21,7 @@ export {
   ComputedRef,
   toRaw,
   UnwrapRef, // Plugin,
+  customRef,
 } from "@vue/composition-api";
 export { VueConstructor as App } from "vue";
 

packages/vue-composable/src/api.3.ts

@@ -25,6 +25,7 @@ export {
   readonly,
   toRaw,
   DeepReadonly,
+  customRef,
 } from "@vue/runtime-core";
 
 // istanbul ignore next

packages/vue-composable/src/api.ts

@@ -25,6 +25,7 @@ export {
   readonly,
   toRaw,
   DeepReadonly,
+  customRef,
 } from "@vue/runtime-core";
 
 // istanbul ignore next

packages/vue-composable/src/misc/index.ts

@@ -4,3 +4,4 @@ export * from "./lockScroll";
 export * from "./vmodel";
 export * from "./injectFactory";
 export * from "./interval";
+export * from "./refDebounced";

packages/vue-composable/src/misc/refDebounced.ts

@@ -0,0 +1,22 @@
+import { Ref, customRef } from "../api";
+import { debounce } from "../debounce";
+import { isNumber } from "../utils";
+
+export function refDebounced<T>(delay: number): Ref<T | undefined>;
+export function refDebounced<T>(value: T, delay: number): Ref<T | undefined>;
+export function refDebounced<T>(value: T | number, delay?: number): Ref<T> {
+  let [v, d] =
+    arguments.length === 1 && isNumber(value)
+      ? [undefined, value]
+      : [value, delay];
+  return customRef<T>((track, trigger) => ({
+    get() {
+      track();
+      return v as any;
+    },
+    set: debounce((val) => {
+      v = val;
+      trigger();
+    }, d),
+  }));
+}

readme.md

@@ -81,6 +81,7 @@ Check our [documentation](https://pikax.me/vue-composable/)
 - [injectFactory](https://pikax.me/vue-composable/composable/misc/injectFactory) - same as [inject](https://vue-composition-api-rfc.netlify.app/api.html#dependency-injection) but allows you to have a factory as default value
 - [interval](https://pikax.me/vue-composable/composable/misc/interval) - self-remove `setInterval` on unmount
 - [lockScroll](https://pikax.me/vue-composable/composable/misc/lockScroll) - `lock-scroll` component
+- [refDebounced](https://pikax.me/vue-composable/composable/misc/refDebounced) - debounces the update value of a `ref`
 
 ### Storage