React Store Context Hooks

Provides various data store hooks that allow functional components to share the application state within the same React Context or different React Context using persistent storage.

CDN Link

1<script crossorigin src="https://unpkg.com/react-store-context-hook/index.umd.js"></script>

Node.js Installation

1$ yarn add react-store-context-hooks
2# or
3$ npm install --save react-store-context-hooks

API Reference

Provides various data store hooks that allow functional components to share the application state within the same React Context or different React Context using persistent storage.

Requires: module:react
Example (Within the same React Context)

1import { isEmpty, useStore, useStores, withStore } from 'react-store-context-hooks';
2import { render } from 'react-dom';
3import { useEffect } from 'react';
4
5const ComponentA = () => {
6  const [value, setValue, delValue] = useStore('key');
7
8  useEffect(() => {
9    if (isEmpty(value)) {
10      setValue({ key: {
11        nested: 'value-from-A',
12      } });
13    }
14    return () => delValue();
15  }, []);
16
17  return <>{JSON.stringify(value)}</>;
18};
19
20const ComponentB = () => {
21  const [value, setValue, delValue] = useStore('key');
22
23  useEffect(() => {
24    if (isEmpty(value)) {
25      setValue({ key: {
26        nested: 'value-from-B',
27      } });
28    }
29    return () => delValue();
30  }, []);
31
32  return <>{JSON.stringify(value)}</>;
33};
34
35const App = withStore(() => {
36  const { setStores } = useStores();
37
38  useEffect(() => {
39    setStores({
40      key: {
41        nested: 'value',
42      },
43    });
44  }, []);
45
46  return (
47    <>
48      <ComponentA />
49      <ComponentB />
50    </>
51  );
52});
53
54render(<App />, document.querySelector('#root'));

Example (Different React Context with localStorage)

1import { render } from 'react-dom';
2import { useEffect } from 'react';
3import { useLocalStore, useLocalStores }  from 'react-store-context-hooks';
4
5const ComponentA = () => {
6  const { setStores } = useLocalStores();
7
8  useEffect(() => {
9    setStores({
10      key: 'value',
11    });
12  }, []);
13
14  return null;
15};
16
17const ComponentB = () => {
18  const [value] = useLocalStore('key');
19  return <>{JSON.stringify(value)}</>;
20};
21
22const ComponentC = () => {
23  const [value] = useLocalStore('key');
24  return <>{JSON.stringify(value)}</>;
25};
26
27render(<><ComponentA /><ComponentB /><ComponentC /></>, document.querySelector('#root'));

Example (Different React Context with sessionStorage)

1import { render } from 'react-dom';
2import { useEffect } from 'react';
3import { useSessionStore, useSessionStores }  from 'react-store-context-hooks';
4
5const ComponentA = () => {
6  const { setStores } = useSessionStores();
7
8  useEffect(() => {
9    setStores({
10      key: 'value',
11    });
12  }, []);
13
14  return null;
15};
16
17const ComponentB = () => {
18  const [value] = useSessionStore('key');
19  return <>{JSON.stringify(value)}</>;
20};
21
22const ComponentC = () => {
23  const [value] = useSessionStore('key');
24  return <>{JSON.stringify(value)}</>;
25};
26
27render(<><ComponentA /><ComponentB /><ComponentC /></>, document.querySelector('#root'));

• react-store-context-hooks
  • .isEmpty(value) ⇒ boolean
  • .useLocalStore(key, defaultValue) ⇒ Array.<mixed, function(value): void, function(): void>
  • .useLocalStores() ⇒ Object.<{setStores: function(data): void}>
  • .useSessionStore(key, defaultValue) ⇒ Array.<mixed, function(value): void, function(): void>
  • .useSessionStores() ⇒ Object.<{setStores: function(data): void}>
  • .useStore(key, defaultValue, persistence) ⇒ Array.<mixed, function(value): void, function(): void>
  • .useStores(persistence) ⇒ Object.<{setStores: function(data): void}>
  • .withStores(Component) ⇒ React.ComponentType

react-store-context-hooks.isEmpty(value) ⇒ boolean

A data store hook allows a functional component to validate given value emptiness.

Kind: static method of react-store-context-hooks
Returns: boolean - Value emptiness flag.

Param	Type	Description
value	mixed	The value to be checked for emptiness.

Example

1import { isEmpty } from 'react-store-context-hooks';
2
3let flag = isEmpty('');
4// flag = true
5flag = isEmpty('value');
6// flag = false

react-store-context-hooks.useLocalStore(key, defaultValue) ⇒ Array.<mixed, function(value): void, function(): void>

A data store hook allows any components on different React Context to share the application state using localStorage as the persistent storage.

