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

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

Node.js Installation

$ yarn add react-store-context-hooks
# or
$ 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)

import { isEmpty, useStore, useStores, withStore } from 'react-store-context-hooks';
import { render } from 'react-dom';
import { useEffect } from 'react';

const ComponentA = () => {
  const [value, setValue, delValue] = useStore('key');

  useEffect(() => {
    if (isEmpty(value)) {
      setValue({ key: {
        nested: 'value-from-A',
      } });
    }
    return () => delValue();
  }, []);

  return <>{JSON.stringify(value)}</>;
};

const ComponentB = () => {
  const [value, setValue, delValue] = useStore('key');

  useEffect(() => {
    if (isEmpty(value)) {
      setValue({ key: {
        nested: 'value-from-B',
      } });
    }
    return () => delValue();
  }, []);

  return <>{JSON.stringify(value)}</>;
};

const App = withStore(() => {
  const { setStores } = useStores();

  useEffect(() => {
    setStores({
      key: {
        nested: 'value',
      },
    });
  }, []);

  return (
    <>
      <ComponentA />
      <ComponentB />
    </>
  );
});

render(<App />, document.querySelector('#root'));

Example (Different React Context with localStorage)

import { render } from 'react-dom';
import { useEffect } from 'react';
import { useLocalStore, useLocalStores }  from 'react-store-context-hooks';

const ComponentA = () => {
  const { setStores } = useLocalStores();

  useEffect(() => {
    setStores({
      key: 'value',
    });
  }, []);

  return null;
};

const ComponentB = () => {
  const [value] = useLocalStore('key');
  return <>{JSON.stringify(value)}</>;
};

const ComponentC = () => {
  const [value] = useLocalStore('key');
  return <>{JSON.stringify(value)}</>;
};

render(<><ComponentA /><ComponentB /><ComponentC /></>, document.querySelector('#root'));

Example (Different React Context with sessionStorage)

import { render } from 'react-dom';
import { useEffect } from 'react';
import { useSessionStore, useSessionStores }  from 'react-store-context-hooks';

const ComponentA = () => {
  const { setStores } = useSessionStores();

  useEffect(() => {
    setStores({
      key: 'value',
    });
  }, []);

  return null;
};

const ComponentB = () => {
  const [value] = useSessionStore('key');
  return <>{JSON.stringify(value)}</>;
};

const ComponentC = () => {
  const [value] = useSessionStore('key');
  return <>{JSON.stringify(value)}</>;
};

render(<><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

import { isEmpty } from 'react-store-context-hooks';

let flag = isEmpty('');
// flag = true
flag = isEmpty('value');
// 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

import { useEffect } from 'react';
import { useLocalStore }  from 'react-store-context-hooks';

// Simulate an existing value
localStorage.setItem('key', JSON.stringify('local-default'));

const ComponentA = () => {
  const [value, setValue, delValue] = useLocalStore('key', 'default');
  // value = 'local-default'
  // localStorage.getItem('key') = '"local-default"'

  useEffect(() => {
    setValue('value');
    // value = 'value'
    // localStorage.getItem('key') = '"value"'

    return () => {
      delValue();
      // value = 'default'
      // localStorage.getItem('key') = null
    };
  }, []);

  return null;
};

const ComponentB = () => {
  const [value] = useLocalStore('key');
  // value = 'local-default'
  // localStorage.getItem('key') = '"local-default"'

  // After ComponentA setValue('value');
  // value = 'value'
  // localStorage.getItem('key') = '"value"'

  // After ComponentA delValue();
  // value = undefined
  // localStorage.getItem('key') = null

  return null;
};

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

import { useEffect } from 'react';
import { useLocalStore, useLocalStores }  from 'react-store-context-hooks';

const ComponentA = () => {
  const { setStores } = useLocalStores();

  useEffect(() => {
    setStores({
      key1: 'value1',
      key2: {
        nested: 'value',
      },
    });
  }, []);

  return null;
};

const ComponentB = () => {
  const [value1] = useLocalStore('key1');
  const [value2] = useLocalStore('key2');

  // value1 = 'value1'
  // value2 = {
  //   nested: 'value',
  // }
  // localStorage.getItem('key1') = '"value1"'
  // localStorage.getItem('key2') = '{"nested":"value"}'

  return <>{JSON.stringify({ value1, value2 })}</>;
};

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

import { useEffect } from 'react';
import { useSessionStore }  from 'react-store-context-hooks';

// Simulate an existing value
sessionStorage.setItem('key', JSON.stringify('session-default'));

const ComponentA = () => {
  const [value, setValue, delValue] = useSessionStore('key', 'default');
  // value = 'session-default'
  // sessionStorage.getItem('key') = '"session-default"'

  useEffect(() => {
    setValue('value');
    // value = 'value'
    // sessionStorage.getItem('key') = '"value"'

    return () => {
      delValue();
      // value = 'default'
      // sessionStorage.getItem('key') = null
    };
  }, []);

  return null;
};

const ComponentB = () => {
  const [value] = useSessionStore('key');
  // value = 'session-default'
  // sessionStorage.getItem('key') = '"session-default"'

  // After ComponentA setValue('value');
  // value = 'value'
  // sessionStorage.getItem('key') = '"value"'

  // After ComponentA delValue();
  // value = undefined
  // sessionStorage.getItem('key') = null

  return null;
};

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

import { useEffect } from 'react';
import { useSessionStore, useSessionStores }  from 'react-store-context-hooks';

const ComponentA = () => {
  const { setStores } = useSessionStores();

  useEffect(() => {
    setStores({
      key1: 'value1',
      key2: {
        nested: 'value',
      },
    });
  }, []);

  return null;
};

const ComponentB = () => {
  const [value1] = useSessionStore('key1');
  const [value2] = useSessionStore('key2');

  // value1 = 'value1'
  // value2 = {
  //   nested: 'value',
  // }
  // sessionStorage.getItem('key1') = '"value1"'
  // sessionStorage.getItem('key2') = '{"nested":"value"}'

  return <>{JSON.stringify({ value1, value2 })}</>;
};

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)

import { useEffect } from 'react';
import { useStore }  from 'react-store-context-hooks';

const Component = () => {
  const [value, setValue, delValue] = useStore('key', 'default');
  // value = 'default'

  useEffect(() => {
    setValue('value');
    // value = 'value'

    return () => {
      delValue();
      // value = 'default'
    };
  }, []);

  return null;
};

Example (With localStorage)

import { useEffect } from 'react';
import { useStore }  from 'react-store-context-hooks';

// Simulate an existing value
localStorage.setItem('key', JSON.stringify('local-default'));

const Component = () => {
  const [value, setValue, delValue] = useStore('key', 'default', localStorage);
  // value = 'local-default'
  // localStorage.getItem('key') = '"local-default"'

  useEffect(() => {
    setValue('value');
    // value = 'value'
    // localStorage.getItem('key') = '"value"'

    return () => {
      delValue();
      // value = 'default'
      // localStorage.getItem('key') = null
    };
  }, []);

  return null;
};

Example (With sessionStorage)

import { useEffect } from 'react';
import { useStore }  from 'react-store-context-hooks';

// Simulate an existing value
sessionStorage.setItem('key', JSON.stringify('session-default'));

const Component = () => {
  const [value, setValue, delValue] = useStore('key', 'default', sessionStorage);
  // value = 'session-default'
  // sessionStorage.getItem('key') = '"session-default"'

  useEffect(() => {
    setValue('value');
    // value = 'value'
    // sessionStorage.getItem('key') = '"value"'

    return () => {
      delValue();
      // value = 'default'
      // sessionStorage.getItem('key') = null
    };
  }, []);

  return null;
};

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)

import { useEffect } from 'react';
import { useStore, useStores }  from 'react-store-context-hooks';

const Component = () => {
  const [value1] = useStore('key1');
  const [value2] = useStore('key2');
  const { setStores } = useStores();

  useEffect(() => {
    setStores({
      key1: 'value1',
      key2: {
        nested: 'value',
      },
    });
  }, []);

  // value1 = 'value1'
  // value2 = {
  //   nested: 'value',
  // }

  return <>{JSON.stringify({ value1, value2 })}</>;
};

Example (With localStorage)

import { useEffect } from 'react';
import { useStore, useStores }  from 'react-store-context-hooks';

const Component = () => {
  const [value1] = useStore('key1', undefined, localStorage);
  const [value2] = useStore('key2', undefined, localStorage);
  const { setStores } = useStores(localStorage);

  useEffect(() => {
    setStores({
      key1: 'value1',
      key2: {
        nested: 'value',
      },
    });
  }, []);

  // value1 = 'value1'
  // value2 = {
  //   nested: 'value',
  // }
  // localStorage.getItem('key1') = '"value1"'
  // localStorage.getItem('key2') = '{"nested":"value"}'

  return <>{JSON.stringify({ value1, value2 })}</>;
};

Example (With sessionStorage)

import { useEffect } from 'react';
import { useStore, useStores }  from 'react-store-context-hooks';

const Component = () => {
  const [value1] = useStore('key1', undefined, sessionStorage);
  const [value2] = useStore('key2', undefined, sessionStorage);
  const { setStores } = useStores(sessionStorage);

  useEffect(() => {
    setStores({
      key1: 'value1',
      key2: {
        nested: 'value',
      },
    });
  }, []);

  // value1 = 'value1'
  // value2 = {
  //   nested: 'value',
  // }
  // sessionStorage.getItem('key1') = '"value1"'
  // sessionStorage.getItem('key2') = '{"nested":"value"}'

  return <>{JSON.stringify({ value1, value2 })}</>;
};

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)

import { render }  from 'react-dom';
import { withStore }  from 'react-store-context-hooks';

const Component = (props) => {
  return <>{JSON.stringify(props)}</>;
};

const ComponentWithStore = withStore(Component);

render(<ComponentWithStore attr1="val1" attr2="val2" />, document.querySelector('#root'));

Example (Wrap a component on-the-fly)

import { render }  from 'react-dom';
import { withStore }  from 'react-store-context-hooks';

const ComponentWithStore = withStore((props) => {
  return <>{JSON.stringify(props)}</>;
});

render(<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.

$ yarn
# or
$ npm install

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

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

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

Run benchmark tests only:

$ yarn test:bench
# or
$ npm run test:bench

Run static type tests only:

$ yarn test:flow
# or
$ npm run test:flow

Run leak tests only:

$ yarn test:leak
# or
$ npm run test:leak

Run lint tests only:

$ yarn test:lint
# or
$ npm run test:lint

Run unit tests only:

$ yarn test:unit
# or
$ npm run test:unit

Run Budles, Documentation, and Typescript definition Builds

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

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

Run bundles build only:

$ yarn build:bundles
# or
$ npm run build:bundles

Run documentation build only:

$ yarn build:docs
# or
$ npm run build:docs

Run Typescript definition build only:

$ yarn build:ts
# or
$ 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.