feat: new hook useValidator

.eslintrc.js

@@ -107,6 +107,13 @@ module.exports = {
         'react/prop-types': 'off',
       },
     },
+    {
+      files: ['src/**/__tests__/*.ts'],
+      rules: {
+        '@typescript-eslint/no-unused-vars': 'off',
+        '@typescript-eslint/no-explicit-any': 'off',
+      },
+    },
     {
       files: ['*.md'],
       extends: ['plugin:mdx/recommended', 'prettier'],

.gitignore

@@ -5,4 +5,3 @@ node_modules
 /cjs
 /esm
 /esnext
-/types

.storybook/main.js

@@ -1,13 +1,13 @@
 module.exports = {
-  stories: ['../src/**/__docs__/*.mdx'],
+  stories: ['../src/**/__docs__/*.mdx', '../src/**/__docs__/*.tsx'],
   addons: [
+    '@storybook/addon-links',
     {
       name: '@storybook/addon-essentials',
       options: {
         backgrounds: false,
       },
     },
-    '@storybook/addon-docs',
   ],
   reactOptions: {
     fastRefresh: true,

.storybook/preview.js

@@ -1,3 +1,4 @@
 export const parameters = {
   layout: 'centered',
+  viewMode: 'docs',
 };

CONTRIBUTING.md

@@ -59,9 +59,10 @@ first.
      4ex: `src/useFirstMountState/__docs__/story.mdx`.
    - Docs are built with storybook, to help you during writing docs - start webserver
      with `yarn storybook:watch`.
-   - Components representing hook functionality should be placed next to story file, within
-     `__docs__` folder.  
-     4ex: `src/useFirstMountState/__docs__/example.tsx`.
+   - Components representing hook functionality should be placed in `example.stories.tsx` within
+     `__docs__` folder. In case file name will be missing `.stories.tsx` part - code preview won't
+     work.  
+     4ex: `src/useFirstMountState/__docs__/example.stories.tsx`.
    - Preferred format to write the docs is
      MDX. [Read more about storybook docs](https://storybook.js.org/docs/react/writing-docs/introduction).
 5. Add docs link and hook summary to the `README.md`.

README.md

@@ -96,6 +96,8 @@ import { useMountEffect } from "@react-hookz/web/esnext";
     — Like `useState`, but its state setter is guarded against sets on unmounted component.
   - [**`useToggle`**](https://react-hookz.github.io/web/?path=/docs/state-usetoggle)
     — Like `useState`, but can only become `true` or `false`.
+  - [**`useValidator`**](https://react-hookz.github.io/web/?path=/docs/state-usevalidator)
+    — Performs validation when any of provided dependencies has changed.
 
 - #### Navigator
 

package.json

@@ -110,7 +110,6 @@
     "eslint-plugin-prettier": "^3.4.0",
     "eslint-plugin-react": "^7.23.2",
     "eslint-plugin-react-hooks": "^4.2.0",
-    "globby": "^11.0.3",
     "husky": "^4.3.8",
     "jest": "^26.6.3",
     "jest-github-actions-reporter": "^1.0.3",

src/index.ts

@@ -44,3 +44,11 @@ export { useMeasure } from './useMeasure/useMeasure';
 
 // Dom
 export { useDocumentTitle, IUseDocumentTitleOptions } from './useDocumentTitle/useDocumentTitle';
+
+export {
+  useValidator,
+  IValidatorImmediate,
+  IValidatorDeferred,
+  IValidator,
+  IValidityState,
+} from './useValidator/useValidator';

src/useConditionalEffect/__docs__/story.mdx

@@ -1,5 +1,5 @@
 import { Canvas, Meta, Story } from '@storybook/addon-docs/blocks';
-import { Example } from './example';
+import { Example } from './example.stories';
 
 <Meta title="Lifecycle/useConditionalEffect" component={Example} />
 

src/useConditionalUpdateEffect/__docs__/story.mdx

@@ -1,5 +1,5 @@
 import { Canvas, Meta, Story } from '@storybook/addon-docs/blocks';
-import { Example } from './example';
+import { Example } from './example.stories';
 
 <Meta title="Lifecycle/useConditionalUpdateEffect" component={Example} />
 

src/useDebounceCallback/__docs__/story.mdx

@@ -1,5 +1,5 @@
 import { Canvas, Meta, Story } from '@storybook/addon-docs/blocks';
-import { Example } from './example';
+import { Example } from './example.stories';
 
 <Meta title="Callback/useDebounceCallback" component={Example} />
 

src/useDebounceCallback/__tests__/dom.ts

@@ -21,6 +21,22 @@ describe('useDebounceCallback', () => {
     expect(result.error).toBeUndefined();
   });
 
+  it('should return function same length and wrapped name', () => {
+    let { result } = renderHook(() =>
+      useDebounceCallback((_a: any, _b: any, _c: any) => {}, 200, [])
+    );
+
+    expect(result.current.length).toBe(3);
+    expect(result.current.name).toBe(`anonymous__debounced__200`);
+
+    function testFn(_a: any, _b: any, _c: any) {}
+
+    result = renderHook(() => useDebounceCallback(testFn, 100, [])).result;
+
+    expect(result.current.length).toBe(3);
+    expect(result.current.name).toBe(`testFn__debounced__100`);
+  });
+
   it('should return new callback if delay is changed', () => {
     const { result, rerender } = renderHook(
       ({ delay }) => useDebounceCallback(() => {}, delay, []),

src/useDebounceCallback/useDebounceCallback.ts

@@ -14,18 +14,26 @@ export function useDebounceCallback<T extends (...args: any[]) => any>(
   deps: DependencyList
 ): (...args: Parameters<T>) => void {
   const timeout = useRef<ReturnType<typeof setTimeout>>();
-
   return useMemo(
-    () =>
-      (...args: Parameters<T>): void => {
+    () => {
+      // eslint-disable-next-line func-names
+      const debounced = function (...args: Parameters<T>): void {
         if (timeout.current) clearTimeout(timeout.current);
 
         timeout.current = setTimeout(() => {
           timeout.current = undefined;
 
           cb(...args);
         }, delay);
-      },
+      };
+
+      Object.defineProperties(debounced, {
+        length: { value: cb.length },
+        name: { value: `${cb.name || 'anonymous'}__debounced__${delay}` },
+      });
+
+      return debounced;
+    },
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [delay, ...deps]
   );

src/useDocumentTitle/__docs__/story.mdx

@@ -1,5 +1,5 @@
 import { Canvas, Meta, Story } from '@storybook/addon-docs/blocks';
-import { Example } from './example';
+import { Example } from './example.stories';
 
 <Meta title="Dom/useDocumentTitle" component={Example} />
 

src/useFirstMountState/__docs__/story.mdx

@@ -1,5 +1,5 @@
 import { Canvas, Meta, Story, Typeset } from '@storybook/addon-docs/blocks';
-import { Example } from './example';
+import { Example } from './example.stories';
 
 <Meta title="Lifecycle/useFirstMountState" component={Example} />
 

src/useIsMounted/__docs__/story.mdx

@@ -1,5 +1,5 @@
 import { Canvas, Meta, Story } from '@storybook/addon-docs/blocks';
-import { Example } from './example';
+import { Example } from './example.stories';
 
 <Meta title="Lifecycle/useIsMounted" component={Example} />
 

src/useLocalStorageValue/__docs__/story.mdx

@@ -1,4 +1,4 @@
-import { Example } from './example';
+import { Example } from './example.stories';
 import { ArgsTable, Canvas, Meta, Story } from '@storybook/addon-docs/blocks';
 
 <Meta title="Side-effect/useLocalStorageValue" component={Example} />

src/useMeasure/__docs__/story.mdx

@@ -1,5 +1,5 @@
 import { Canvas, Meta, Story } from '@storybook/addon-docs/blocks';
-import { Example } from './example';
+import { Example } from './example.stories';
 
 <Meta title="Sensor/useMeasure" />
 

src/useMediatedState/__docs__/story.mdx

@@ -1,5 +1,5 @@
 import { Canvas, Meta, Story } from '@storybook/addon-docs/blocks';
-import { Example } from './example';
+import { Example } from './example.stories';
 
 <Meta title="State/useMediatedState" component={Example} />
 

src/useMountEffect/__docs__/story.mdx

@@ -1,5 +1,5 @@
 import { Canvas, Meta, Story } from '@storybook/addon-docs/blocks';
-import { Example } from './example';
+import { Example } from './example.stories';
 
 <Meta title="Lifecycle/useMountEffect" component={Example} />
 

src/useNetworkState/__docs__/story.mdx

@@ -1,4 +1,4 @@
-import { Example } from './example';
+import { Example } from './example.stories';
 import { Canvas, Meta, Story } from '@storybook/addon-docs/blocks';
 
 <Meta title={'Navigator/useNetwork'} component={Example} />

src/usePrevious/__docs__/story.mdx

@@ -1,5 +1,5 @@
 import { Canvas, Meta, Story } from '@storybook/addon-docs/blocks';
-import { Example } from './example';
+import { Example } from './example.stories';
 
 <Meta title="State/usePrevious" component={Example} />
 

src/useRafCallback/__docs__/story.mdx

@@ -1,5 +1,5 @@
 import { Canvas, Meta, Story } from '@storybook/addon-docs/blocks';
-import { Example } from './example';
+import { Example } from './example.stories';
 
 <Meta title="Callback/useRafCallback" component={Example} />
 

src/useRafCallback/__tests__/dom.ts

@@ -1,5 +1,5 @@
 import { renderHook } from '@testing-library/react-hooks/dom';
-import { useRafCallback } from '../..';
+import { useDebounceCallback, useRafCallback } from '../..';
 
 describe('useRafCallback', () => {
   const raf = global.requestAnimationFrame;
@@ -27,6 +27,20 @@ describe('useRafCallback', () => {
     renderHook(() => useRafCallback(() => {}));
   });
 
+  it('should return function same length and wrapped name', () => {
+    let { result } = renderHook(() => useRafCallback((_a: any, _b: any, _c: any) => {}));
+
+    expect(result.current[0].length).toBe(3);
+    expect(result.current[0].name).toBe(`anonymous__raf`);
+
+    function testFn(_a: any, _b: any, _c: any) {}
+
+    result = renderHook(() => useRafCallback(testFn)).result;
+
+    expect(result.current[0].length).toBe(3);
+    expect(result.current[0].name).toBe(`testFn__raf`);
+  });
+
   it('should return array of functions', () => {
     const { result } = renderHook(() => useRafCallback(() => {}));
 

src/useRafCallback/useRafCallback.ts

@@ -1,4 +1,4 @@
-import { useCallback, useRef } from 'react';
+import { useCallback, useMemo, useRef } from 'react';
 import { useSyncedRef } from '../useSyncedRef/useSyncedRef';
 import { isBrowser } from '../util/const';
 import { useUnmountEffect } from '../useUnmountEffect/useUnmountEffect';
@@ -29,17 +29,27 @@ export function useRafCallback<T extends (...args: any[]) => any>(
   useUnmountEffect(cancel);
 
   return [
-    useCallback((...args) => {
-      if (!isBrowser) return;
+    useMemo(() => {
+      const wrapped = (...args: Parameters<T>) => {
+        if (!isBrowser) return;
 
-      cancel();
+        cancel();
 
-      frame.current = requestAnimationFrame(() => {
-        cbRef.current(...args);
-        frame.current = 0;
+        frame.current = requestAnimationFrame(() => {
+          cbRef.current(...args);
+          frame.current = 0;
+        });
+      };
+
+      Object.defineProperties(wrapped, {
+        length: { value: cb.length },
+        name: { value: `${cb.name || 'anonymous'}__raf` },
       });
+
+      return wrapped;
       // eslint-disable-next-line react-hooks/exhaustive-deps
     }, []),
+
     cancel,
   ];
 }

src/useRerender/__docs__/story.mdx

@@ -1,5 +1,5 @@
 import { Canvas, Meta, Story } from '@storybook/addon-docs/blocks';
-import { Example } from './example';
+import { Example } from './example.stories';
 
 <Meta title="Lifecycle/useRerender" component={Example} />
 

src/useResizeObserver/__docs__/story.mdx

@@ -1,5 +1,5 @@
 import { Canvas, Meta, Story } from '@storybook/addon-docs/blocks';
-import { Example, ExampleDebounced } from './example';
+import { Example, ExampleDebounced } from './example.stories';
 
 <Meta title="Sensor/useResizeObserver" />
 

src/useSessionStorageValue/__docs__/story.mdx

@@ -1,4 +1,4 @@
-import { Example } from './example';
+import { Example } from './example.stories';
 import { ArgsTable, Canvas, Meta, Story } from '@storybook/addon-docs/blocks';
 
 <Meta title="Side-effect/useSessionStorageValue" component={Example} />

src/useSyncedRef/__docs__/story.mdx

@@ -1,5 +1,5 @@
 import { Canvas, Meta, Story } from '@storybook/addon-docs/blocks';
-import { Example } from './example';
+import { Example } from './example.stories';
 
 <Meta title="Miscellaneous/useSyncedRef" component={Example} />
 

src/useToggle/__docs__/story.mdx

@@ -1,5 +1,5 @@
 import { Canvas, Meta, Story } from '@storybook/addon-docs/blocks';
-import { Example } from './example';
+import { Example } from './example.stories';
 
 <Meta title="State/useToggle" component={Example} />
 

src/useUnmountEffect/__docs__/story.mdx

@@ -1,5 +1,5 @@
 import { Canvas, Meta, Story } from '@storybook/addon-docs/blocks';
-import { Example } from './example';
+import { Example } from './example.stories';
 
 <Meta title="Lifecycle/useUnmountEffect" component={Example} />
 

src/useUpdateEffect/__docs__/story.mdx

@@ -1,5 +1,5 @@
 import { Canvas, Meta, Story } from '@storybook/addon-docs/blocks';
-import { Example } from './example';
+import { Example } from './example.stories';
 
 <Meta title="Lifecycle/useUpdateEffect" component={Example} />
 

src/useValidator/__docs__/example.stories.tsx

@@ -0,0 +1,48 @@
+import * as React from 'react';
+import { useState } from 'react';
+import { IValidatorDeferred, useDebounceCallback, useValidator } from '../..';
+
+export const ExampleStories: React.FC = () => {
+  const [text, setText] = useState('');
+
+  // as deferred validator is unable to infer the type of validity
+  // state - we should define it ourself
+  type ITextValidityState = { isValid: boolean | undefined; error: Error | undefined };
+
+  // debounced callback is deferred callback so we should use deferred type
+  // of validator (the one that receives dispatcher as an argument)
+  const validator = useDebounceCallback<IValidatorDeferred<ITextValidityState>>(
+    (d) => {
+      const isValid = !text.length || text.length % 2 === 1;
+
+      d({
+        isValid,
+        error: !isValid ? new Error('text length should be an odd length') : undefined,
+      });
+    },
+    150,
+    [text]
+  );
+
+  // validity state type if inferred from validator
+  const [validity] = useValidator(validator, [validator]);
+
+  return (
+    <div>
+      <div>
+        In case below input has an odd number of characters - it is valid, otherwise, the error
+        message is shown
+      </div>
+      <br />
+
+      {validity.isValid === false && <div style={{ color: 'red' }}>{validity.error?.message}</div>}
+      <input
+        type="text"
+        value={text}
+        onChange={(ev) => {
+          setText(ev.target.value);
+        }}
+      />
+    </div>
+  );
+};