feat: new hook useCookie

README.md

@@ -115,6 +115,8 @@ import { useMountEffect } from "@react-hookz/web/esnext";
     — Manages a single LocalStorage key.
   - [**`useSessionStorageValue`**](https://react-hookz.github.io/?path=/docs/side-effect-usesessionstoragevalue)
     — Manages a single SessionStorage key.
+  - [**`useCookie`**](https://react-hookz.github.io/?path=/docs/side-effect-usecookie)
+    — Manages a single cookie.
 
 - #### Sensor
 

package.json

@@ -70,13 +70,20 @@
     ]
   },
   "dependencies": {
+    "@types/js-cookie": "^2.2.6",
     "@types/react": "^17.0.3",
     "@types/react-dom": "^17.0.3"
   },
   "peerDependencies": {
+    "js-cookie": "^2.2.1",
     "react": "^16.8 || ^17",
     "react-dom": "^16.8 || ^17"
   },
+  "peerDependenciesMeta": {
+    "js-cookie": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@babel/core": "^7.13.16",
     "@commitlint/config-conventional": "^12.1.1",
@@ -113,6 +120,7 @@
     "husky": "^4.3.8",
     "jest": "^26.6.3",
     "jest-github-actions-reporter": "^1.0.3",
+    "js-cookie": "^2.2.1",
     "lint-staged": "^11.0.0",
     "prettier": "^2.2.1",
     "react": "^17.0.2",

src/index.ts

@@ -30,17 +30,23 @@ export {
   IValidatorDeferred,
   IValidator,
   IValidityState,
+  IUseValidatorReturn,
 } from './useValidator/useValidator';
 
 // Navigator
-export { useNetworkState } from './useNetworkState/useNetworkState';
+export {
+  useNetworkState,
+  IUseNetworkState,
+  INetworkInformation,
+} from './useNetworkState/useNetworkState';
 
 // Miscellaneous
 export { useSyncedRef } from './useSyncedRef/useSyncedRef';
 
 // SideEffect
 export { useLocalStorageValue } from './useLocalStorageValue/useLocalStorageValue';
 export { useSessionStorageValue } from './useSessionStorageValue/useSessionStorageValue';
+export { useCookie, IUseCookieReturn } from './useCookie/useCookie';
 
 // Sensor
 export {

src/useCookie/__docs__/example.stories.tsx

@@ -0,0 +1,31 @@
+import * as React from 'react';
+import { useCookie } from '../..';
+
+export const Example: React.FC = () => {
+  const [cookie, set, remove] = useCookie('react-hookz', { expires: 3600 });
+
+  return (
+    <div>
+      <div>
+        <em>Cookie name:</em> react-hookz
+      </div>
+      <div>
+        <em>Cookie value:</em> {cookie}
+      </div>
+      <br />
+      <input
+        type="text"
+        value={cookie ?? ''}
+        onChange={(ev) => {
+          set(ev.target.value);
+        }}
+        placeholder="Enter cookie value here"
+      />
+      <br />
+      <br />
+      <div>
+        <button onClick={remove}>remove cookie</button>
+      </div>
+    </div>
+  );
+};

src/useCookie/__docs__/story.mdx

@@ -0,0 +1,50 @@
+import { Canvas, Meta, Story } from '@storybook/addon-docs/blocks';
+import { Example } from './example.stories';
+
+<Meta title="Side-effect/useCookie" component={Example} />
+
+# useCookie
+
+Manages a single cookie.
+
+> Requires installation of `js-cookie` package.
+
+- Uses `js-cookie` package underneath.
+- SSR-friendly.
+- Hooks that managing same key on same page - are synchronised. This synchronisation does not
+  involve cross-tabs sync or triggering on changes that performed by third-party code.
+
+#### Example
+
+<Canvas columns={3}>
+  <Story story={Example} inline />
+  <Story story={Example} inline />
+  <Story story={Example} inline />
+</Canvas>
+
+## Reference
+
+```ts
+export type IUseCookieReturn = [
+  value: undefined | null | string,
+  set: (value: string) => void,
+  remove: () => void,
+  fetch: () => void
+];
+
+export function useCookie(key: string, options?: Cookies.CookieAttributes): IUseCookieReturn;
+```
+
+#### Arguments
+
+- **key** _`string`_ - Cookie name to manage.
+- **options** _`Cookies.CookieAttributes`_ _(default: undefined)_ - Cookie options that will be
+  used during cookie set and delete.
+
+#### Return
+
+0. **state** - cookie value, `undefined` means it is not fetched yet, `null` means absence of
+   cookie.
+1. **det** - Method to set new cookie value.
+2. **remove** - Method to remove cookie.
+3. **fetch** - Method to re-fetch cookie value.

src/useCookie/__tests__/dom.tsx

@@ -0,0 +1,132 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { act, renderHook } from '@testing-library/react-hooks/dom';
+import * as Cookies from 'js-cookie';
+import { IUseCookieReturn, useCookie } from '../..';
+import SpyInstance = jest.SpyInstance;
+
+describe('useCookie', () => {
+  let getSpy: SpyInstance<{ [p: string]: string }, []>;
+  let setSpy: SpyInstance<
+    string | undefined,
+    [
+      name: string,
+      value: string | Record<string, any>,
+      options?: Cookies.CookieAttributes | undefined
+    ]
+  >;
+  let removeSpy: SpyInstance<void, [name: string, options?: Cookies.CookieAttributes | undefined]>;
+
+  beforeAll(() => {
+    getSpy = jest.spyOn(Cookies, 'get');
+    setSpy = jest.spyOn(Cookies, 'set');
+    removeSpy = jest.spyOn(Cookies, 'remove');
+  });
+
+  afterAll(() => {
+    getSpy.mockRestore();
+    setSpy.mockRestore();
+    removeSpy.mockRestore();
+  });
+
+  beforeEach(() => {
+    getSpy.mockClear();
+    setSpy.mockClear();
+    removeSpy.mockClear();
+  });
+
+  it('should be defined', () => {
+    expect(useCookie).toBeDefined();
+  });
+
+  it('should render', () => {
+    const { result } = renderHook(() => useCookie('react-hookz'));
+    expect(result.error).toBeUndefined();
+  });
+
+  it('should return undefined on first render', () => {
+    const { result } = renderHook(() => useCookie('react-hookz'));
+    expect((result.all[0] as IUseCookieReturn)[0]).toBeUndefined();
+  });
+
+  it('should return null if cookie not exists', () => {
+    const { result } = renderHook(() => useCookie('react-hookz'));
+    expect(result.current[0]).toBe(null);
+    expect(getSpy).toBeCalledWith('react-hookz');
+  });
+
+  it('should set the cookie value on call to `set`', () => {
+    const { result } = renderHook(() => useCookie('react-hookz'));
+
+    expect(result.current[0]).toBe(null);
+    act(() => {
+      result.current[1]('awesome');
+    });
+    expect(result.current[0]).toBe('awesome');
+    expect(setSpy).toBeCalledWith('react-hookz', 'awesome', undefined);
+    Cookies.remove('react-hookz');
+  });
+
+  it('should remove cookie value on call to `remove`', () => {
+    const { result } = renderHook(() => useCookie('react-hookz'));
+
+    expect(result.current[0]).toBe(null);
+    act(() => {
+      result.current[1]('awesome');
+    });
+    expect(result.current[0]).toBe('awesome');
+
+    act(() => {
+      result.current[2]();
+    });
+    expect(result.current[0]).toBe(null);
+    expect(removeSpy).toBeCalledWith('react-hookz', undefined);
+    Cookies.remove('react-hookz');
+  });
+
+  it('should re-fetch cookie value on call to `fetch`', () => {
+    const { result } = renderHook(() => useCookie('react-hookz'));
+
+    Cookies.set('react-hookz', 'rulez');
+    expect(result.current[0]).toBe(null);
+    act(() => {
+      result.current[3]();
+    });
+    expect(result.current[0]).toBe('rulez');
+
+    Cookies.remove('react-hookz');
+  });
+
+  it('should be synchronized between several hooks managing same key', () => {
+    const { result: res1 } = renderHook(() => useCookie('react-hookz'));
+    const { result: res2 } = renderHook(() => useCookie('react-hookz'));
+
+    expect(res1.current[0]).toBe(null);
+    expect(res2.current[0]).toBe(null);
+
+    act(() => {
+      res1.current[1]('awesome');
+    });
+
+    expect(res1.current[0]).toBe('awesome');
+    expect(res2.current[0]).toBe('awesome');
+
+    act(() => {
+      res2.current[2]();
+    });
+
+    expect(res1.current[0]).toBe(null);
+    expect(res2.current[0]).toBe(null);
+  });
+
+  it('should return stable methods', () => {
+    const { result, rerender } = renderHook(() => useCookie('react-hookz'));
+
+    const res1 = result.current;
+
+    rerender();
+
+    expect(res1[1]).toBe(result.current[1]);
+    expect(res1[2]).toBe(result.current[2]);
+    expect(res1[3]).toBe(result.current[3]);
+  });
+});

src/useCookie/__tests__/ssr.tsx

@@ -0,0 +1,18 @@
+import { renderHook } from '@testing-library/react-hooks/server';
+import { useCookie } from '../..';
+
+describe('useCookie', () => {
+  it('should be defined', () => {
+    expect(useCookie).toBeDefined();
+  });
+
+  it('should render', () => {
+    const { result } = renderHook(() => useCookie('react-hookz'));
+    expect(result.error).toBeUndefined();
+  });
+
+  it('should return undefined ', () => {
+    const { result } = renderHook(() => useCookie('react-hookz'));
+    expect(result.current[0]).toBeUndefined();
+  });
+});