state-decorator 6.10.0 → 7.0.0-beta.0

package/README.md

@@ -11,12 +11,19 @@ The StateDecorator is a set of Reacts hook that manages a complex component stat
 - Deterministic state changes (clear separation of effects and side effects)
 - Ease asynchronous actions state changes (loading / error states, success & error handlers, parallel actions management, optimistic updates...)
 - Easily and efficiently share slices of state.
-- Easily testable (uses pure functions, utility functions provided)
+- Easily testable (test framework provided)
 - Easily update state from or react to props changes
-- Ease debugging (trace state changes)
+- Ease debugging (trace state changes, dev tools)
 - Improve code conciseness (no boiler plate code)
-- Enforce separation of container components and presentation components.
-- Strongly typed
+- Strongly typed (Typescript)
+
+# V7: Partial state and new hooks
+
+- All effects can now return a partial state that will be merged with current state.
+- More documentation on global and local store use cases.
+- **useLocalStore** and **useStore** now have a parameter to specify if the React component must re-rerender after a state change.
+- New **useStoreContextSlice** hook was added to get a slice of a store in a context.
+- Removed useBindStore hook.
 
 # 🏎️ V6: The Store
 
@@ -82,13 +89,12 @@ export const getInitialState = (): State => ({
 
 export const userAppActions: StoreActions<State, Actions, Props> = {
   // synchronous action (simple form)
-  selectUser: ({ state, args: [id] }) => ({ ...state, selectedUserId: id }),
+  selectUser: ({ args: [id] }) => ({ selectedUserId: id }),
 
   // a synchronous action with side effects
   selectAndLoadUser: {
-    // same as simple form, using aliases (use short context alias 's' instead of 'state')
     // effects contain only immutable state changes
-    effects: ({ s, args: [id] }) => ({ ...s, selectedUserId: id }),
+    effects: ({ args: [id] }) => ({ selectedUserId: id }),
     // side effects (ie. other effects than state changes), using "actions" alias
     sideEffects: ({ a }) => {
       a.loadUser();
@@ -100,9 +106,9 @@ export const userAppActions: StoreActions<State, Actions, Props> = {
     // promise provider, can use action context (ctx) to get current state, args, props etc.
     getPromise: (ctx) => Promise.resolve({ firstName: 'John', lastName: 'Doe' }),
     // state changes
-    effects: ({ s, res }) => ({ ...s, user: res }),
+    effects: ({ res }) => ({ user: res }),
     // state changes if error
-    errorEffects: ({ s, error }) => ({ ...s, user: null }),
+    errorEffects: ({ error }) => ({ user: null }),
     // side effects here
     sideEffects: ({ res, actions }) => {},
     // side effects if error
@@ -139,12 +145,12 @@ export function App(props: Props) => {
 
 # React hooks
 
-| Hook          | Purpose                                                | Component refreshed on store change | Store is destroyed on unmount |
-| ------------- | ------------------------------------------------------ | ----------------------------------- | ----------------------------- |
-| useLocalStore | Create a store and binds it to the react component     | Y                                   | Y                             |
-| useStore      | Binds an existing store to a react component (sharing) | Y                                   | Y                             |
-| useBindStore  | Bind an existing store to a react component (sharing)  | N                                   | Y                             |
-| useStoreSlice | Binds a store slice to a react component (sharing)     | If slice has changed only           | N                             |
+| Hook                 | Purpose                                             | Returns | Is component refreshed on store change? | Is store destroyed on unmount? |
+| -------------------- | --------------------------------------------------- | ------- | --------------------------------------- | ------------------------------ |
+| useLocalStore        | Create a store and binds it to the react component. | Store   | if **refreshOnUpdate** is set           | Y                              |
+| useStore             | Binds a store instance to the react component.      | Store   | if **refreshOnUpdate** is set           | N                              |
+| useStoreSlice        | Get a slice of a store.                             | Slice   | If slice has changed only               | N                              |
+| useStoreContextSlice | Get a slice of a store stored in a context          | Slice   | If slice has changed only               | N                              |
 
 # Initial state
 
@@ -190,14 +196,14 @@ The StateDecorator is taking a list of actions and decorate them to inject state
 ## Short form
 
 ```typescript
-action: (ctx) => ctx.state, // state changes
+action: (ctx) => ctx.state, // changes to be merged to current state
 ```
 
 Example:
 
 ```typescript
 const actions: StoreActions<State, Actions> = {
-  setText: ({ s, args: [newText] }) => ({ ...s, text: newText }),
+  setText: ({ args: [newText] }) => ({ text: newText }),
 };
 ```
 
@@ -222,7 +228,7 @@ Example:
 ```typescript
 const actions: StoreActions<State, Actions> = {
   setText: {
-    effects: ({ s, args: [newText] }) => ({ ...s, text: newText }),
+    effects: ({ args: [newText] }) => ({ text: newText }),
     // use either debounceTimeout or debounceSideEffectsTimeout
     // debounceTimeout: 5000,
     debounceSideEffectsTimeout: 5000,
@@ -272,7 +278,7 @@ Example:
 const actions: StoreActions<State, Actions> = {
   loadList: {
     getPromise: () => fetch('https://myapi/myservices').then((res) => (res.ok ? res.json() : Promise.reject())),
-    effects: ({ s, res }) => ({ ...s, list: res }),
+    effects: ({ res }) => ({ list: res }),
     sideEffects: ({ a }) => {
       a.otherAction();
     },
@@ -395,7 +401,7 @@ If some actions need to be triggered, set **errorSideEffects**.
 const actions: StoreActions<State, Actions> = {
   loadList: {
     getPromise: () => new Promise((_, reject) => setTimeout(reject, 500, new Error('Too bad'))),
-    errorEffects: ({ state, error }) => ({ ...state, error: error.message, list: [] }),
+    errorEffects: ({ error }) => ({ error: error.message, list: [] }),
     getErrorMessage: ({ err }) => err.message,
     errorSideEffects: ({ error }) => {
       Logger.log(error);
@@ -517,8 +523,8 @@ Example:
 const actions: StoreActions<State, Actions> = {
   deleteItem: {
     getPromise: ([id]) => new Promise((resolve) => setTimeout(resolve, 500)),
-    optimisticEffects: (state, args) => ({ ...state, list: list.filter((item) => item.id === args[0]) }),
-    errorEffects: (state, error: Error) => ({ ...state, error: error.message }),
+    optimisticEffects: ({ args: [id] }) => ({ list: list.filter((item) => item.id === id) }),
+    errorEffects: ({err} => ({ err: error.message }),
   },
 };
 ```
@@ -554,9 +560,9 @@ export const actionsAbort: StoreActions<State, Actions, Props> = {
           reject(new DOMException('Aborted', 'AbortError'));
         });
       }),
-    errorEffects: ({s, err}) => (err.name === 'AbortError' ? { ...s, isAborted: true } : { ...s, isError: true }),
-    effects: ({s}) => ({ ...s, isSuccess: true }),
-    errorSideEffects: ({s, err}) => {
+    errorEffects: ({ err}) => (err.name === 'AbortError' ? { isAborted: true } : { isError: true }),
+    effects: () => ({ isSuccess: true }),
+    errorSideEffects: ({ err }) => {
       if (e.name === 'AbortError') {
         console.log('AbortError side effect');
       } else {
@@ -569,96 +575,92 @@ export const actionsAbort: StoreActions<State, Actions, Props> = {
 
 [![Edit Abort](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/abort-v6-uvnl7)
 
-## Call actions on mount
+# Derived state
 
-When a hook that creates / binds a store is mounted, the **onMount** option is called.
+A derived state is a state that can be deduced from state and props.
 
 ```typescript
 import { createStore } from 'state-decorator';
 
-const store = createStore(getInitialState, actionsImpl, {
-  onMount: ({ a }) => {
-    a.loadList;
-  },
-});
-
-// onMount is called when this component is mounted
-function Container(p: ContainerProps) {
-  useBindStore(store, p);
-}
-```
+type State = {
+  value: number;
+};
 
-If an initial action is launched each time a property changes, consider using the **onMount** flag of the **onPropsChange** entry.
+type Actions = {
+  add1: () => void;
+};
 
-## State sharing and slices
+type Props = {
+  propIn: number;
+};
 
-- Declare a store and bind it to a component using _useStore_ or _useBindStore_ hooks.
-- Deeper in the tree component, use _useStoreSlice_ to get a store slice.
-- Component using slices will be refreshed only if their store slice changes.
+type DerivedState = {
+  derivedProp: number;
+};
 
-```typescript
-import React from 'react';
-import { useStore, useStoreSlice, StoreActions } from 'state-decorator';
+const store = createStore<State, Actions, Props, DerivedState>(
+  () => ({ value: 0 }),
+  {
+    add1: ({ s }) => ({ ...s, value: s.value + 1 }),
+  },
+  {
+    derivedState: {
+      derivedProp: {
+        // get the list of dependencies to be checked to trigger the computation of the derived state
+        // if state.value AND/OR props.prop1 changes, derivedProp is recomputed
+        getDeps: ({ state, props }) => [state.value, props.propIn],
+        // compute derived state from state & props (use short aliases)
+        get: ({ s, p }) => s.value * p.propIn,
+      },
+    },
+  }
+);
 
-// Declare typings & actions as above
+export function App(props: Props) {
+  const { state } = useStore(store, props);
+  // state contains the store state and derived state
+  return <div>{state.derivedProp}</div>;
+}
+```
 
-// Create a store
+## Recipes
 
-export const store = createStore(getInitialState, userAppActions);
+- Derived state is the same as using _useMemo_ in sub component.
+- If the derived state is needed in one component only, it may prove better to use a _useMemo_ in this component to save memory when the component is unmounted and store not.
+- In general, do **not** compute derived values directly in state, it's error prone as you can forget some places or implement different logic.
+- Use derived state especially if this state is shared accross several sub components
 
-// Bind to react component
+# Call actions on mount
 
-export function Container(prop: Props) {
-  const { state, actions } = useStore(store, props);
+When a hook that creates / binds a store is mounted, the **onMount** option is called.
 
-  // or
-  // useBindStore(store, props);
-  // if you are not interested in getting the state here
+```typescript
+import { createStore } from 'state-decorator';
 
-  return <div />;
-}
+// global store
+const store = createStore(getInitialState, actionsImpl, {
+  onMount: ({ a }) => {
+    a.loadList;
+  },
+});
 
-// Components deeper in the component tree will be refreshed if, and only if,
-// slice is changed (here: text property)
+store.init(initialProps);
+```
 
-export function SubComponent2() {
-  const s = useStoreSlice(store, ['text']);
-  return <div>{s.text}</div>;
-}
+```typescript
+import { createStore } from 'state-decorator';
 
-export function SubComponent() {
-  const s = useStoreSlice(store, (s) => ({ text: s.text }));
-  return <div>{s.text}</div>;
+// local store
+function Container(p: ContainerProps) {
+  const store = useLocalStore(getInitialState, actionsImpl, p, {
+    onMount: ({ a }) => {
+      a.loadList;
+    },
+  });
 }
 ```
 
-[![Edit Slice](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/slices-v6-eg471?file=/src/SliceView.tsx)
-
-# Global configuration
-
-Overrides configuration to set properties that will be used by all stores.
-
-```typescript
-// all parameters are optional
-setGlobalConfig({
-  // Used to clone state and props when managing optimistic conflicting actions.
-  clone: defaultCloneFunc,
-  // Compare to objets and returns if they are equal (slices).
-  comparator: shallow,
-  // Callback function to handle asychronous actions rejected promise (error reporting).
-  asyncErrorHandler: () => {},
-  // Tests if the error will trigger a retry of the action or will fail directly (retry promises)
-  retryOnErrorFunction: (error: Error) => error instanceof TypeError,
-  // Notification function on successful asynchronous action (if success message is set on action)
-  notifySuccess: undefined,
-  // Notification function on failed asynchronous action (if error message is set on action)
-  notifyError: undefined,
-  // Notification function injected in side effects action context (success and error) to notify warning
-  notifyWarning: undefined,
-  // Function called to return common error message if error message is not provided or error not managed in action. To override locally in action, provide a function that returns _null_.
-  getErrorMessage: undefined,
-});
-```
+If an initial action is launched each time a property changes, consider using the **onMount** flag of the **onPropsChange** entry.
 
 # Update store when props change
 
@@ -672,7 +674,7 @@ const store = createStore(getInitialState, actionsImpl, {
     // list of depedencies that should trigger effects & side effects if changed
     getDeps: (p) => [p.id],
     // state changes, indices contains the indices of dependencies that have changed
-    effects: ({ state, props, indices, isInit }) => ({ ...state, selectedId: props.id }),
+    effects: ({ props, indices, isInit }) => ({ selectedId: props.id }),
     // other changes (use short aliases)
     sideEffects: ({ p, a, indices, isInit }) => {
       a.loadItem(p.id);
@@ -708,7 +710,7 @@ const store = createStore(getInitialState, actionsImpl, {
     },
     {
       getDeps: (p) => [p.otherProp],
-      effects: ({ state, props, indices }) => ({ ...state, otherProp: props.otherProp }),
+      effects: ({ props, indices }) => ({ otherProp: props.otherProp }),
       sideEffects: ({ p, a }) => {
         a.otherSideEffect(p.otherProp);
       },
@@ -731,7 +733,7 @@ const store = createStore(getInitialState, actionsImpl, {
   onPropsChange: [
     {
       getDeps: (p) => [p.userId],
-      effects: ({ s, p }) => ({ ...s, userId: p.userId }),
+      effects: ({ p }) => ({ userId: p.userId }),
       sideEffects: ({ p, a }) => {
         a.loadUser(p.userId);
       },
@@ -745,7 +747,7 @@ const store = createStore(getInitialState, actionsImpl, {
   onPropsChange: [
     {
       getDeps: (p) => [p.userId],
-      effects: ({ s, p, isInit }) => (isInit ? null : { ...s, userId: p.userId }),
+      effects: ({ p, isInit }) => (isInit ? null : { userId: p.userId }),
       sideEffects: ({ p, a }) => {
         a.loadUser(p.userId);
       },
@@ -762,60 +764,235 @@ const store = createStore(getInitialState, actionsImpl, {
 - Use several prop change configurations to separate dependencies between props and have simple definition.
 - Use onMount flag to have a more systematic and simpler code.
 
-# Derived state
+# Global / local Stores and State sharing
 
-A derived state is a state that can be deduced from state and props.
+There are two ways to share state and actions:
+
+- Using regular props.
+- Using state slices.
+
+There are two types of stores:
+
+- Global store:
+
+  - store is created as an instance (**createStore**) and it is exported from the JS module.
+  - it can be imported in any other JS module.
+  - store lifespan is equal to the application one.
+
+- Local store:
+  - store is created by a hook (**useLocalStore**) and is bound to a React component (each instance of this component owns its own store).
+  - action and props can be shared using props or sharing the store itself (see example below)
+  - store is destroyed when its owner React component is unmounted.
+
+## Using props
+
+- Bind a React component to make store state / actions available on React component.
+- Any change in the store (state, loading actions, ...) will trigger a refresh of the bound React component.
+- Pass state / actions using regular React props.
+- Use React.memo to prevent unecessary React re-renders if needed.
+
+### Global store
 
 ```typescript
-import { createStore } from 'state-decorator';
+// Declare typings & actions as above
 
-type State = {
-  value: number;
-};
+// Create a store in a dedicated file, named GlobalStore.ts for example
+export const store = createStore(getInitialState, userAppActions);
 
-type Actions = {
-  add1: () => void;
-};
+//----------------------
 
-type Props = {
-  propIn: number;
-};
+// In another file
+import React, { memo } from 'react';
+import { useStore } from 'state-decorator';
+import store from './GlobalStore';
 
-type DerivedState = {
-  derivedProp: number;
-};
+// Bind to react component
+// Each time the store state changes, a re-render is done.
+export function Container(props: Props) {
+  const { state, actions } = useStore(store, props);
+  return (
+    <div>
+      <Title text={state.title} />
+      <Subtitle text={state.subtitle} />
+    </div>
+  );
+}
 
-const store = createStore<State, Actions, Props, DerivedState>(
-  () => ({ value: 0 }),
-  {
-    add1: ({ s }) => ({ ...s, value: s.value + 1 }),
-  },
-  {
-    derivedState: {
-      derivedProp: {
-        // get the list of dependencies to be checked to trigger the computation of the derived state
-        // if state.value AND/OR props.prop1 changes, derivedProp is recomputed
-        getDeps: ({ state, props }) => [state.value, props.propIn],
-        // compute derived state from state & props (use short aliases)
-        get: ({ s, p }) => s.value * p.propIn,
-      },
-    },
-  }
-);
+// Simple presentation components
+// Use memo to prevent re-render if another part of the state has changed than "title"
+const Title = memo(function Title(props: { title: string }) {
+  return <div>{props.text}</div>;
+});
 
-export function App(props: Props) {
-  const { state } = useStore(store, props);
-  // state contains the store state and derived state
-  return <div>{state.derivedProp}</div>;
+const Subtitle = memo(function Subtitle(props: { subtitle: string }) {
+  return <div>{props.subtitle}</div>;
+});
+```
+
+### Local Store
+
+```typescript
+import React, { memo } from 'react';
+import { useLocalStore } from 'state-decorator';
+
+// Declare typings & actions as above
+
+// Create and bind to react component
+// Each time the store state changes, a re-render is done.
+export function Container(props: Props) {
+  const { state, actions } = useLocalStore(getInitialState, userAppActions, props);
+  return (
+    <div>
+      <Title text={state.title} />
+      <Subtitle text={state.subtitle} />
+    </div>
+  );
 }
+
+// Simple presentation components
+// Use memo to prevent re-render if another part of the state has changed than "title"
+const Title = memo(function Title(props: { title: string }) {
+  return <div>{props.title}</div>;
+});
+
+const Subtitle = memo(function Subtitle(props: { subtitle: string }) {
+  return <div>{props.subtitle}</div>;
+});
 ```
 
-## Recipes
+## State slices
 
-- Derived state is the same as using _useMemo_ in sub component.
-- If the derived state is needed in one component only, it may prove better to use a _useMemo_ in this component to save memory when the component is unmounted and store not.
-- In general, do **not** compute derived values directly in state, it's error prone as you can forget some places or implement different logic.
-- Use derived state especially if this state is shared accross several sub components
+Using React props implies useless re-renders and optionally memoization.
+
+To prevent this, React provides [context](https://en.reactjs.org/docs/context.html) hooks.
+
+The problem is that if the context contains a complex state with lots of props, if **any** of these props is changing, **all** components that uses this context will be re-rendered.
+
+To overcome this problem, the StateDecorator provides a **useStoreSlice** and **useStoreContextSlice** hook that allow to define and extracts a slice of the state and trigger a re-render of the React component only if the slice has changed.
+
+[![Edit Slice](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/slices-v6-eg471?file=/src/SliceView.tsx)
+
+## Global Store
+
+```typescript
+// Declare typings & actions as above
+
+// Create a store in a dedicated file, named GlobalStore.ts for example
+export const store = createStore(getInitialState, userAppActions);
+
+//----------------------
+
+import React, { memo } from 'react';
+import { useStoreSlice } from 'state-decorator';
+import store from './GlobalStore';
+
+export function Container(props: Props) {
+  return (
+    <div>
+      <Title />
+      <Subtitle />
+    </div>
+  );
+}
+
+function Title() {
+  // extracts the "title" slice
+  // component is refresh only if title is changed in the store
+  const { title } = useStoreSlice(store, ['title']);
+  return <div>{title}</div>;
+}
+
+function Subtitle(props: { subtitle: string }) {
+  const { subtitle } = useStoreSlice(store, ['subtitle']);
+  return <div>{subtitle}</div>;
+}
+```
+
+## Local Store
+
+```typescript
+// ------- stores/MyStore.ts --------
+
+import React from 'react';
+import { useLocalStore, useStoreContextSlice } from 'state-decorator';
+
+// Declare typings & actions as above
+
+// Create a store context
+
+type StoreContextProps = StoreApi<State, Actions, Props>;
+
+export const StoreContext = createContext<StoreContextProps>(null);
+
+// The StoreContext will allow to access to the store
+// But this context is NOT refreshed if the store state is changed
+export function StoreContextProvider(p: { children: any; propIn: string }) {
+  const { children, ...props } = p;
+  const store = useLocalStore(getInitialState, actionsImpl, props);
+  return <StoreContext.Provider value={store}>{children}</StoreContext.Provider>;
+}
+
+// In a container file ------------------------
+
+import { StoreContextProvider } from 'stores/MyStore';
+
+// If Container is destroyed store is destroyed
+export function Container(props: Props) {
+  return (
+    <StoreContextProvider {...props}>
+      <SubComponent />
+      <SubComponent2 />
+    </StoreContextProvider>
+  );
+}
+
+// Component deeper in the component tree...
+
+import { StoreContext } from 'stores/MyStore';
+
+function Title() {
+  // extracts the "title" slice
+  // component is refresh only if title is changed in the store
+  const { title } = useStoreContextSlice(StoreContext, ['title']);
+
+  // same as
+  // const store = useContext(StoreContext)
+  // const { title } = useStoreSlice(store, ['title']);
+
+  return <div>{title}</div>;
+}
+
+function Subtitle(props: { subtitle: string }) {
+  const { subtitle } = useStoreContextSlice(StoreContext, ['subtitle']);
+  return <div>{subtitle}</div>;
+}
+```
+
+# Global configuration
+
+Overrides configuration to set properties that will be used by all stores.
+
+```typescript
+// all parameters are optional
+setGlobalConfig({
+  // Used to clone state and props when managing optimistic conflicting actions.
+  clone: defaultCloneFunc,
+  // Compare to objets and returns if they are equal (slices).
+  comparator: shallow,
+  // Callback function to handle asychronous actions rejected promise (error reporting).
+  asyncErrorHandler: () => {},
+  // Tests if the error will trigger a retry of the action or will fail directly (retry promises)
+  retryOnErrorFunction: (error: Error) => error instanceof TypeError,
+  // Notification function on successful asynchronous action (if success message is set on action)
+  notifySuccess: undefined,
+  // Notification function on failed asynchronous action (if error message is set on action)
+  notifyError: undefined,
+  // Notification function injected in side effects action context (success and error) to notify warning
+  notifyWarning: undefined,
+  // Function called to return common error message if error message is not provided or error not managed in action. To override locally in action, provide a function that returns _null_.
+  getErrorMessage: undefined,
+});
+```
 
 # Debug actions
 
@@ -900,11 +1077,11 @@ function Container(props: Props) {
   - a new store is created each time state or props are set.
   - it allows to share mock store across tests.
 - The API is chainable: functions are returning a mock store, excepting test functions.
-- On a mock store, we can test the store internals after initialiation, after inbound props have changed, after actions are called.
+- On a mock store, we can test the store internals after initialiation, after inbound props have changed, after actions are called. These test function do not change the internal state of the mock store.
 
 ## Getting started
 
-1. Create and setup a mock store (_createMockFromStore_)
+1. Create and setup a mock store (_createMockFromStore_, _createMockStore_)
 2. Test store after initialization (_onInit_)
 3. Test store after props changes (_onPropsChange_)
 4. Test each action: