Feature/10 add usetimeout and useinterval hooks

package.json

@@ -41,7 +41,7 @@
     "plop": "plop"
   },
   "peerDependencies": {
-    "@muban/muban": "^1.0.0-alpha.28"
+    "@muban/muban": "^1.0.0-alpha.34"
   },
   "devDependencies": {
     "@babel/core": "^7.12.10",

src/useInterval/useInterval.stories.mdx

@@ -0,0 +1,73 @@
+import { Meta } from '@storybook/addon-docs';
+
+<Meta
+  title="useInterval/docs"
+/>
+
+# useInterval
+
+The `useInterval` hook is a wrapper around the native `setInterval`, it allows you to easily set
+an interval within your component that will be auto cancelled when the component unmounts.
+
+## Reference
+
+```ts
+function useInterval(
+  callback: () => void,
+  interval?: number = 100,
+  startImmediate?: boolean = true,
+): { startInterval: () => void, stopInterval: () => void; isIntervalRunning: ComputedRef<boolean> }
+```
+
+### Parameters
+* `callback` – The callback you want to trigger once the interval runs.
+* `interval` - The duration of the interval you want to create.
+* `startImmediate` - Whether or not you want to immediately start the interval.
+
+### Returns
+* `{ startInterval, stopInterval, isIntervalRunning }`
+  * `startInterval` – A function that starts the interval, any running intervals will automatically be stopped.
+  * `stopInterval` – A function that will stop the current active interval.
+  * `isIntervalRunning` – A computed ref that keeps track whether or not the interval is running.
+
+## Usage
+
+```ts
+const { startInterval, stopInterval, isIntervalRunning } = useInterval(() => {
+  console.log('The interval has run')
+}, 1000, false);
+````
+
+```ts
+const Demo = defineComponent({
+  name: 'demo',
+  refs: {
+    startBtn: 'start-button'
+    stopButton: 'stop-button'
+  },
+  setup({ refs }) {
+    // The interval starts as soon as the component is mounted.
+    useInterval(() => {
+      console.log('The immediate interval callback is triggered.')
+    }, 1000);
+
+    // The interval doesn't start automatically, but requires a user action to start.
+    const { startInterval, stopInterval, isIntervalRunning } = useInterval(() => {
+      console.log('The user-action interval callback is triggered.')
+    }, 1000, false);
+
+    return [
+      bind(refs.startBtn, {
+        click() {
+         startInterval(); // This actually starts the interval.
+        }
+      }),
+      bind(refs.stopButton, {
+        click() {
+          stopInterval(); // This stops the interval if it's active.
+        }
+      })
+    ]
+  }
+})
+```

src/useInterval/useInterval.stories.ts

@@ -0,0 +1,86 @@
+/* eslint-disable import/no-extraneous-dependencies */
+import { bind, computed, defineComponent, propType } from '@muban/muban';
+import type { Story } from '@muban/storybook/types-6-0';
+import { html } from '@muban/template';
+import { useInterval } from './useInterval';
+import { useStorybookLog } from '../hooks/useStorybookLog';
+
+export default {
+  title: 'useInterval',
+};
+
+type DemoStoryProps = { startImmediate?: boolean; interval?: number };
+
+export const Demo: Story<DemoStoryProps> = () => ({
+  component: defineComponent({
+    name: 'story',
+    props: {
+      startImmediate: propType.boolean.defaultValue(false),
+      interval: propType.number,
+    },
+    refs: {
+      label: 'label',
+      startButton: 'start-button',
+      stopButton: 'stop-button',
+    },
+    setup({ refs, props }) {
+      const [logBinding, log] = useStorybookLog(refs.label);
+
+      function onInterval() {
+        log('interval called');
+      }
+
+      const { startInterval, stopInterval, isIntervalRunning } = useInterval(
+        onInterval,
+        props.interval,
+        props.startImmediate,
+      );
+
+      return [
+        logBinding,
+        bind(refs.startButton, {
+          attr: {
+            disabled: isIntervalRunning,
+          },
+          click() {
+            startInterval();
+          },
+        }),
+        bind(refs.stopButton, {
+          attr: {
+            disabled: computed(() => !isIntervalRunning.value),
+          },
+          click() {
+            log('interval stopped');
+            stopInterval();
+          },
+        }),
+      ];
+    },
+  }),
+  template: ({ startImmediate = false, interval = 2500 }: DemoStoryProps = {}) => html`<div
+    data-component="story"
+    data-start-immediate=${startImmediate}
+    data-interval=${interval}
+  >
+    <div class="alert alert-primary">
+      <h4 class="alert-heading">Instructions!</h4>
+      <p class="mb-0">
+        The demo interval is set to 2.5 seconds, you can start it by clicking the start button. You
+        can stop the interval by clicking the stop button.
+      </p>
+    </div>
+    <div data-ref="label" />
+    <div class="card border-dark">
+      <div class="card-header">Test Area</div>
+      <div class="card-body">
+        <button type="button" data-ref="start-button" class="btn btn-primary">
+          Start interval
+        </button>
+        ${' '}
+        <button type="button" data-ref="stop-button" class="btn btn-danger">Stop interval</button>
+      </div>
+    </div>
+  </div>`,
+});
+Demo.storyName = 'demo';

src/useInterval/useInterval.test.ts

@@ -0,0 +1,102 @@
+import { runComponentSetup } from '@muban/test-utils';
+import { useInterval } from './useInterval';
+
+jest.mock('@muban/muban', () => jest.requireActual('@muban/test-utils').getMubanLifecycleMock());
+
+describe('useInterval', () => {
+  beforeEach(() => {
+    jest.useFakeTimers();
+  });
+
+  it('should not crash', () => {
+    runComponentSetup(() => {
+      useInterval(() => undefined);
+    });
+  });
+
+  it('should start immediate and not be completed', () => {
+    const mockHandler = jest.fn();
+
+    runComponentSetup(() => {
+      useInterval(mockHandler, 100);
+    });
+
+    expect(mockHandler).toBeCalledTimes(0);
+  });
+
+  it('should start immediate and be called once', () => {
+    const mockHandler = jest.fn();
+
+    runComponentSetup(
+      () => useInterval(mockHandler, 100),
+      ({ stopInterval }) => {
+        jest.advanceTimersByTime(100);
+        stopInterval();
+      },
+    );
+
+    expect(mockHandler).toBeCalledTimes(1);
+  });
+
+  it('should trigger start and be stopped after three calls', () => {
+    const mockHandler = jest.fn();
+
+    runComponentSetup(
+      () => useInterval(mockHandler, 100, false),
+      ({ startInterval, stopInterval }) => {
+        startInterval();
+        jest.advanceTimersByTime(300);
+        stopInterval();
+      },
+    );
+
+    expect(mockHandler).toBeCalledTimes(3);
+  });
+
+  it('should trigger stop once the interval is started', () => {
+    const mockHandler = jest.fn();
+
+    runComponentSetup(
+      () => useInterval(mockHandler, 200, false),
+      ({ startInterval, stopInterval }) => {
+        startInterval();
+        jest.advanceTimersByTime(100);
+        stopInterval();
+        jest.advanceTimersByTime(200);
+      },
+    );
+
+    expect(mockHandler).toBeCalledTimes(0);
+  });
+
+  it('should know that the interval is running', () => {
+    const mockHandler = jest.fn();
+
+    runComponentSetup(
+      () => useInterval(mockHandler, 200, false),
+      ({ startInterval, stopInterval, isIntervalRunning }) => {
+        startInterval();
+        jest.advanceTimersByTime(100);
+        expect(isIntervalRunning.value).toEqual(true);
+        stopInterval();
+        expect(isIntervalRunning.value).toEqual(false);
+      },
+    );
+  });
+
+  it('should start a new interval before the old one was triggered and only complete once', () => {
+    const mockHandler = jest.fn();
+
+    runComponentSetup(
+      () => useInterval(mockHandler, 100, false),
+      ({ startInterval }) => {
+        startInterval();
+        jest.advanceTimersByTime(50);
+        startInterval();
+        jest.advanceTimersByTime(100);
+      },
+    );
+
+    expect(mockHandler).toBeCalledTimes(1);
+  });
+});

src/useInterval/useInterval.ts

@@ -0,0 +1,49 @@
+import type { ComputedRef } from '@muban/muban';
+import { ref, onMounted, onUnmounted, computed } from '@muban/muban';
+
+// We use `-1` as the value to indicate that an interval is not running.
+const NOT_RUNNING = -1;
+
+/**
+ *  A hook that can be used to call a function on a provided interval, by default the interval
+ *  will run immediate. You can also start and cancel the interval whenever needed.
+ *
+ * @param callback The callback you want to trigger once the interval runs.
+ * @param interval The duration of the interval you want to create.
+ * @param startImmediate Whether or not you want to immediately start the interval.
+ */
+export const useInterval = (
+  callback: () => void,
+  interval: number = 100,
+  startImmediate: boolean = true,
+): {
+  startInterval: () => void;
+  stopInterval: () => void;
+  isIntervalRunning: ComputedRef<boolean>;
+} => {
+  const intervalId = ref<number>(NOT_RUNNING);
+
+  function start() {
+    stop();
+    intervalId.value = setInterval(callback, interval) as unknown as number;
+  }
+
+  function stop() {
+    clearInterval(intervalId.value);
+    intervalId.value = NOT_RUNNING;
+  }
+
+  onUnmounted(() => {
+    stop();
+  });
+
+  onMounted(() => {
+    if (startImmediate) start();
+  });
+
+  return {
+    startInterval: start,
+    stopInterval: stop,
+    isIntervalRunning: computed(() => intervalId.value !== NOT_RUNNING),
+  };
+};

src/useInterval/useIntervalStories.test.ts

@@ -0,0 +1,29 @@
+import '@testing-library/jest-dom';
+import { waitFor, render } from '@muban/testing-library';
+import userEvent from '@testing-library/user-event';
+import { Demo } from './useInterval.stories';
+
+describe('useInterval stories', () => {
+  const { click } = userEvent.setup();
+
+  it('should render', () => {
+    const { getByText } = render(Demo);
+
+    expect(getByText('Test Area')).toBeInTheDocument();
+  });
+
+  it('should start immediate and be called after 100ms', async () => {
+    const { getByText } = render(Demo, { startImmediate: true, interval: 100 });
+
+    await waitFor(() => expect(getByText('interval called')).toBeInTheDocument());
+  });
+
+  it('should start after clicking start and be called after 100ms', async () => {
+    const { getByText, getByRef } = render(Demo, { interval: 100 });
+    const startButton = getByRef('start-button');
+
+    click(startButton);
+
+    await waitFor(() => expect(getByText('interval called')).toBeInTheDocument());
+  });
+});