reactish-state 1.0.0-alpha.1 → 1.0.0-alpha.3

package/README.md

@@ -2,7 +2,9 @@
 
 > Simple, decentralized (atomic) state management for React.
 
-[![NPM](https://img.shields.io/npm/v/reactish-state.svg)](https://www.npmjs.com/package/reactish-state) [![NPM](https://img.shields.io/bundlephobia/minzip/reactish-state)](https://bundlephobia.com/package/reactish-state)
+[![NPM](https://img.shields.io/npm/v/reactish-state.svg)](https://www.npmjs.com/package/reactish-state) [![NPM](https://img.shields.io/bundlephobia/minzip/reactish-state)](https://bundlephobia.com/package/reactish-state) [![bundlejs](https://img.shields.io/badge/bundlejs-.com-blue.svg)](https://bundlejs.com/?q=reactish-state&treeshake=%5B*%5D&config=%7B%22esbuild%22%3A%7B%22external%22%3A%5B%22react%22%5D%7D%7D)
+
+💡 [Quick examples](#examples)    🔧 [TypeScript usage](#typescript-usage)
 
 ## ✨Highlights✨
 
@@ -43,7 +45,7 @@ countState.set(10);
 console.log(countState.get()); // Print 10
 ```
 
-### A state can also have actions bound to it
+### A state can also have custom actions bound to it
 
 ```js
 const countState = state(0, (set, get) => ({
@@ -55,8 +57,8 @@ const countState = state(0, (set, get) => ({
   decrease: () => set(get() - 1)
 }));
 
-// Use the actions
-countState.actions.increase();
+// Use the custom actions
+countState.increase();
 ```
 
 ### `selector` can create derived state
@@ -90,9 +92,10 @@ const Example = () => {
 
   return (
     <h1>
+      {/* The return values of `useSnapshot` are used for rendering */}
       {count} {triple}
-      {/* Update the state using the actions bound to it */}
-      <button onClick={() => countState.actions.increase()}>Increase</button>
+      {/* Update the state using the custom actions bound to it */}
+      <button onClick={() => countState.increase()}>Increase</button>
       {/* Or update the state using the `set` method directly */}
       <button onClick={() => countState.set((i) => i - 1)}>Decrease</button>
       <button onClick={() => countState.set(0)}>Reset</button>
@@ -232,11 +235,14 @@ You can also create async actions bound to a state:
 
 ```js
 const todosState = state([], (set) => ({
-  fetch: async (url) => {
-    const response = await fetch(url);
+  fetchData: async () => {
+    const response = await fetch(/* some url */);
     set(await response.json());
   }
 }));
+
+// Use the async action
+await todosState.fetchData();
 ```
 
 ## Accessing other state or selectors inside actions
@@ -293,7 +299,7 @@ const countState = state(0, (set) => ({
   increase: () => set((count) => count + 1),
   reset: () => set(0)
 }));
-const { increase, reset } = countState.actions;
+const { increase, reset } = countState;
 
 const Example = () => {
   const count = useSnapshot(countState);
@@ -372,7 +378,7 @@ const countState = state(0, (set) => ({
   dispatch: (action) => set((state) => reducer(state, action), action)
 }));
 
-const { dispatch } = countState.actions;
+const { dispatch } = countState;
 dispatch({ type: "INCREASE", by: 10 });
 dispatch({ type: "DECREASE", by: 7 });
 console.log(countState.get()); // Print 3
@@ -401,7 +407,7 @@ const countState = state(0, (set) => ({
 }));
 
 countState.set(99); // Print "New state 99"
-countState.actions.increase(); // Print "New state 100"
+countState.increase(); // Print "New state 100"
 
 // The same `state` function can be reused,
 // so you don't need to set up the middleware again
@@ -473,8 +479,8 @@ const todos = state([], (set) => ({
 }));
 
 // Use the actions
-todos.actions.add("Shop groceries");
-todos.actions.toggle(1);
+todos.add("Shop groceries");
+todos.toggle(1);
 ```
 
 ## Redux devtools middleware
@@ -588,6 +594,68 @@ const selector = createSelector({ plugin: reduxDevtools() });
 // Then use the `selector` as usual...
 ```
 
+# TypeScript usage
+
+The API relies on type inference to correctly infer the types for both the value and actions of the state. There are two scenarios:
+
+## I. The type of state can be inferred from its initial value
+
+In this case, the usage in TypeScript should be identical to JavaScript. You don't need to make any specific effort regarding typing. This is true when the state holds simple or primitive values.
+
+```ts
+const countState = state(0, (set) => ({
+  increase: (by: number) =>
+    set(
+      (count) => count + by
+      // The `count` is inferred as a number type from the initial value.
+    )
+}));
+```
+
+## II. The type of state cannot be inferred from its initial value
+
+In this case, you have three options:
+
+### 1. Use a type assertion to specify a more specific type for the initial value:
+
+```ts
+const myTodos = state([] as string[], (set) => ({
+  add: (newTodo: string) => set((todos) => [...todos, newTodo])
+}));
+```
+
+This is the simplest approach since the types for custom actions will be automatically inferred.
+
+### 2. Declare the initial value separately with a specific type:
+
+```ts
+const initialValue: string[] = [];
+const myTodos = state(initialValue, (set) => ({
+  add: (newTodo: string) => set((todos) => [...todos, newTodo])
+}));
+```
+
+This is basically very similar to the first method, except you need to write an additional line of code. The types for actions will be automatically inferred.
+
+### 3. Specify type parameters explicitly:
+
+```ts
+const myTodos = state<string[], { add: (newTodo: string) => void }>(
+  [],
+  (set) => ({
+    add: (newTodo) => set((todos) => [...todos, newTodo])
+  })
+);
+```
+
+However, if you choose this method, you need to specify the types for both the state value and actions.
+
+# Examples
+
+- Counter – [sandbox](https://codesandbox.io/p/sandbox/reactish-counter-z42qt7) | [source](https://github.com/szhsin/reactish-state/tree/master/examples/examples/counter)
+- Todo app – [sandbox](https://codesandbox.io/s/reactish-todo-thyhbl) | [source](https://github.com/szhsin/reactish-state/tree/master/examples/examples/todo)
+- Async – [sandbox](https://codesandbox.io/s/reactish-async-2cghkg) | [source](https://github.com/szhsin/reactish-state/tree/master/examples/examples/async)
+
 # React 16/17 setup
 
 When using this library with React 16/17, you must set up a shim since it doesn't include a native [useSyncExternalStore](https://react.dev/reference/react/useSyncExternalStore). We don't set up the shim by default to minimize the bundle size for React 18/19 users.
@@ -599,9 +667,3 @@ setReactShim(reactShim);
 ```
 
 You only need to set it up once after your app launches, outside of React code. DO NOT call `setReactShim` within any React components.
-
-# Examples
-
-- Counter – [sandbox](https://codesandbox.io/p/sandbox/reactish-counter-z42qt7) | [source](https://github.com/szhsin/reactish-state/tree/master/examples/examples/counter)
-- Todo app – [sandbox](https://codesandbox.io/s/reactish-todo-thyhbl) | [source](https://github.com/szhsin/reactish-state/tree/master/examples/examples/todo)
-- Async – [sandbox](https://codesandbox.io/s/reactish-async-2cghkg) | [source](https://github.com/szhsin/reactish-state/tree/master/examples/examples/async)

package/dist/cjs/react/useSnapshot.cjs

@@ -7,7 +7,7 @@ const useSnapshot = ({
   get
 }) => {
   if (process.env.NODE_ENV !== 'production' && !shim.useSyncExternalStore) {
-    throw new Error('[reactish-state] Shim setup is required for React 16/17.');
+    throw new Error('[reactish-state] Shim setup is required for React 16/17. See: https://github.com/szhsin/reactish-state/tree/master?tab=readme-ov-file#react-1617-setup');
   }
   return shim.useSyncExternalStore(subscribe, get, get);
 };

package/dist/cjs/vanilla/state.cjs

@@ -23,10 +23,10 @@ const createState = ({
     subscribe
   }, config);
   return {
+    ...actionCreator?.(set, get),
     get,
     set,
-    subscribe,
-    actions: actionCreator?.(set, get)
+    subscribe
   };
 };
 const state = /*#__PURE__*/createState();

package/dist/esm/react/useSnapshot.mjs

@@ -5,7 +5,7 @@ const useSnapshot = ({
   get
 }) => {
   if (process.env.NODE_ENV !== 'production' && !useSyncExternalStore) {
-    throw new Error('[reactish-state] Shim setup is required for React 16/17.');
+    throw new Error('[reactish-state] Shim setup is required for React 16/17. See: https://github.com/szhsin/reactish-state/tree/master?tab=readme-ov-file#react-1617-setup');
   }
   return useSyncExternalStore(subscribe, get, get);
 };

package/dist/esm/vanilla/state.mjs

@@ -21,10 +21,10 @@ const createState = ({
     subscribe
   }, config);
   return {
+    ...actionCreator?.(set, get),
     get,
     set,
-    subscribe,
-    actions: actionCreator?.(set, get)
+    subscribe
   };
 };
 const state = /*#__PURE__*/createState();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "reactish-state",
-  "version": "1.0.0-alpha.1",
-  "description": "Simple, decentralized state management for React.",
+  "version": "1.0.0-alpha.3",
+  "description": "Simple, decentralized (atomic) state management for React.",
   "author": "Zheng Song",
   "license": "MIT",
   "repository": {
@@ -37,7 +37,7 @@
     "lint:fix": "eslint --fix .",
     "pret": "prettier -c .",
     "pret:fix": "prettier -w .",
-    "build": "run-s pret lint clean types bundle",
+    "build": "run-s pret clean types lint bundle",
     "test": "jest",
     "test:watch": "jest --watch",
     "eg": "npm run dev --prefix examples"

package/types/vanilla/state.d.ts

@@ -1,12 +1,12 @@
 import type { Reactish, Setter, Config, Middleware } from '../common';
 type ActionCreator<T, A> = ((set: Setter<T>, get: () => T) => A) | null | undefined;
-interface State<T, A = unknown, C extends ActionCreator<T, A> = undefined> extends Reactish<T> {
+type VanillaState<T> = Reactish<T> & {
     set: Setter<T>;
-    actions: C extends undefined ? never : A;
-}
+};
+type State<T, A> = Omit<A, keyof VanillaState<T>> & VanillaState<T>;
 declare const createState: ({ middleware }?: {
     middleware?: Middleware;
-}) => <T, A>(initialValue: T, actionCreator?: ActionCreator<T, A>, config?: Config) => State<T, A, ActionCreator<T, A>>;
-declare const state: <T, A>(initialValue: T, actionCreator?: ActionCreator<T, A>, config?: Config) => State<T, A, ActionCreator<T, A>>;
+}) => <T, A>(initialValue: T, actionCreator?: ActionCreator<T, A>, config?: Config) => State<T, A>;
+declare const state: <T, A>(initialValue: T, actionCreator?: ActionCreator<T, A>, config?: Config) => State<T, A>;
 export type { State, ActionCreator };
 export { state, createState };