The mutator will persist the value with JSON string format in the persistent storage.

Kind: static method of react-store-context-hooks
Returns: Array.<mixed, function(value): void, function(): void> - Store value, update, and remove callbacks.

Param	Type	Description
key	string	The store key.
defaultValue	mixed	The store default value.

Example

1import { useEffect } from 'react';
2import { useLocalStore }  from 'react-store-context-hooks';
3
4// Simulate an existing value
5localStorage.setItem('key', JSON.stringify('local-default'));
6
7const ComponentA = () => {
8  const [value, setValue, delValue] = useLocalStore('key', 'default');
9  // value = 'local-default'
10  // localStorage.getItem('key') = '"local-default"'
11
12  useEffect(() => {
13    setValue('value');
14    // value = 'value'
15    // localStorage.getItem('key') = '"value"'
16
17    return () => {
18      delValue();
19      // value = 'default'
20      // localStorage.getItem('key') = null
21    };
22  }, []);
23
24  return null;
25};
26
27const ComponentB = () => {
28  const [value] = useLocalStore('key');
29  // value = 'local-default'
30  // localStorage.getItem('key') = '"local-default"'
31
32  // After ComponentA setValue('value');
33  // value = 'value'
34  // localStorage.getItem('key') = '"value"'
35
36  // After ComponentA delValue();
37  // value = undefined
38  // localStorage.getItem('key') = null
39
40  return null;
41};

react-store-context-hooks.useLocalStores() ⇒ Object.<{setStores: function(data): void}>

A data store hook allows any components on different React Context to update multiple stores at once and share the application state using localStorage as the persistent storage.

The mutator will persist the values with JSON string format in the persistent storage.

Kind: static method of react-store-context-hooks
Returns: Object.<{setStores: function(data): void}> - Multiple stores update callback.
Example

1import { useEffect } from 'react';
2import { useLocalStore, useLocalStores }  from 'react-store-context-hooks';
3
4const ComponentA = () => {
5  const { setStores } = useLocalStores();
6
7  useEffect(() => {
8    setStores({
9      key1: 'value1',
10      key2: {
11        nested: 'value',
12      },
13    });
14  }, []);
15
16  return null;
17};
18
19const ComponentB = () => {
20  const [value1] = useLocalStore('key1');
21  const [value2] = useLocalStore('key2');
22
23  // value1 = 'value1'
24  // value2 = {
25  //   nested: 'value',
26  // }
27  // localStorage.getItem('key1') = '"value1"'
28  // localStorage.getItem('key2') = '{"nested":"value"}'
29
30  return <>{JSON.stringify({ value1, value2 })}</>;
31};

react-store-context-hooks.useSessionStore(key, defaultValue) ⇒ Array.<mixed, function(value): void, function(): void>

A data store hook allows any components on different React Context to share the application state using sessionStorage as the persistent storage.

The mutator will persist the value with JSON string format in the persistent storage.

Kind: static method of react-store-context-hooks
Returns: Array.<mixed, function(value): void, function(): void> - Store value, update, and remove callbacks.

Param	Type	Description
key	string	The store key.
defaultValue	mixed	The store default value.

Example

1import { useEffect } from 'react';
2import { useSessionStore }  from 'react-store-context-hooks';
3
4// Simulate an existing value
5sessionStorage.setItem('key', JSON.stringify('session-default'));
6
7const ComponentA = () => {
8  const [value, setValue, delValue] = useSessionStore('key', 'default');
9  // value = 'session-default'
10  // sessionStorage.getItem('key') = '"session-default"'
11
12  useEffect(() => {
13    setValue('value');
14    // value = 'value'
15    // sessionStorage.getItem('key') = '"value"'
16
17    return () => {
18      delValue();
19      // value = 'default'
20      // sessionStorage.getItem('key') = null
21    };
22  }, []);
23
24  return null;
25};
26
27const ComponentB = () => {
28  const [value] = useSessionStore('key');
29  // value = 'session-default'
30  // sessionStorage.getItem('key') = '"session-default"'
31
32  // After ComponentA setValue('value');
33  // value = 'value'
34  // sessionStorage.getItem('key') = '"value"'
35
36  // After ComponentA delValue();
37  // value = undefined
38  // sessionStorage.getItem('key') = null
39
40  return null;
41};

react-store-context-hooks.useSessionStores() ⇒ Object.<{setStores: function(data): void}>

A data store hook allows any components on different React Context to update multiple stores at once and share the application state using sessionStorage as the persistent storage.

The mutator will persist the values with JSON string format in the persistent storage.

Kind: static method of react-store-context-hooks
Returns: Object.<{setStores: function(data): void}> - Multiple stores update callback.
Example

