[v2] new API and new implementation with useMutableSource

.eslintrc.json

@@ -30,7 +30,9 @@
     "import/extensions": ["error", "never"],
     "import/no-unresolved": ["error", { "ignore": ["use-context-selector"] }],
     "symbol-description": "off",
+    "no-underscore-dangle": "off",
     "no-use-before-define": "off",
+    "no-redeclare": "off",
     "no-unused-vars": "off"
   },
   "overrides": [{

README.md

@@ -4,7 +4,7 @@
 [![npm](https://img.shields.io/npm/v/use-context-selector)](https://www.npmjs.com/package/use-context-selector)
 [![size](https://img.shields.io/bundlephobia/minzip/use-context-selector)](https://bundlephobia.com/result?p=use-context-selector)
 
-React useContextSelector hook in userland
+React useContext with selector support in userland
 
 ## Introduction
 
@@ -22,6 +22,7 @@ This library provides the API in userland.
 
 Prior to v1.3, it uses `changedBits=0` feature to stop propagation,
 v1.3 no longer depends on this undocumented feature.
+v2 uses `useMutableSource`.
 
 ## Install
 
@@ -97,13 +98,33 @@ const App = () => (
 ReactDOM.render(<App />, document.getElementById('app'));
 ```
 
+## Migrating from v1 to v2
+
+In v1:
+
+```js
+useContextSelector(context, state => state.count);
+```
+
+In v2:
+
+```js
+useContext(context, useCallback(state => state.count, []));
+```
+
+In this case, you can (should) also define the selector function outside render.
+
 ## API
 
 <!-- Generated by documentation.js. Update this documentation by updating the source code. -->
 
 ### createContext
 
-This creates a special context for `useContextSelector`.
+This creates a special context for selector-enabled `useContext`.
+
+It doesn't pass its value but a ref of the value.
+Unlike the original context provider, this context provider
+expects the context value to be immutable and stable.
 
 #### Parameters
 
@@ -117,43 +138,28 @@ import { createContext } from 'use-context-selector';
 const PersonContext = createContext({ firstName: '', familyName: '' });
 ```
 
-### useContextSelector
+### useContext
 
-This hook returns context selected value by selector.
+This hook returns context value with optional selector.
 
 It will only accept context created by `createContext`.
 It will trigger re-render if only the selected value is referentially changed.
+The selector must be stable.
+Either define selector outside render or wrap with `useCallback`.
 
 The selector should return referentially equal result for same input for better performance.
 
 #### Parameters
 
 -   `context` **Context&lt;Value>** 
--   `selector` **function (value: Value): Selected** 
-
-#### Examples
-
-```javascript
-import { useContextSelector } from 'use-context-selector';
-
-const firstName = useContextSelector(PersonContext, state => state.firstName);
-```
-
-### useContext
-
-This hook returns the entire context value.
-Use this instead of React.useContext for consistent behavior.
-
-#### Parameters
-
--   `context` **Context&lt;Value>** 
+-   `selector` **function (value: Value): Selected**  (optional, default `identity as(value:Value)=>Selected`)
 
 #### Examples
 
 ```javascript
 import { useContext } from 'use-context-selector';
 
-const person = useContext(PersonContext);
+const firstName = useContext(PersonContext, state => state.firstName);
 ```
 
 ### useContextUpdate
@@ -212,7 +218,6 @@ This hook return a value for BridgeProvider
 ## Limitations
 
 -   In order to stop propagation, `children` of a context provider has to be either created outside of the provider or memoized with `React.memo`.
--   Provider trigger re-renders only if the context value is referentially changed.
 -   Neither context consumers or class components are supported.
 -   The [stale props](https://react-redux.js.org/api/hooks#stale-props-and-zombie-children) issue can't be solved in userland.
 -   Tearing is only avoided if all consumers get data using `useContextSelector`. If you use both props and `use-context-selector` to pass the same data, they may provide inconsistence data for a brief moment. (`02_tearing_spec` fails)

__tests__/01_basic_spec.tsx

@@ -1,6 +1,7 @@
 import React, {
   Dispatch,
   SetStateAction,
+  useCallback,
   useRef,
   useState,
   StrictMode,
@@ -12,7 +13,7 @@ import {
 
 import {
   createContext,
-  useContextSelector,
+  useContext,
 } from '../src/index';
 
 describe('basic spec', () => {
@@ -31,8 +32,8 @@ describe('basic spec', () => {
       [initialState, () => null],
     );
     const Counter1 = () => {
-      const count1 = useContextSelector(context, (v) => v[0].count1);
-      const setState = useContextSelector(context, (v) => v[1]);
+      const count1 = useContext(context, useCallback((v) => v[0].count1, []));
+      const setState = useContext(context, useCallback((v) => v[1], []));
       const increment = () => setState((s) => ({
         ...s,
         count1: s.count1 + 1,
@@ -48,7 +49,7 @@ describe('basic spec', () => {
       );
     };
     const Counter2 = () => {
-      const count2 = useContextSelector(context, (v) => v[0].count2);
+      const count2 = useContext(context, useCallback((v) => v[0].count2, []));
       const renderCount = useRef(0);
       renderCount.current += 1;
       return (

__tests__/02_tearing_spec.tsx

@@ -1,8 +1,8 @@
-import React, { useState, StrictMode } from 'react';
+import React, { useCallback, useState, StrictMode } from 'react';
 
 import { render, fireEvent, cleanup } from '@testing-library/react';
 
-import { createContext, useContextSelector } from '../src/index';
+import { createContext, useContext } from '../src/index';
 
 describe.skip('tearing spec', () => {
   afterEach(cleanup);
@@ -13,7 +13,7 @@ describe.skip('tearing spec', () => {
     };
     const context = createContext(initialState);
     const Counter: React.FC<{ parentCount: number }> = ({ parentCount }) => {
-      const count = useContextSelector(context, (v) => v.count);
+      const count = useContext(context, useCallback((v) => v.count, []));
       if (parentCount !== count) throw new Error('tears!!!');
       return (
         <div>
@@ -22,7 +22,7 @@ describe.skip('tearing spec', () => {
         </div>
       );
     };
-    const Parent = () => {
+    const Parent: React.FC = () => {
       const [state, setState] = useState(initialState);
       const increment = () => setState((s) => ({
         ...s,

__tests__/03_stale_props_spec.tsx

@@ -1,25 +1,25 @@
-import React, { useReducer } from 'react';
+import React, { useCallback, useReducer } from 'react';
 
 import { render, fireEvent, cleanup } from '@testing-library/react';
 
-import { createContext, useContextSelector } from '../src/index';
+import { createContext, useContext } from '../src/index';
 
 describe.skip('stale props spec', () => {
   afterEach(cleanup);
 
   it('ignores transient errors in selector (e.g. due to stale props)', () => {
     const Context = createContext(0);
     const Parent: React.FC = () => {
-      const count = useContextSelector(Context, (c: number) => c);
+      const count = useContext(Context, useCallback((c: number) => c, []));
       return <Child parentCount={count} />;
     };
     const Child: React.FC<{ parentCount: number }> = ({ parentCount }) => {
-      const result = useContextSelector(Context, (c: number) => {
+      const result = useContext(Context, useCallback((c: number) => {
         if (c !== parentCount) {
           throw new Error();
         }
         return c + parentCount;
-      });
+      }, [parentCount]));
       return <div>{result}</div>;
     };
     const App: React.FC = () => {
@@ -43,14 +43,14 @@ describe.skip('stale props spec', () => {
     let selectorSawInconsistencies = false;
     const Context = createContext(0);
     const Parent: React.FC = () => {
-      const count = useContextSelector(Context, (c: number) => c);
+      const count = useContext(Context, useCallback((c: number) => c, []));
       return <Child parentCount={count} />;
     };
     const Child: React.FC<{ parentCount: number }> = ({ parentCount }) => {
-      const result = useContextSelector(Context, (c: number) => {
+      const result = useContext(Context, useCallback((c: number) => {
         selectorSawInconsistencies = selectorSawInconsistencies || c !== parentCount;
         return c + parentCount;
-      });
+      }, [parentCount]));
       return <div>{result}</div>;
     };
     const App: React.FC = () => {

__tests__/05_cm_spec.tsx

@@ -1,6 +1,7 @@
 import React, {
   Dispatch,
   SetStateAction,
+  useCallback,
   useRef,
   useState,
   StrictMode,
@@ -12,7 +13,7 @@ import {
 
 import {
   createContext,
-  useContextSelector,
+  useContext,
   useContextUpdate,
 } from '../src/index';
 
@@ -32,8 +33,8 @@ describe('useContextUpdate spec', () => {
       [initialState, () => null],
     );
     const Counter1 = () => {
-      const count1 = useContextSelector(context, (v) => v[0].count1);
-      const setState = useContextSelector(context, (v) => v[1]);
+      const count1 = useContext(context, useCallback((v) => v[0].count1, []));
+      const setState = useContext(context, useCallback((v) => v[1], []));
       const update = useContextUpdate(context);
       const increment = () => update(() => {
         setState((s) => ({
@@ -52,7 +53,7 @@ describe('useContextUpdate spec', () => {
       );
     };
     const Counter2 = () => {
-      const count2 = useContextSelector(context, (v) => v[0].count2);
+      const count2 = useContext(context, useCallback((v) => v[0].count2, []));
       const renderCount = useRef(0);
       renderCount.current += 1;
       return (

__tests__/06_bridge_spec.tsx

@@ -1,6 +1,7 @@
 import React, {
   Dispatch,
   SetStateAction,
+  useCallback,
   useState,
   StrictMode,
 } from 'react';
@@ -11,7 +12,7 @@ import {
 
 import {
   createContext,
-  useContextSelector,
+  useContext,
   useBridgeValue,
   BridgeProvider,
 } from '../src/index';
@@ -31,8 +32,8 @@ describe('Bridge spec', () => {
       [initialState, () => null],
     );
     const Counter = () => {
-      const count = useContextSelector(context, (v) => v[0].count);
-      const setState = useContextSelector(context, (v) => v[1]);
+      const count = useContext(context, useCallback((v) => v[0].count, []));
+      const setState = useContext(context, useCallback((v) => v[1], []));
       const increment = () => {
         setState((s) => ({
           ...s,
@@ -47,7 +48,7 @@ describe('Bridge spec', () => {
       );
     };
     const AnotherCounter = () => {
-      const count = useContextSelector(context, (v) => v[0].count);
+      const count = useContext(context, useCallback((v) => v[0].count, []));
       return (
         <div>
           <span data-testid="anothercounter">{count}</span>

__tests__/__snapshots__/05_cm_spec.tsx.snap

@@ -40,7 +40,7 @@ exports[`useContextUpdate spec counter 2`] = `
       +1
     </button>
     <span>
-      5
+      3
     </span>
   </div>
   <div>

examples/01_minimal/src/index.js

@@ -1,9 +1,9 @@
-import React, { useReducer, StrictMode } from 'react';
+import React, { useCallback, useReducer, StrictMode } from 'react';
 import ReactDOM from 'react-dom';
 
 import {
   createContext,
-  useContextSelector,
+  useContext,
 } from 'use-context-selector';
 
 const initialState = {
@@ -23,8 +23,8 @@ const reducer = (state, action) => {
 const context = createContext(null);
 
 const Counter = () => {
-  const count = useContextSelector(context, (v) => v[0].count);
-  const dispatch = useContextSelector(context, (v) => v[1]);
+  const count = useContext(context, useCallback((v) => v[0].count, []));
+  const dispatch = useContext(context, useCallback((v) => v[1], []));
   return (
     <div>
       {Math.random()}
@@ -38,8 +38,8 @@ const Counter = () => {
 };
 
 const TextBox = () => {
-  const text = useContextSelector(context, (v) => v[0].text);
-  const dispatch = useContextSelector(context, (v) => v[1]);
+  const text = useContext(context, useCallback((v) => v[0].text, []));
+  const dispatch = useContext(context, useCallback((v) => v[1], []));
   return (
     <div>
       {Math.random()}

examples/02_typescript/src/Counter.tsx

@@ -1,12 +1,12 @@
-import React from 'react';
+import React, { useCallback } from 'react';
 
-import { useContextSelector } from 'use-context-selector';
+import { useContext } from 'use-context-selector';
 
 import { MyContext } from './state';
 
 const Counter = () => {
-  const count = useContextSelector(MyContext, (v) => v[0].count);
-  const dispatch = useContextSelector(MyContext, (v) => v[1]);
+  const count = useContext(MyContext, useCallback((v) => v[0].count, []));
+  const dispatch = useContext(MyContext, useCallback((v) => v[1], []));
   return (
     <div>
       {Math.random()}

examples/02_typescript/src/Person.tsx

@@ -1,12 +1,12 @@
-import React from 'react';
+import React, { useCallback } from 'react';
 
-import { useContextSelector } from 'use-context-selector';
+import { useContext } from 'use-context-selector';
 
 import { MyContext } from './state';
 
 const Person = () => {
-  const person = useContextSelector(MyContext, (v) => v[0].person);
-  const dispatch = useContextSelector(MyContext, (v) => v[1]);
+  const person = useContext(MyContext, useCallback((v) => v[0].person, []));
+  const dispatch = useContext(MyContext, useCallback((v) => v[1], []));
   return (
     <div>
       {Math.random()}