restash

Version:

Simple React context store, set it or get it.

97 lines (83 loc) • 42.2 kB

HTML

<!DOCTYPE html><html class="default"><head><meta charSet="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>Restash</title><meta name="description" content="Documentation for Restash"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="assets/style.css"/><link rel="stylesheet" href="assets/highlight.css"/><script async src="assets/search.js" id="search-script"></script></head><body><script>document.body.classList.add(localStorage.getItem("tsd-theme") || "os")</script><header><div class="tsd-page-toolbar"><div class="container"><div class="table-wrap"><div class="table-cell" id="tsd-search" data-base="."><div class="field"><label for="tsd-search-field" class="tsd-widget search no-caption">Search</label><input type="text" id="tsd-search-field"/></div><ul class="results"><li class="state loading">Preparing search index...</li><li class="state failure">The search index is not available</li></ul><a href="index.html" class="title">Restash</a></div><div class="table-cell" id="tsd-widgets"><div id="tsd-filter"><a href="#" class="tsd-widget options no-caption" data-toggle="options">Options</a><div class="tsd-filter-group"><div class="tsd-select" id="tsd-filter-visibility">All<ul class="tsd-select-list"><li data-value="public">Public</li><li data-value="protected">Public/Protected</li><li data-value="private" class="selected">All</li></ul></div> <input type="checkbox" id="tsd-filter-inherited" checked/><label class="tsd-widget" for="tsd-filter-inherited">Inherited</label><input type="checkbox" id="tsd-filter-externals" checked/><label class="tsd-widget" for="tsd-filter-externals">Externals</label></div></div><a href="#" class="tsd-widget menu no-caption" data-toggle="menu">Menu</a></div></div></div></div><div class="tsd-page-title"><div class="container"><h1>Restash</h1></div></div></header><div class="container container-main"><div class="row"><div class="col-8 col-content"><div class="tsd-panel tsd-typography"> <a href="http://github.com/blujedis/restash"><img src="https://raw.githubusercontent.com/blujedis/restash/master/fixtures/logo.png" width="225" /></a> Restash is a simple <a href="https://reactjs.org/">React</a> context store which uses <a href="https://reactjs.org/docs/hooks-reference.html#usereducer">useReducer</a> behind the scenes. The API is broken into components so that you can either use the default implementation or build up your own. <a href="#new" id="new" style="color: inherit; text-decoration: none;"> <h2>NEW!!</h2> </a> Restash now supports dot notation for properties! The below will give you <pre><code class="language-tsx">// Consider this state const state = { person: { firstName: 'Milton', lastName: 'Waddams', numbers: { home: '8985551212', mobile: '8985551234' } } }; const [nestedState, setNestedState] = useStore('person.numbers.mobile'); // Nested state here will be equal to '8985551234'; // Update it as follows. const updateState = (value) => { setNestedState(value); }; </code></pre> <a href="#getting-started" id="getting-started" style="color: inherit; text-decoration: none;"> <h2>Getting Started</h2> </a> <pre><code class="language-sh">$ npm install restash -s </code></pre> OR <pre><code class="language-sh">$ yarn add restash </code></pre> <a href="#restash" id="restash" style="color: inherit; text-decoration: none;"> <h2>Restash</h2> </a> It's best or most flexibile if you break up your setup in a few small parts. Exposing the Provider to wrap your application, a store or init file to configure your store and finally using the exposed hook. <a href="#initialize-restash" id="initialize-restash" style="color: inherit; text-decoration: none;"> <h3>Initialize Restash</h3> </a> After providing your context above initialize Restash in a file called for example <code>restash.tsx</code> for example. Then call <code>createRestash</code> passing our options and then export our new Restash store. <pre><code class="language-tsx">import { createRestash } from 'restash'; const initialState = { firstName: 'Milton', lastName: 'Waddams' }; const { Provider, useStore } = createRestash({initialState}); export { Provider, useStore } </code></pre> <a href="#provide-context" id="provide-context" style="color: inherit; text-decoration: none;"> <h3>Provide Context</h3> </a> Using our export from above expose the <code>Provider</code> and wrap our application so it knows about our context. <pre><code class="language-tsx">import { Provider } from './restash'; // NOTE: you can also provide the initialState and reducer // as params to your provider if you wish. If you provide // a reducer or inital state in your "createRestash" init // options those will be favored over params here. const App = () => { return ( <Provider> // Your App Here </Provider> ); } </code></pre> <a href="#using-hook" id="using-hook" style="color: inherit; text-decoration: none;"> <h3>Using Hook</h3> </a> We can now use our hook that's been created by our new Restash store. <pre><code class="language-tsx">import { useStore } from './restash'; const Home = () => { const [state, dispatch] = useStore(); const changeState = (key) => { return (e) => { dispatch({ [key]: e.target.value }); }; }; return ( <div> <h2 style={{ marginBottom: '12px' }}>Use Store</h2> <hr style={{ marginBottom: '20px' }} /> <p style={{ padding: '12px', backgroundColor: '#eee', width: '50%' }}> Simple example wiring up input elements to state values changing the state on blur of each field. </p> <div style={{ marginBottom: '12px' }}> First Name: <input type="text" onBlur={changeState('firstName')} defaultValue={state.firstName} /> </div> <div style={{ marginBottom: '12px' }}> Last Name: <input type="text" onBlur={changeState('lastName')} defaultValue={state.lastName} /> </div> <h3 style={{marginTop: '32px'}}>Current State</h3> <pre> {JSON.stringify(state, null, 2)} </pre> </div> ); }; </code></pre> <a href="#middleware-persistence-amp-statuses" id="middleware-persistence-amp-statuses" style="color: inherit; text-decoration: none;"> <h3>Middleware, Persistence & Statuses</h3> </a> Initializing with middleware is very similar to <a href="https://redux.js.org/">Redux</a>. You create your middleware then call a helper method called applyMiddleware then pass to your options. By default Restash supports thunks which are useful for async tasks. Restash currently comes with only one middleware. That being a simple console logger. Redux middleware should work however in many cases. <pre><code class="language-tsx">import { createRestash, logger } from 'restash'; const initialState = { firstName: 'Milton', lastName: 'Waddams' }; // The only logger options are that of styles // for colorizing and styling in your console. // see source for details. const middleware = applyMiddleware(logger()); const options { // The initial data state. initialState, // The middleware to process before updating state. middleware, // This is required when using Restash in an SSR environment. // Your state will load from this key. If present Restash // will load it. ssrKey: 'some_unique_ssr_key', // this will cause state to persist within localStorage. // when your app loads it will again look for this key. persistent: 'some_unique_name' // Statuses are used as the second dispatch argument. // The enable triggering things based on their state. statuses: ['start', 'progress', 'error', 'complete'] }; const { Provider, useStore } = createRestash(options); export { Provider, useStore } </code></pre> <a href="#status" id="status" style="color: inherit; text-decoration: none;"> <h3>Status</h3> </a> Restash includes a handy second arg on dispatch that allows you to set the status on dispatching an event. This is useful for updating your view based on this status. For example when making an async data requests. NOTE: this examples assumes you have added statuses as shown above in our options in the previous section. <pre><code class="language-tsx">const Home = () => { // The third arg here is the restash store. // you can use this to get state, status // you can also use this is middleware. const [state, dispatch, restash] = useStore(); // Although we're not updating the state here // you could update it along with the status. // This can really be handy stepping through // a stepper or remembering and updating a // status filling out a form. Once you get // the hang of it, can be quite useful. const changeStatus = (e) => { dispatch(null, e.target.value); }; return ( <div> <h3 style={{ marginBottom: '12px' }}>Current Status</h3> <hr style={{ marginBottom: '20px' }} /> <div style={{ color: '#fff', backgroundColor: 'darkblue', padding: '6px', display: 'inline' }}> <span>{(restash.status || '').toUpperCase()}</span> &nbsp; <select defaultValue={restash.status} onChange={changeStatus}> <option value="">Please Select</option> <option>mounted</option> <option>start</option> <option>progress</option> <option>error</option> <option>complete</option> </select> </div> </div> ); }; </code></pre> <a href="#server-side-react-ssr" id="server-side-react-ssr" style="color: inherit; text-decoration: none;"> <h2>Server Side React (SSR)</h2> </a> To use Restash with server side react you'll need to expose your state to the window of the application. This is common practice with other libs such as Redux. Here's an example using Restash with NextJS. First ensure you've enabled Restash for use with SSR. You can other pass true to use the default SSR key or pass your own string. <pre><code class="language-jsx">const { Provider, useStore } = createRestash({ ssrKey: true // or your own key such as __APP_STATE__ }); </code></pre> Using the default SSR key or the one you provided expose that to a custom _document.jsx (or _docuemnt.tsx) page in your NextJS <code>/pages</code> directory. <pre><code class="language-jsx">const state = JSON.stringify({ some_initial_state }); <script dangerouslySetInnerHTML={{ __html: `window.${SSR_KEY} = ${state};` }} /> </code></pre> <a href="#see-below-for-complete-example" id="see-below-for-complete-example" style="color: inherit; text-decoration: none;"> <h3>See Below for Complete Example</h3> </a> The Below example is for <a href="">NextJS</a> but you should be able to easily adapt to any SSR environemnt. The trick with SSR is to bind your state to a window prop as you see above and also below inside our script tag within the head element. <pre><code class="language-jsx"> const SSR_KEY = '__APP_STATE__'; // or use default __RESTASH_APP_STATE__ class MyDocument extends Document { static async getInitialProps(ctx) { const { res } = ctx; const app = res && res.meta ? res.meta : {}; const initialProps = await Document.getInitialProps(ctx); return { ...initialProps, app }; } render() { const { app } = this.props; const state = JSON.stringify({ ...DEFAULTS, ...app }); return ( <Html> <Head /> <script dangerouslySetInnerHTML={{ __html: `window.${SSR_KEY} = ${state};` }} /> <body> <Main /> <NextScript /> </body> </Html> ); } } export default MyDocument; </code></pre> <a href="#docs" id="docs" style="color: inherit; text-decoration: none;"> <h2>Docs</h2> </a> See <a href="https://blujedis.github.io/restash/">https://blujedis.github.io/restash/</a> <a href="#change" id="change" style="color: inherit; text-decoration: none;"> <h2>Change</h2> </a> See <a href="CHANGE.md">CHANGE.md</a> <a href="#license" id="license" style="color: inherit; text-decoration: none;"> <h2>License</h2> </a> See <a href="LICENSE">LICENSE.md</a> </div></div><div class="col-4 col-menu menu-sticky-wrap menu-highlight"><nav class="tsd-navigation primary"><ul><li class="current"><a href="modules.html">Exports</a></li></ul></nav><nav class="tsd-navigation secondary menu-sticky"><ul><li class="tsd-kind-enum"><a href="enums/Action.html" class="tsd-kind-icon">Action</a></li><li class="tsd-kind-enum"><a href="enums/DefaultStatus.html" class="tsd-kind-icon">DefaultStatus</a></li><li class="tsd-kind-enum"><a href="enums/StatusBase.html" class="tsd-kind-icon">StatusBase</a></li><li class="tsd-kind-interface"><a href="interfaces/IAction.html" class="tsd-kind-icon">IAction</a></li><li class="tsd-kind-interface tsd-has-type-parameter"><a href="interfaces/IContextOptions.html" class="tsd-kind-icon">IContextOptions</a></li><li class="tsd-kind-interface tsd-has-type-parameter"><a href="interfaces/IProvider.html" class="tsd-kind-icon">IProvider</a></li><li class="tsd-kind-interface tsd-has-type-parameter"><a href="interfaces/IRestash.html" class="tsd-kind-icon">IRestash</a></li><li class="tsd-kind-interface tsd-has-type-parameter"><a href="interfaces/IRestashAction.html" class="tsd-kind-icon">IRestashAction</a></li><li class="tsd-kind-interface tsd-has-type-parameter"><a href="interfaces/IRestashOptions.html" class="tsd-kind-icon">IRestashOptions</a></li><li class="tsd-kind-interface tsd-has-type-parameter"><a href="interfaces/IRestashState.html" class="tsd-kind-icon">IRestashState</a></li><li class="tsd-kind-interface tsd-has-type-parameter"><a href="interfaces/IStoreOptions.html" class="tsd-kind-icon">IStoreOptions</a></li><li class="tsd-kind-type-alias"><a href="modules.html#ActionTypes" class="tsd-kind-icon">ActionTypes</a></li><li class="tsd-kind-type-alias tsd-has-type-parameter"><a href="modules.html#DeepPartial" class="tsd-kind-icon">DeepPartial</a></li><li class="tsd-kind-type-alias"><a href="modules.html#DefaultStatusTypes" class="tsd-kind-icon">DefaultStatusTypes</a></li><li class="tsd-kind-type-alias tsd-has-type-parameter"><a href="modules.html#Dispatch" class="tsd-kind-icon">Dispatch</a></li><li class="tsd-kind-type-alias tsd-has-type-parameter"><a href="modules.html#KeyOf" class="tsd-kind-icon">KeyOf</a></li><li class="tsd-kind-type-alias"><a href="modules.html#Middleware" class="tsd-kind-icon">Middleware</a></li><li class="tsd-kind-type-alias"><a href="modules.html#MiddlewareDispatch" class="tsd-kind-icon">MiddlewareDispatch</a></li><li class="tsd-kind-type-alias tsd-has-type-parameter"><a href="modules.html#Path" class="tsd-kind-icon">Path</a></li><li class="tsd-kind-type-alias tsd-has-type-parameter"><a href="modules.html#PathValue" class="tsd-kind-icon">PathValue</a></li><li class="tsd-kind-type-alias tsd-has-type-parameter"><a href="modules.html#RestashHook" class="tsd-kind-icon">RestashHook</a></li><li class="tsd-kind-type-alias"><a href="modules.html#StatusBaseTypes" class="tsd-kind-icon">StatusBaseTypes</a></li><li class="tsd-kind-function"><a href="modules.html#applyMiddleware" class="tsd-kind-icon">applyMiddleware</a></li><li class="tsd-kind-function tsd-has-type-parameter"><a href="modules.html#createContext" class="tsd-kind-icon">createContext</a></li><li class="tsd-kind-function tsd-has-type-parameter"><a href="modules.html#createRestash" class="tsd-kind-icon">createRestash</a></li><li class="tsd-kind-function tsd-has-type-parameter"><a href="modules.html#createStore" class="tsd-kind-icon">createStore</a></li><li class="tsd-kind-function tsd-has-type-parameter"><a href="modules.html#logger" class="tsd-kind-icon">logger</a></li></ul></nav></div></div></div><footer class="with-border-bottom"><div class="container"><h2>Legend</h2><div class="tsd-legend-group"><ul class="tsd-legend"><li class="tsd-kind-property tsd-parent-kind-interface">Property</li></ul></div><h2>Settings</h2>Theme <select id="theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></footer><div class="container tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></div><div class="overlay"></div><script src="assets/main.js"></script></body></html>