1import { useEffect } from 'react';
2import { useSessionStore, useSessionStores }  from 'react-store-context-hooks';
3
4const ComponentA = () => {
5  const { setStores } = useSessionStores();
6
7  useEffect(() => {
8    setStores({
9      key1: 'value1',
10      key2: {
11        nested: 'value',
12      },
13    });
14  }, []);
15
16  return null;
17};
18
19const ComponentB = () => {
20  const [value1] = useSessionStore('key1');
21  const [value2] = useSessionStore('key2');
22
23  // value1 = 'value1'
24  // value2 = {
25  //   nested: 'value',
26  // }
27  // sessionStorage.getItem('key1') = '"value1"'
28  // sessionStorage.getItem('key2') = '{"nested":"value"}'
29
30  return <>{JSON.stringify({ value1, value2 })}</>;
31};

react-store-context-hooks.useStore(key, defaultValue, persistence) ⇒ Array.<mixed, function(value): void, function(): void>

A data store hook allows any components within the same React Context to share the application state.

The accessor will validate the value in the data store first before accessing the given persistent storage. If both data store and persistent storage values are empty, it will use the default value.

The mutators will persist the value with JSON string format in the persistent storage.

Kind: static method of react-store-context-hooks
Returns: Array.<mixed, function(value): void, function(): void> - Store value, update, and remove callbacks.

Param	Type	Description
key	string	The store key.
defaultValue	mixed	The store default value.
persistence	Storage	The data persistence choices: localStorage, sessionStorage.

Example (Without persistent storage)

1import { useEffect } from 'react';
2import { useStore }  from 'react-store-context-hooks';
3
4const Component = () => {
5  const [value, setValue, delValue] = useStore('key', 'default');
6  // value = 'default'
7
8  useEffect(() => {
9    setValue('value');
10    // value = 'value'
11
12    return () => {
13      delValue();
14      // value = 'default'
15    };
16  }, []);
17
18  return null;
19};

Example (With localStorage)

1import { useEffect } from 'react';
2import { useStore }  from 'react-store-context-hooks';
3
4// Simulate an existing value
5localStorage.setItem('key', JSON.stringify('local-default'));
6
7const Component = () => {
8  const [value, setValue, delValue] = useStore('key', 'default', localStorage);
9  // value = 'local-default'
10  // localStorage.getItem('key') = '"local-default"'
11
12  useEffect(() => {
13    setValue('value');
14    // value = 'value'
15    // localStorage.getItem('key') = '"value"'
16
17    return () => {
18      delValue();
19      // value = 'default'
20      // localStorage.getItem('key') = null
21    };
22  }, []);
23
24  return null;
25};

Example (With sessionStorage)

1import { useEffect } from 'react';
2import { useStore }  from 'react-store-context-hooks';
3
4// Simulate an existing value
5sessionStorage.setItem('key', JSON.stringify('session-default'));
6
7const Component = () => {
8  const [value, setValue, delValue] = useStore('key', 'default', sessionStorage);
9  // value = 'session-default'
10  // sessionStorage.getItem('key') = '"session-default"'
11
12  useEffect(() => {
13    setValue('value');
14    // value = 'value'
15    // sessionStorage.getItem('key') = '"value"'
16
17    return () => {
18      delValue();
19      // value = 'default'
20      // sessionStorage.getItem('key') = null
21    };
22  }, []);
23
24  return null;
25};

react-store-context-hooks.useStores(persistence) ⇒ Object.<{setStores: function(data): void}>

A data store hook allows a functional component to update multiple stores at once and share the application state with any components within the same React Context.

The mutator will persist the values with JSON string format in the persistent storage.

Kind: static method of react-store-context-hooks
Returns: Object.<{setStores: function(data): void}> - Multiple stores update callback.

Param	Type	Description
persistence	Storage	The data persistence choices: localStorage, sessionStorage.

Example (Without persistent storage)

1import { useEffect } from 'react';
2import { useStore, useStores }  from 'react-store-context-hooks';
3
4const Component = () => {
5  const [value1] = useStore('key1');
6  const [value2] = useStore('key2');
7  const { setStores } = useStores();
8
9  useEffect(() => {
10    setStores({
11      key1: 'value1',
12      key2: {
13        nested: 'value',
14      },
15    });
16  }, []);
17
18  // value1 = 'value1'
19  // value2 = {
20  //   nested: 'value',
21  // }
22
23  return <>{JSON.stringify({ value1, value2 })}</>;
24};

Example (With localStorage)

