reactish-state 0.10.4 → 0.11.0

package/README.md

@@ -1,6 +1,6 @@
 # Reactish-State
 
-> Simple, decentralized state management for React.
+> Simple, decentralized(atomic) state management for React.
 
 ## Install
 
@@ -94,9 +94,9 @@ The state management solutions in the React ecosystem have popularized two state
 
 - **Centralized**: a single store that combines entire app states together and slices of the store are connected to React components through selectors. Examples: react-redux, Zustand.
 
-- **Decentralized**: consisting of many small states which can build up state dependency trees using a bottom-up approach. React components only need to connect with the states that they use. Examples: Recoil, Jotai.
+- **Decentralized**: consisting of many small(atomic) states which can build up state dependency trees using a bottom-up approach. React components only need to connect with the states that they use. Examples: Recoil, Jotai.
 
-This library adopts the decentralized state model, offering a _Recoil-like_ API, but with a much simpler and smaller implementation(similar to Zustand), which makes it the one of the smallest state management solutions with gzipped bundle size less than 1KB.
+This library adopts the decentralized state model, offering a _Recoil-like_ API, but with a much simpler and smaller implementation(similar to Zustand), which makes it the one of the smallest state management solutions with gzipped bundle size around 1KB.
 
 |  | State model | Bundle size |
 | --- | --- | --- |
@@ -153,7 +153,7 @@ The difference might sound insignificant, but imaging every single state update
 - Feature extensible with middleware or plugins
 - States persistable to browser storage
 - Support Redux dev tools via middleware
