feat(useInterval): add useInterval composable

docs/README.md

@@ -75,6 +75,7 @@ Check out the [examples folder](examples) or start hacking on [codesandbox](http
 - [sharedRef](composable/misc/sharedRef) - cross-tab reactive `ref`
 - [VModel](composable/misc/vmodel) - helper to wrap model update into a `ref` `[vue3 only]`
 - [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
 
 ### Storage

docs/composable/misc/interval.md

@@ -0,0 +1,44 @@
+# Interval
+
+> `setInterval` with `start`/`remove` and `clearInterval` on unmounted.
+
+## Parameters
+
+```js
+import { useInterval } from "vue-composable";
+
+useInterval(callback, ms?, ...args);
+```
+
+| Parameters | Type                         | Required | Default     | Description                                                                  |
+| ---------- | ---------------------------- | -------- | ----------- | ---------------------------------------------------------------------------- |
+| callback   | `(...args):void`             | `true`   |             | `setInterval` callback                                                       |
+| ms         | `number | false | undefined` | `false`  | `undefined` | callback interval `ms`, if `ms` provided it will `setInterval` automatically |
+| ...args    | `any`                        | `false`  | `[]`        | callback args                                                                |
+
+## Methods
+
+The `useInterval` function exposes the following methods:
+
+```js
+import { useInterval } from "vue-composable";
+
+const { start, remove } = useInterval();
+```
+
+| Signature | Description              |
+| --------- | ------------------------ |
+| start     | Start                    |
+| remove    | Manually `clearInterval` |
+
+### Code
+
+```vue
+<script>
+export default {
+  setup() {
+    useInterval(() => console.log(Date.now()), 1000);
+  }
+};
+</script>
+```

packages/vue-composable/README.md

@@ -77,6 +77,7 @@ Check our [documentation](https://pikax.me/vue-composable/)
 - [sharedRef](https://pikax.me/vue-composable/composable/misc/sharedRef) - cross-tab reactive `ref`
 - [VModel](https://pikax.me/vue-composable/composable/meta/vmodel) - helper to wrap model update into a `ref` `[vue3 only]`
 - [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
 
 ### Storage

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

@@ -0,0 +1,158 @@
+import { createVue } from "../utils";
+import {
+  useInterval,
+  UseIntervalReturn,
+  UseIntervalReturnMs,
+  UseIntervalReturnArgs
+} from "../../src";
+
+describe("interval", () => {
+  beforeEach(() => {
+    jest.useFakeTimers();
+  });
+  afterAll(() => {
+    jest.useRealTimers();
+  });
+  it("should work", async () => {
+    const callback = jest.fn();
+    const ms = 100;
+
+    let interval: UseIntervalReturn & UseIntervalReturnMs = {} as any;
+    const { mount, destroy } = createVue({
+      template: `<div></div>`,
+      setup() {
+        interval = useInterval(callback, ms);
+      }
+    });
+
+    mount();
+
+    expect(clearInterval).not.toHaveBeenCalled();
+    expect(setInterval).toHaveBeenCalledWith(callback, ms);
+
+    interval.start();
+    expect(clearInterval).toHaveBeenCalled();
+    expect(setInterval).toHaveBeenNthCalledWith(2, callback, ms);
+
+    interval.remove();
+
+    expect(clearInterval).toHaveBeenCalledTimes(2);
+
+    interval.start();
+
+    destroy();
+
+    expect(clearInterval).toHaveBeenCalledTimes(3);
+  });
+
+  it("should remove at unmount", () => {
+    const callback = jest.fn();
+    const ms = 100;
+
+    const { mount, destroy } = createVue({
+      template: `<div></div>`,
+      setup() {
+        useInterval(callback, ms);
+      }
+    });
+
+    mount();
+
+    expect(clearInterval).not.toHaveBeenCalled();
+    expect(setInterval).toHaveBeenCalledWith(callback, ms);
+
+    destroy();
+
+    expect(clearInterval).toHaveBeenCalled();
+  });
+
+  it("should not start if ms are not passed", () => {
+    const callback = jest.fn();
+    const ms = 100;
+
+    let interval: UseIntervalReturn = {} as any;
+    const { mount, destroy } = createVue({
+      template: `<div></div>`,
+      setup() {
+        interval = useInterval(callback);
+      }
+    });
+
+    mount();
+
+    expect(clearInterval).not.toHaveBeenCalled();
+    expect(setInterval).not.toHaveBeenCalled();
+
+    interval.start(ms);
+    expect(setInterval).toHaveBeenCalledWith(callback, ms);
+
+    destroy();
+  });
+
+  it("should override ms on start()", () => {
+    const callback = jest.fn();
+    const ms = 100;
+
+    let interval: UseIntervalReturn & UseIntervalReturnMs = {} as any;
+    const { mount, destroy } = createVue({
+      template: `<div></div>`,
+      setup() {
+        interval = useInterval(callback, ms);
+      }
+    });
+
+    mount();
+
+    expect(clearInterval).not.toHaveBeenCalled();
+    expect(setInterval).toHaveBeenCalled();
+
+    interval.start(20);
+    expect(setInterval).toHaveBeenLastCalledWith(callback, 20);
+
+    destroy();
+  });
+
+  it("should override args on start()", () => {
+    const callback = jest.fn((x: number) => x);
+    const ms = 100;
+
+    let interval: UseIntervalReturn &
+      UseIntervalReturnArgs<[number]> = {} as any;
+    const { mount, destroy } = createVue({
+      template: `<div></div>`,
+      setup() {
+        interval = useInterval(callback, ms, 1);
+      }
+    });
+
+    mount();
+
+    expect(clearInterval).not.toHaveBeenCalled();
+    expect(setInterval).toHaveBeenLastCalledWith(callback, ms, 1);
+
+    interval.start(undefined, 2);
+    expect(setInterval).toHaveBeenLastCalledWith(callback, ms, 2);
+
+    destroy();
+  });
+
+  it("should not start if no ms passed", () => {
+    const callback = jest.fn((x: number) => x);
+    let interval: UseIntervalReturnMs = {} as any;
+    const { mount, destroy } = createVue({
+      template: `<div></div>`,
+      setup() {
+        // @ts-ignore
+        interval = useInterval(callback);
+      }
+    });
+
+    mount();
+
+    expect(clearInterval).not.toHaveBeenCalled();
+    interval.start();
+    expect(setInterval).not.toHaveBeenCalled();
+
+    destroy();
+  });
+});

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

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

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

@@ -0,0 +1,76 @@
+import { onUnmounted } from "../api";
+import { isNumber } from "../utils";
+
+export interface UseIntervalReturn<TArgs extends Array<any> = []> {
+  start(ms: number, ...args: TArgs): number;
+
+  remove(): void;
+}
+
+export interface UseIntervalReturnMs {
+  start(): number;
+}
+
+export interface UseIntervalReturnArgs<TArgs extends Array<any>> {
+  start(_: undefined, ...args: TArgs): number;
+}
+
+export function useInterval<TArgs extends Array<any>>(
+  callback: (...args: TArgs) => void,
+  ms?: false,
+  ...args: TArgs
+): UseIntervalReturn<TArgs>;
+
+export function useInterval<TArgs extends Array<any>>(
+  callback: (...args: TArgs) => void,
+  ms?: false
+): UseIntervalReturn<TArgs>;
+
+export function useInterval<TArgs extends Array<any>>(
+  callback: (...args: TArgs) => void,
+  ms: number,
+  ...args: TArgs
+): UseIntervalReturn<TArgs> &
+  UseIntervalReturnMs &
+  UseIntervalReturnArgs<TArgs>;
+
+export function useInterval<TArgs extends Array<any>>(
+  callback: (...args: TArgs) => void,
+  ms?: number | false,
+  ...args: TArgs
+): UseIntervalReturn<TArgs> &
+  UseIntervalReturnMs &
+  UseIntervalReturnArgs<TArgs> {
+  let intervalId: number | undefined = undefined;
+
+  const start = (_ms?: number, ..._args: any[]) => {
+    remove();
+    if (!_ms && !ms) {
+      return;
+    }
+    const m = (_ms || ms) as number;
+    return (intervalId = setInterval(
+      callback,
+      m,
+      ...(_args && _args.length ? _args : args)
+    ) as any);
+  };
+
+  const remove = () => {
+    if (!intervalId) return;
+    clearInterval(intervalId);
+    intervalId = undefined;
+  };
+
+  if (isNumber(ms)) {
+    start();
+  }
+
+  onUnmounted(remove);
+  return { remove, start };
+}
+
+// TODO move this:  type checkings
+// useInterval((x: number) => {}).start();
+// useInterval((x: number) => {}, 100, 1).start();
+// useInterval(() => {}).start();

readme.md

@@ -77,6 +77,7 @@ Check our [documentation](https://pikax.me/vue-composable/)
 - [sharedRef](https://pikax.me/vue-composable/composable/misc/sharedRef) - cross-tab reactive `ref`
 - [VModel](https://pikax.me/vue-composable/composable/meta/vmodel) - helper to wrap model update into a `ref` `[vue3 only]`
 - [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
 
 ### Storage