1import { useEffect } from 'react';
2import { useStore, useStores }  from 'react-store-context-hooks';
3
4const Component = () => {
5  const [value1] = useStore('key1', undefined, localStorage);
6  const [value2] = useStore('key2', undefined, localStorage);
7  const { setStores } = useStores(localStorage);
8
9  useEffect(() => {
10    setStores({
11      key1: 'value1',
12      key2: {
13        nested: 'value',
14      },
15    });
16  }, []);
17
18  // value1 = 'value1'
19  // value2 = {
20  //   nested: 'value',
21  // }
22  // localStorage.getItem('key1') = '"value1"'
23  // localStorage.getItem('key2') = '{"nested":"value"}'
24
25  return <>{JSON.stringify({ value1, value2 })}</>;
26};

Example (With sessionStorage)

1import { useEffect } from 'react';
2import { useStore, useStores }  from 'react-store-context-hooks';
3
4const Component = () => {
5  const [value1] = useStore('key1', undefined, sessionStorage);
6  const [value2] = useStore('key2', undefined, sessionStorage);
7  const { setStores } = useStores(sessionStorage);
8
9  useEffect(() => {
10    setStores({
11      key1: 'value1',
12      key2: {
13        nested: 'value',
14      },
15    });
16  }, []);
17
18  // value1 = 'value1'
19  // value2 = {
20  //   nested: 'value',
21  // }
22  // sessionStorage.getItem('key1') = '"value1"'
23  // sessionStorage.getItem('key2') = '{"nested":"value"}'
24
25  return <>{JSON.stringify({ value1, value2 })}</>;
26};

react-store-context-hooks.withStores(Component) ⇒ React.ComponentType

A data store hook wraps a component with a store context provider.

Kind: static method of react-store-context-hooks
Returns: React.ComponentType - The wrapped component with store provider.

Param	Type	Description
Component	React.ComponentType	The component to be wrapped with the store provider.

Example (Wrap an existing component)

1import { render }  from 'react-dom';
2import { withStore }  from 'react-store-context-hooks';
3
4const Component = (props) => {
5  return <>{JSON.stringify(props)}</>;
6};
7
8const ComponentWithStore = withStore(Component);
9
10render(<ComponentWithStore attr1="val1" attr2="val2" />, document.querySelector('#root'));

Example (Wrap a component on-the-fly)

1import { render }  from 'react-dom';
2import { withStore }  from 'react-store-context-hooks';
3
4const ComponentWithStore = withStore((props) => {
5  return <>{JSON.stringify(props)}</>;
6});
7
8render(<ComponentWithStore attr1="val1" attr2="val2" />, document.querySelector('#root'));

Development Dependencies

You will need to install Node.js as a local development dependency. The npm package manager comes bundled with all recent releases of Node.js. You can also use yarn as a package manager.

yarn or npm install will attempt to resolve any npm module dependencies that have been declared in the project’s package.json file, installing them into the node_modules folder.

1$ yarn
2# or
3$ npm install

Run Benchmark, Flow, Leak, Lint, and Unit Tests

To make sure we did not break anything, let's run all the tests:

1$ yarn test
2# or
3$ npm run test:lint; npm run test:flow; npm run test:unit; npm run test:bench; npm run test:leak

Run benchmark tests only:

1$ yarn test:bench
2# or
3$ npm run test:bench

Run static type tests only:

1$ yarn test:flow
2# or
3$ npm run test:flow

Run leak tests only:

1$ yarn test:leak
2# or
3$ npm run test:leak

Run lint tests only:

1$ yarn test:lint
2# or
3$ npm run test:lint

Run unit tests only:

1$ yarn test:unit
2# or
3$ npm run test:unit

Run Budles, Documentation, and Typescript definition Builds

To generate distribution bundles, documentation, and Typescript definition, run:

1$ yarn build
2# or
3$ npm run build:docs; npm run build:bundles; npm run build:ts

Run bundles build only:

1$ yarn build:bundles
2# or
3$ npm run build:bundles

Run documentation build only:

1$ yarn build:docs
2# or
3$ npm run build:docs

Run Typescript definition build only:

1$ yarn build:ts
2# or
3$ npm run build:ts

Contributing

If you would like to contribute code to React Store Context Hooks repository, you can do so through GitHub by forking the repository and sending a pull request.

If you do not agree to Contribution Agreement, do not contribute any code to React Store Context Hooks repository.

When submitting code, please make every effort to follow existing conventions and style in order to keep the code as readable as possible. Please also include appropriate test cases.

That's it! Thank you for your contribution!

License

Copyright (c) 2019 - 2021 Richard Huang.

This utility is free software, licensed under: Mozilla Public License (MPL-2.0).

Documentation and other similar content are provided under Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.