-- Less than 1KB: simple and small
+- [~1KB](https://bundlephobia.com/package/reactish-state): simple and small
 
 # Recipes
 
@@ -303,6 +303,55 @@ const Example = () => {
 };
 ```
 
+## Selector that depends on props or local states
+
+The `selector` function allows us to create reusable derived states outside React components. In contrast, component-scoped derived states which depend on props or local states can be created by the `useSelector` hook.
+
+```jsx
+import { state, useSelector } from "reactish-state";
+
+const todosState = state([{ task: "Shop groceries", completed: false }]);
+
+const FilteredTodoList = ({ filter = "ALL" }) => {
+  const filteredTodos = useSelector(
+    () => [
+      todosState,
+      (todos) => {
+        switch (filter) {
+          case "ALL":
+            return todos;
+          case "COMPLETED":
+            return todos.filter((todo) => todo.completed);
+          case "ACTIVE":
+            return todos.filter((todo) => !todo.completed);
+        }
+      }
+    ],
+    [filter]
+  );
+  // Render filtered todos...
+};
+```
+
+The second parameter of `useSelector` is a dependency array (similar to React's `useMemo` hook), in which you can specify what props or local states the selector depends on. In the above example, `FilteredTodoList` component will re-render only if the global `todosState` state or local `filter` prop have been updated.
+
+### Linting the dependency array of useSelector
+
+You can take advantage of the [eslint-plugin-react-hooks](https://www.npmjs.com/package/eslint-plugin-react-hooks) package to lint the dependency array of `useSelector`. Add the following configuration into your ESLint config file:
+
+```json
+{
+  "rules": {
+    "react-hooks/exhaustive-deps": [
+      "warn",
+      {
+        "additionalHooks": "useSelector"
+      }
+    ]
+  }
+}
+```
+
 ## Still perfer Redux-like reducers?
 
 ```js

package/dist/cjs/index.js

@@ -1,6 +1,7 @@
 'use strict';
 
 var shim = require('use-sync-external-store/shim');
+var react = require('react');
 
 const createState = ({
   middleware
@@ -39,6 +40,12 @@ const isEqual = (args1, args2) => {
   }
   return true;
 };
+const createSubscriber = items => listener => {
+  const unsubscribers = items.map(item => item.subscribe(listener));
+  return () => unsubscribers.forEach(unsubscribe => unsubscribe());
+};
+const getReactishValues = items => items.map(item => item.get());
+
 const createSelector = ({
   plugin
 } = {}) => (...items) => {
@@ -52,19 +59,16 @@ const createSelector = ({
   let cache;
   const selector = {
     get: () => {
-      const args = items.map(item => item.get());
-      if (cache && isEqual(args, cache.args)) return cache.ret;
-      const ret = selectorFunc(...args);
+      const args = getReactishValues(items);
+      if (cache && isEqual(args, cache.args)) return cache.val;
+      const val = selectorFunc(...args);
       cache = {
         args,
-        ret
+        val
       };
-      return ret;
+      return val;
     },
-    subscribe: listener => {
-      const unsubscribers = items.map(item => item.subscribe(listener));
-      return () => unsubscribers.forEach(unsubscribe => unsubscribe());
-    }
+    subscribe: createSubscriber(items)
   };
   plugin == null ? void 0 : plugin(selector, config);
   return selector;
@@ -76,8 +80,37 @@ const useSnapshot = ({
   get
 }) => shim.useSyncExternalStore(subscribe, get, get);
 
+const useSelector = (selectorParamFactory, deps) => {
+  const items = selectorParamFactory();
+  const cutoff = items.length - 1;
+  const selectorFunc = items[cutoff];
+  items.length = cutoff;
+  const [context] = react.useState(() => ({
+    sub: createSubscriber(items)
+  }));
+  const get = () => {
+    const {
+      cache
+    } = context;
+    const reactishValues = getReactishValues(items);
+    const args = reactishValues.concat(deps || selectorFunc);
+    if (cache && isEqual(args, cache.args)) return cache.val;
+    const val = selectorFunc(...reactishValues);
+    context.cache = {
+      args,
+      val
+    };
+    return val;
+  };
+  return useSnapshot({
+    get,
+    subscribe: context.sub
+  });
+};
+
 exports.createSelector = createSelector;
 exports.createState = createState;
 exports.selector = selector;
 exports.state = state;
+exports.useSelector = useSelector;
 exports.useSnapshot = useSnapshot;

package/dist/esm/index.js

@@ -1,3 +1,4 @@
 export { createState, state } from './vanilla/state.js';
 export { createSelector, selector } from './vanilla/selector.js';
 export { useSnapshot } from './react/useSnapshot.js';
+export { useSelector } from './react/useSelector.js';

package/dist/esm/react/useSelector.js

@@ -0,0 +1,33 @@
+import { useState } from 'react';
+import { createSubscriber, getReactishValues, isEqual } from '../utils.js';
+import { useSnapshot } from './useSnapshot.js';
+
+const useSelector = (selectorParamFactory, deps) => {
+  const items = selectorParamFactory();
+  const cutoff = items.length - 1;
+  const selectorFunc = items[cutoff];
+  items.length = cutoff;
+  const [context] = useState(() => ({
+    sub: createSubscriber(items)
+  }));
+  const get = () => {
+    const {
+      cache
+    } = context;
+    const reactishValues = getReactishValues(items);
+    const args = reactishValues.concat(deps || selectorFunc);
+    if (cache && isEqual(args, cache.args)) return cache.val;
+    const val = selectorFunc(...reactishValues);
+    context.cache = {
+      args,
+      val
+    };
+    return val;
+  };
+  return useSnapshot({
+    get,
+    subscribe: context.sub
+  });
+};
+
+export { useSelector };

package/dist/esm/utils.js

@@ -0,0 +1,13 @@
+const isEqual = (args1, args2) => {
+  for (let i = 0; i < args1.length; i++) {
+    if (!Object.is(args1[i], args2[i])) return false;
+  }
+  return true;
+};
+const createSubscriber = items => listener => {
+  const unsubscribers = items.map(item => item.subscribe(listener));
+  return () => unsubscribers.forEach(unsubscribe => unsubscribe());
+};
+const getReactishValues = items => items.map(item => item.get());
+
+export { createSubscriber, getReactishValues, isEqual };

package/dist/esm/vanilla/selector.js

@@ -1,9 +1,5 @@
-const isEqual = (args1, args2) => {
-  for (let i = 0; i < args1.length; i++) {
-    if (!Object.is(args1[i], args2[i])) return false;
-  }
-  return true;
-};
+import { getReactishValues, createSubscriber, isEqual } from '../utils.js';
+
 const createSelector = ({
   plugin
 } = {}) => (...items) => {
@@ -17,19 +13,16 @@ const createSelector = ({
   let cache;
   const selector = {
     get: () => {
-      const args = items.map(item => item.get());
-      if (cache && isEqual(args, cache.args)) return cache.ret;
-      const ret = selectorFunc(...args);
+      const args = getReactishValues(items);
+      if (cache && isEqual(args, cache.args)) return cache.val;
+      const val = selectorFunc(...args);
       cache = {
         args,
-        ret
+        val
       };
-      return ret;
+      return val;
     },
-    subscribe: listener => {
-      const unsubscribers = items.map(item => item.subscribe(listener));
-      return () => unsubscribers.forEach(unsubscribe => unsubscribe());
-    }
+    subscribe: createSubscriber(items)
   };
   plugin == null ? void 0 : plugin(selector, config);
   return selector;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reactish-state",
-  "version": "0.10.4",
+  "version": "0.11.0",
   "description": "Simple, decentralized state management for React.",
   "author": "Zheng Song",
   "license": "MIT",
@@ -73,35 +73,35 @@
     "use-sync-external-store": "^1.2.0"
   },
   "devDependencies": {
-    "@babel/core": "^7.20.12",
-    "@babel/preset-env": "^7.20.2",
+    "@babel/core": "^7.21.4",
+    "@babel/preset-env": "^7.21.4",
     "@babel/preset-react": "^7.18.6",
-    "@babel/preset-typescript": "^7.18.6",
+    "@babel/preset-typescript": "^7.21.4",
     "@redux-devtools/extension": "^3.2.5",
     "@rollup/plugin-babel": "^6.0.3",
-    "@rollup/plugin-node-resolve": "^15.0.1",
+    "@rollup/plugin-node-resolve": "^15.0.2",
     "@testing-library/jest-dom": "^5.16.5",
-    "@testing-library/react": "^13.4.0",
-    "@types/jest": "^29.2.5",
-    "@types/react": "^18.0.26",
+    "@testing-library/react": "^14.0.0",
+    "@types/jest": "^29.5.0",
+    "@types/react": "^18.0.34",
     "@types/use-sync-external-store": "^0.0.3",
-    "@typescript-eslint/eslint-plugin": "^5.48.2",
-    "@typescript-eslint/parser": "^5.48.2",
+    "@typescript-eslint/eslint-plugin": "^5.58.0",
+    "@typescript-eslint/parser": "^5.58.0",
     "babel-plugin-pure-annotations": "^0.1.2",
-    "eslint": "^8.32.0",
-    "eslint-config-prettier": "^8.6.0",
+    "eslint": "^8.38.0",
+    "eslint-config-prettier": "^8.8.0",
     "eslint-plugin-jest": "^27.2.1",
-    "eslint-plugin-react": "^7.32.1",
+    "eslint-plugin-react": "^7.32.2",
     "eslint-plugin-react-hooks": "^4.6.0",
     "eslint-plugin-react-hooks-addons": "^0.3.1",
-    "immer": "^9.0.18",
-    "jest": "^29.3.1",
-    "jest-environment-jsdom": "^29.3.1",
+    "immer": "^9.0.21",
+    "jest": "^29.5.0",
+    "jest-environment-jsdom": "^29.5.0",
     "npm-run-all": "^4.1.5",
-    "prettier": "^2.8.3",
+    "prettier": "^2.8.7",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
-    "rollup": "^3.10.0",
-    "typescript": "^4.9.4"
+    "rollup": "^3.20.2",
+    "typescript": "^5.0.4"
   }
 }

package/types/common.d.ts

@@ -20,3 +20,13 @@ export interface Middleware {
 export interface Plugin {
     <T>(reactish: Reactish<T>, config?: Config): void;
 }
+export type ReactishArray = Reactish<unknown>[];
+export type ReactishValueArray<RA extends ReactishArray> = {
+    [index in keyof RA]: ReturnType<RA[index]['get']>;
+};
+export type SelectorFunc<RA extends ReactishArray, T> = (...args: ReactishValueArray<RA>) => T;
+export type SelectorParams<RA extends ReactishArray, T> = [...RA, SelectorFunc<RA, T>];
+export interface Selector {
+    <RA extends ReactishArray, T>(...items: SelectorParams<RA, T>): Reactish<T>;
+    <RA extends ReactishArray, T>(...items: [...SelectorParams<RA, T>, Config]): Reactish<T>;
+}

package/types/index.d.ts

@@ -2,3 +2,4 @@ export * from './common';
 export * from './vanilla/state';
 export * from './vanilla/selector';
 export * from './react/useSnapshot';
+export * from './react/useSelector';

package/types/react/useSelector.d.ts

@@ -0,0 +1,3 @@
+import type { ReactishArray, SelectorFunc, SelectorParams } from '../common';
+declare const useSelector: <RA extends ReactishArray, T>(selectorParamFactory: () => [...RA, SelectorFunc<RA, T>], deps?: unknown[]) => T;
+export { useSelector };

package/types/utils.d.ts

@@ -0,0 +1,4 @@
+import type { Subscriber, ReactishArray, ReactishValueArray } from './common';
+export declare const isEqual: (args1: unknown[], args2: unknown[]) => boolean;
+export declare const createSubscriber: (items: ReactishArray) => Subscriber;
+export declare const getReactishValues: <RA extends ReactishArray>(items: ReactishArray) => ReactishValueArray<RA>;

package/types/vanilla/selector.d.ts

@@ -1,13 +1,4 @@
-import type { Reactish, Plugin, Config } from '../common';
-type ReactishArray = Reactish<unknown>[];
-type ReactishValueArray<R extends ReactishArray> = {
-    [index in keyof R]: ReturnType<R[index]['get']>;
-};
-type SelectorFunc<R extends ReactishArray, T> = (...args: ReactishValueArray<R>) => T;
-interface Selector {
-    <R extends ReactishArray, T>(...items: [...R, SelectorFunc<R, T>]): Reactish<T>;
-    <R extends ReactishArray, T>(...items: [...R, SelectorFunc<R, T>, Config]): Reactish<T>;
-}
+import type { Plugin, Selector } from '../common';
 declare const createSelector: ({ plugin }?: {
     plugin?: Plugin | undefined;
 }) => Selector;