Support @@trigger protocol in operator interval (#289)

* Add implementation and test

* Add docs

* Fix overloads error

* Fix invalid type-tests (after adding overloads)

Author: igorkamyshev

src/interval/index.ts

@@ -9,6 +9,20 @@ import {
   is,
 } from 'effector';
 
+export function interval<S extends unknown, F extends unknown>(config: {
+  timeout: number | Store<number>;
+  start: Event<S>;
+  stop?: Event<F>;
+  leading?: boolean;
+  trailing?: boolean;
+}): { tick: Event<void>; isRunning: Store<boolean> };
+
+export function interval(config: {
+  timeout: number | Store<number>;
+  leading?: boolean;
+  trailing?: boolean;
+}): TriggerProtocol;
+
 export function interval<S extends unknown, F extends unknown>({
   timeout,
   start,
@@ -17,11 +31,14 @@ export function interval<S extends unknown, F extends unknown>({
   trailing = false,
 }: {
   timeout: number | Store<number>;
-  start: Event<S>;
+  start?: Event<S>;
   stop?: Event<F>;
   leading?: boolean;
   trailing?: boolean;
-}): { tick: Event<void>; isRunning: Store<boolean> } {
+}): { tick: Event<void>; isRunning: Store<boolean> } & TriggerProtocol {
+  const setup = (start ?? createEvent()) as Event<void>;
+  const teardown = (stop ?? createEvent()) as Event<void>;
+
   const tick = createEvent();
   const $isRunning = createStore(false);
   const $timeout = toStoreNumber(timeout);
@@ -65,19 +82,19 @@ export function interval<S extends unknown, F extends unknown>({
   });
 
   guard({
-    clock: start,
+    clock: setup,
     source: $timeout,
     filter: $notRunning,
     target: timeoutFx,
   });
 
   if (leading) {
-    const onReady = guard({ clock: start, filter: $notRunning }) as Event<S>;
+    const onReady = guard({ clock: setup, filter: $notRunning });
     sample({ clock: onReady, target: tick });
   }
 
   sample({
-    clock: start,
+    clock: setup,
     fn: () => true,
     target: $isRunning,
   });
@@ -97,23 +114,29 @@ export function interval<S extends unknown, F extends unknown>({
     }),
   });
 
-  if (stop) {
-    if (trailing) {
-      sample({
-        clock: stop,
-        target: tick,
-      });
-    }
-
-    $isRunning.on(stop, () => false);
-
+  if (trailing) {
     sample({
-      clock: stop,
-      target: cleanupFx,
+      clock: teardown,
+      target: tick,
     });
   }
 
-  return { tick, isRunning: $isRunning };
+  $isRunning.on(teardown, () => false);
+
+  sample({
+    clock: teardown,
+    target: cleanupFx,
+  });
+
+  return {
+    tick,
+    isRunning: $isRunning,
+    '@@trigger': {
+      setup,
+      teardown,
+      fired: tick,
+    },
+  };
 }
 
 function toStoreNumber(value: number | Store<number> | unknown): Store<number> {
@@ -126,3 +149,10 @@ function toStoreNumber(value: number | Store<number> | unknown): Store<number> {
     `timeout parameter in interval method should be number or Store. "${typeof value}" was passed`,
   );
 }
+
+/**
+ * @see {@link https://withease.pages.dev/protocols/trigger.html}
+ */
+type TriggerProtocol = {
+  '@@trigger': { fired: Event<void>; setup: Event<void>; teardown: Event<void> };
+};

src/interval/interval.fork.test.ts

@@ -1,4 +1,11 @@
-import { allSettled, createEvent, fork, createStore, guard } from 'effector';
+import {
+  allSettled,
+  createEvent,
+  fork,
+  createStore,
+  guard,
+  createWatch,
+} from 'effector';
 import { argumentHistory, wait, watch } from '../../test-library';
 import { interval } from '.';
 
@@ -96,3 +103,30 @@ test('does not leaves unresolved timeout effect, if stopped', async () => {
 
   expect(scope.getState($count)).toEqual(6);
 });
+
+describe('@@trigger', () => {
+  test('fire tick on start and stop after teardown', async () => {
+    const listener = jest.fn();
+    const intervalTrigger = interval({ timeout: 1 });
+
+    const scope = fork();
+
+    const unwatch = createWatch({
+      unit: intervalTrigger['@@trigger'].fired,
+      fn: listener,
+      scope,
+    });
+
+    allSettled(intervalTrigger['@@trigger'].setup, { scope });
+
+    await wait(1);
+    expect(listener).toBeCalledTimes(1);
+
+    await allSettled(intervalTrigger['@@trigger'].teardown, { scope });
+
+    await wait(10);
+    expect(listener).toBeCalledTimes(1);
+
+    unwatch();
+  });
+});

src/interval/readme.md

@@ -78,3 +78,27 @@ setTimeout(() => stopCounter(), 5000);
 ```
 
 [Try it](https://share.effector.dev/EOVzc3df)
+
+### `@@trigger` protocol
+
+`interval` supports [`@@trigger` protocol](https://withease.pages.dev/protocols/trigger.html). It means that you can use `interval` whatever you can use `trigger` with, just do not pass `start` and `stop` options.
+
+```ts
+import { interval } from 'patronum';
+
+somethingThatRequiresTrigger({
+  trigger: interval({ timeout: 1000 }),
+});
+```
+
+For example, you can use `interval` to refresh data in the Query from the library [Farfetched](https://farfetched.pages.dev/tutorial/trigger_api.html#external-triggers) using `@@trigger` protocol.
+
+```ts
+import { keepFresh } from '@farfetched/core';
+import { interval } from 'patronum';
+
+keepFresh(someQuery, {
+  // 👇 Query will be refreshed each 1000 ms
+  triggers: [interval({ timeout: 1000 })],
+});
+```

test-typings/interval.ts

@@ -38,23 +38,21 @@ import { interval } from '../src/interval';
     }),
   );
 
+  // @ts-expect-error
   interval({
     timeout: 100,
     start: createEvent<void>(),
     stop: createEvent<void>(),
-    // @ts-expect-error
     leading: 1,
-    // @ts-expect-error
     trailing: '',
   });
 
+  // @ts-expect-error
   interval({
     timeout: 100,
     start: createEvent<void>(),
     stop: createEvent<void>(),
-    // @ts-expect-error
     leading: [],
-    // @ts-expect-error
     trailing: null,
   });
 }