feat(state-wire): add useSubscribe hook (#19)

Author: smmoosavi

README.md

@@ -20,6 +20,7 @@ connect react components with wire
   - [Global wire](#global-wire)
   - [`useSelector` hook](#useselector-hook)
   - [`createSelector` function](#createselector-function)
+  - [`useSubscribe` hook](#usesubscribe-hook)
   - [Subscribe to the wire](#subscribe-to-the-wire)
   - [`useInterceptor` hook](#useinterceptor-hook)
 - [Notes](#notes)
@@ -277,9 +278,22 @@ function SomeComponent() {
 }
 ```
 
+### `useSubscribe` hook
+
+Every time the wire value changes, the callback function would be called
+
+```tsx
+// subscribe
+useSubscribe(
+  useCallback(value => {
+    /* ... */
+  }, []),
+);
+```
+
 ### Subscribe to the wire
 
-Every time wire value changed the callback function will be called
+Every time the wire value changes, the callback function would be called
 
 <details>
 <summary>more detail</summary>

index.d.ts

@@ -184,6 +184,11 @@ export declare function useSelector<V, Fns = {}>(
   options: ReadOnlySelectorOptions<V>,
 ): ReadonlyWire<V, Fns>;
 
+export declare function useSubscribe<V>(
+  wire: ReadonlyStateWire<V>,
+  callback: (value: Defined<V>) => void,
+): void;
+
 export declare function useWire<V, Fns = {}>(
   upLink: Wire<V, Fns>,
 ): Wire<V, Fns>;

src/index.ts

@@ -14,3 +14,4 @@ export { useFn } from './fn-wire/use-fn';
 export { createWire } from './wire/create-wire';
 export { createSelector } from './selector/create-selector';
 export { useSelector } from './selector/use-selector';
+export { useSubscribe } from './state-wire/use-subscribe';

src/state-wire/use-subscribe.test.ts

@@ -0,0 +1,66 @@
+import { renderHook } from '@testing-library/react-hooks';
+import { useCallback } from 'react';
+import { act } from 'react-dom/test-utils';
+import { useStateWire } from './use-state-wire';
+import { useSubscribe } from './use-subscribe';
+
+describe('useSubscribe', () => {
+  it('should not call the callback function on subscribing', () => {
+    const fn = jest.fn();
+
+    renderHook(() => {
+      const wire = useStateWire(null, 5);
+      useSubscribe(
+        wire,
+        useCallback(value => {
+          fn(value);
+        }, []),
+      );
+      return { wire };
+    });
+    expect(fn).not.toBeCalled();
+  });
+
+  it('should call the callback function when the wire value updates', () => {
+    const fn = jest.fn();
+
+    const { result } = renderHook(() => {
+      const wire = useStateWire(null, 5);
+      useSubscribe(
+        wire,
+        useCallback(value => {
+          fn(value);
+        }, []),
+      );
+      return { wire };
+    });
+    act(() => {
+      result.current.wire.setValue(3);
+    });
+
+    expect(fn).toBeCalledWith(3);
+  });
+
+  it('should not call the callback function after unmount', () => {
+    const fn = jest.fn();
+
+    const { result, unmount } = renderHook(() => {
+      const wire = useStateWire(null, 5);
+      useSubscribe(
+        wire,
+        useCallback(value => {
+          fn(value);
+        }, []),
+      );
+      return { wire };
+    });
+    act(() => {
+      unmount();
+    });
+    act(() => {
+      result.current.wire.setValue(3);
+    });
+
+    expect(fn).not.toBeCalled();
+  });
+});

src/state-wire/use-subscribe.ts

@@ -0,0 +1,14 @@
+import { useEffect } from 'react';
+import { Defined } from '../utils/type-utils';
+import { useStabilityGuard } from '../utils/use-stability-guard';
+import { ReadonlyStateWire } from './readonly-state-wire';
+
+export function useSubscribe<V>(
+  wire: ReadonlyStateWire<V>,
+  callback: (value: Defined<V>) => void,
+): void {
+  useStabilityGuard(wire);
+  useEffect(() => {
+    return wire.subscribe(callback);
+  }, [wire, callback]);
+}