feat(useTimeout): add a new composable (#740)

* feat(composable): add a new composable

* chore: update tests to use fake timers

Co-authored-by: pikax <carlos@hypermob.co.uk>

Author: jy0529

docs/.vuepress/components/timeoutExample.vue

@@ -0,0 +1,35 @@
+<template>
+  <div>
+    <p />
+    <button @click="show">Show an alert box after two seconds</button>
+    <p />
+    <button @click="cancel">Cancel alert before it happens</button>
+  </div>
+</template>
+<script>
+import { useTimeout } from "vue-composable";
+import { defineComponent, reactive } from "@vue/composition-api";
+
+export default defineComponent({
+  name: "timeout-example",
+  setup() {
+    let cancelTimeout;
+
+    function show() {
+      const { cancel } = useTimeout(() => {
+        alert("useTimeout callback invoked");
+      }, 2000);
+      cancelTimeout = cancel;
+    }
+
+    function cancel() {
+      cancelTimeout();
+    }
+
+    return {
+      show,
+      cancel,
+    };
+  },
+});
+</script>

docs/composable/web/timeout.md

@@ -0,0 +1,85 @@
+# Timeout
+
+> The [setTimeout](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout).
+
+## Parameters
+
+```js
+import { useTimeout } from "vue-composable";
+
+useTimeout(fn, delay);
+```
+
+| Parameters | Type       | Required | Default | Description                                                                                                           |
+| ---------- | ---------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
+| fn         | `Function` | `true`   |         | A function to be executed after the timer expires.                                                                    |
+| delay      | `Number`   | `false`  | `0 `    | The time, in milliseconds (thousandths of a second), the timer should wait before the specified function is executed. |
+
+## State
+
+The `useTimeout` function exposes the following reactive state:
+
+```js
+import { useTimeout } from "vue-composable";
+
+const { ready } = useTimeout(fn, delay);
+```
+
+| State | Type         | Description |
+| ----- | ------------ | ----------- | ---------------------------------------------------------------------------------------------------- |
+| ready | `Ref<Boolean | null>`      | current timeout state:<br/>&emsp;false - pending <br/>&emsp;true - called <br/>&emsp;null - canceled |
+
+## Methods
+
+The `useTimeout` function exposes the following methods:
+
+```js
+import { useTimeout } from "vue-composable";
+
+const { cancel } = useTimeout(fn, delay);
+```
+
+| Signature | Description        |
+| --------- | ------------------ |
+| `cancel`  | cancel the timeout |
+
+## Example
+
+<timeout-example s/>
+
+### Code
+
+```vue
+<template>
+  <div>
+    <p />
+    <button @click="show">Show an alert box after two seconds</button>
+    <p />
+    <button @click="cancel">Cancel alert before it happens</button>
+  </div>
+</template>
+<script>
+import { useTimeout } from "vue-composable";
+export default {
+  setup() {
+    let cancelTimeout;
+
+    function show() {
+      const { cancel } = useTimeout(() => {
+        alert("useTimeout callback invoked");
+      }, 2000);
+      cancelTimeout = cancel;
+    }
+
+    function cancel() {
+      cancelTimeout();
+    }
+
+    return {
+      show,
+      cancel,
+    };
+  },
+};
+</script>
+```

packages/vue-composable/__tests__/web/timeout.spec.ts

@@ -0,0 +1,80 @@
+import { useTimeout } from "../../src";
+import { createVue } from "../utils";
+import { Ref, ref } from "../../src/api";
+
+describe("timeout", () => {
+  jest.useFakeTimers();
+  it("should be defined", () => {
+    expect(useTimeout).toBeDefined();
+  });
+
+  it("should call passed function after given amount of time", async () => {
+    let count = 0;
+    useTimeout(() => {
+      count++;
+    }, 1000);
+
+    expect(count).toBe(0);
+    jest.advanceTimersByTime(900);
+    // should not be resolved
+    expect(count).toBe(0);
+
+    jest.advanceTimersByTime(100);
+    expect(count).toBe(1);
+  });
+
+  it("should set ready true after run callback", async () => {
+    const { ready } = useTimeout(() => {}, 1000);
+
+    expect(ready.value).toBe(false);
+    jest.advanceTimersByTime(1000);
+    expect(ready.value).toBe(true);
+  });
+
+  it("should cancel function call when call cancel function", async () => {
+    let count = 0;
+    const { ready, cancel } = useTimeout(() => {
+      count++;
+    }, 1000);
+
+    expect(ready.value).toBe(false);
+    expect(count).toBe(0);
+
+    cancel();
+
+    jest.advanceTimersByTime(1000);
+    expect(ready.value).toBe(null);
+    expect(count).toBe(0);
+  });
+
+  it("should cancel on unMounted", async () => {
+    let ready: Ref<boolean | null> = ref(false);
+
+    const { mount, destroy } = createVue({
+      template: `<div></div>`,
+      setup() {
+        ready = useTimeout(() => {}, 1000).ready;
+      },
+    });
+
+    mount();
+
+    expect(ready.value).toBe(false);
+    jest.advanceTimersByTime(500);
+    expect(ready.value).toBe(false);
+
+    destroy();
+    expect(ready.value).toBe(null);
+  });
+
+  it("should default the delay to 0", () => {
+    let count = 0;
+    useTimeout(() => {
+      count++;
+    });
+
+    expect(count).toBe(0);
+    jest.runOnlyPendingTimers();
+    expect(count).toBe(1);
+  });
+});

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

@@ -11,4 +11,5 @@ export * from "./cssVariables";
 export * from "./worker";
 export * from "./share";
 export * from "./clipboard";
+export * from "./timeout";
 export { useWorkerFunction, WebWorkerFunctionOptions } from "./workerFunction";

packages/vue-composable/src/web/timeout.ts

@@ -0,0 +1,43 @@
+import { ref, Ref, onUnmounted } from "../api";
+
+interface UseTimeoutReturn {
+  /**
+   * current timeout state:
+   *     false - pending
+   *     true - called
+   *     null - canceled
+   */
+  ready: Ref<boolean | null>;
+  /**
+   * cancel the timeout
+   */
+  cancel: () => void;
+}
+/**
+ * @param fn setTimeout callback
+ * @param delay If this parameter is omitted, a value of 0 is used
+ * (https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout)
+ */
+export function useTimeout(
+  fn: () => void,
+  delay: number = 0
+): UseTimeoutReturn {
+  let ready: Ref<boolean | null> = ref(false);
+
+  const timeoutId = setTimeout(() => {
+    ready.value = true;
+    fn();
+  }, delay);
+
+  const cancel = () => {
+    ready.value = null;
+    clearTimeout(timeoutId);
+  };
+
+  onUnmounted(cancel);
+
+  return {
+    ready,
+    cancel,
+  };
+}