@chhsiao1981/use-thunk 11.0.0 → 13.0.0

package/README.md

@@ -2,39 +2,28 @@
 
 [![codecov](https://codecov.io/gh/chhsiao1981/use-thunk/branch/main/graph/badge.svg)](https://codecov.io/gh/chhsiao1981/use-thunk)
 
-A framework easily using `useThunk` to manage the data-state.
+A framework for easily managing global data state with `useThunk`, with [`zustand`](https://github.com/pmndrs/zustand)-like taste.
 
-Adopted concept of [redux-thunk](https://redux.js.org/usage/writing-logic-thunks) and [redux-duck](https://github.com/PlatziDev/redux-duck)
+Inspired by the concepts of [Redux Thunk](https://redux.js.org/usage/writing-logic-thunks) and [Redux Duck](https://github.com/PlatziDev/redux-duck).
 
-[src/useThunkReducer.ts](src/useThunkReducer.ts) is adopted from [nathanbuchar/react-hook-thunk-reducer](https://github.com/nathanbuchar/react-hook-thunk-reducer/blob/master/src/thunk-reducer.js).
+[src/useThunkReducer.ts](src/useThunkReducer.ts) is adapted from [nathanbuchar/react-hook-thunk-reducer](https://github.com/nathanbuchar/react-hook-thunk-reducer/blob/master/src/thunk-reducer.js).
 
-`use-thunk` is with the following additional features:
+For more information, please check [docs/00-introduction.md](docs/00-introduction.md).
 
-1. The development of the thunk modules follows the concept of `redux-duck`.
-2. Instead of action / reducer, we focus only on `thunk`, and have the primitive actions/reducers.
-
-Please check [docs/00-introduction.md](docs/00-introduction.md) for more information.
-
-Please check [demo-use-thunk](https://github.com/chhsiao1981/demo-use-thunk) for a demo to use Thunk.
-
-### Breaking Changes
-
-* Starting from `10.0.0`: The ClassState is shared globally, with `registerThunk` and `ThunkContext`.
-* Starting from `9.0.0`: npm package is renamed as [@chhsiao1981/use-thunk](https://www.npmjs.com/package/%40chhsiao1981/use-thunk)
-* Starting from `8.0.0`: [Totally renamed as `useThunk`](https://github.com/chhsiao1981/use-thunk/issues/105).
+For usage examples, please refer to [demo-use-thunk](https://github.com/chhsiao1981/demo-use-thunk).
 
 ## Install
 
     npm install --save @chhsiao1981/use-thunk
 
-## Example
+## Getting Started
 
-Thunk module able to do increment (reducers/increment.ts):
+Thunk module able to do increment (thunks/increment.ts):
 
 ```ts
-import { init as _init, setData, Thunk, getState, type State as rState, genUUID } from '@chhsiao1981/use-thunk'
+import { type Thunk, type State as rState, update } from '@chhsiao1981/use-thunk'
 
-export const myClass = 'demo/Increment'
+export const name = 'demo/Increment'
 
 export interface State extends rState {
   count: number
@@ -44,54 +33,53 @@ export const defaultState: State = {
   count: 0
 }
 
-export const init = (): Thunk<State> => {
-  const myID = genUUID()
-  return async (dispatch, getClassState) => {
-    dispatch(_init({myID, state: defaultState}))
+// upsert directly with set.
+export const increment = (myID: string, num: number = 1): Thunk<State> => {
+  return async (set, get) => {
+    let me = get(myID)
+    const {count} = me
+
+    set(myID, { count: count + num })
   }
 }
 
-export const increment = (myID: string): Thunk<State> => {
-  return async (dispatch, getClassState) => {
-    let classState = getClassState()
-    let me = getState(classState, myID)
-    if(!me) {
-      return
-    }
+// or we can treat set as dispatching a base action.
+export const increment2 = (myID: string): Thunk<State> => {
+  return async (set, get) => {
+    let me = get(myID)
+    const {count} = me
+
+    set(update({ count: count + 2 }))
+  }
+}
 
-    dispatch(setData(myID, { count: me.count + 1 }))
+// or we can use set as dispatching a thunk function.
+export const increment3 = (myID: string): Thunk<State> => {
+  return async (set) => {
+    set(increment(myID, 3))
   }
 }
 ```
 
-App.tsx:
+components/App.tsx:
 
 ```tsx
-import { type ThunkModuleToFunc, useThunk, getDefaultID, getState } from '@chhsiao1981/use-thunk'
-import * as DoIncrement from './reducers/increment'
-
-type TDoIncrement = ThunkModuleToFunc(typeof DoIncrement)
-
-type Props = {
-}
+import { type ThunkModuleToFunc, useThunk, getState } from '@chhsiao1981/use-thunk'
+import * as DoIncrement from './thunks/increment'
 
-export default (props: Props) => {
-  const [classStateIncrement, doIncrement] = useThunk<DoIncrement.State, TDoIncrement>(DoIncrement, StateType.LOCAL)
+type doIncrement = toDoModule(typeof DoIncrement)
 
-  //init
-  useEffect(() => {
-    doIncrement.init()
-  }, [])
-
-  // states
-  const incrementID = getDefaultID(classStateIncrement)
-  const increment = getState(classStateIncrement) || DoIncrement.defaultState
+export default () => {
+  const useIncrement = useThunk<DoIncrement.State, doIncrement>(DoIncrement)
+  const [increment, doIncrement, incrementID] = getState(useIncrement)
 
   // to render
   return (
     <div>
       <p>count: {increment.count}</p>
-      <button onClick={() => doIncrement.increment(incrementID)}>increase</button>
+      <button onClick={() => doIncrement.increment(incrementID)}>increase 1</button>
+      <button onClick={() => doIncrement.increment2(incrementID)}>increase 2</button>
+      <button onClick={() => doIncrement.increment3(incrementID)}>increase 3</button>
     </div>
   )
 }
@@ -102,8 +90,8 @@ main.tsx:
 import { registerThunk, ThunkContext } from "@chhsiao1981/use-thunk";
 import { StrictMode } from "react";
 import { createRoot } from "react-dom/client";
-import * as DoIncrement from './reducers/increment'
-import App from "./App.tsx";
+import * as DoIncrement from './thunks/increment'
+import App from "./components/App";
 
 registerThunk(DoIncrement)
 
@@ -116,47 +104,54 @@ createRoot(document.getElementById("root")!).render(
 )
 ```
 
+## Introduction
+
+
+
+## Development Pattern
 ### Must Included in a Thunk Module
 
 ```ts
 import type { State as rState } from '@chhsiao1981/use-thunk'
 
-// reducer class name.
-export const myClass = ""
+// Thunk-module name.
+export const name = ""
 
 // state definition of the reducer.
 export interface State extends rState {
 }
 
+export const defaultState: State = {}
+
 .
 .
 .
 ```
 
-### Must Included in a Top-level Component
+### Must Included in a Statically-allocated (always allocated) Component
 
 ```ts
-import { type ThunkModuleToFunc, useThunk, getDefaultID, getState } from '@chhsiao1981/use-thunk'
-import * as DoModule from '../reducers/module'
+import { type toDoModule, useThunk, getState } from '@chhsiao1981/use-thunk'
+import * as DoModule from '../thunks/module'
 
-type TDoModule = ThunkModuleToFunc<typeof DoModule>
+type doModule = toDoModule<typeof DoModule>
 
 const Component = () => {
-  const [stateModule, doModule] = useThunk<DoModule.State, TDoModule>(DoModule)
-
-  const moduleID = getDefaultID(stateModule)
-  const theModule = getState(stateModule)
+  const useModule = useThunk<DoModule.State, doModule>(DoModule)
+  const [module, doModule, moduleID] = getState(useModule)
 
-  .
-  .
-  .
+.
+.
+.
 }
 ```
 
-### Must Included in main.tsx
+### Must Included in `main.tsx`
 
 ```tsx
-registerThunk(...)
+import { registerThunk, ThunkContext } from '@chhsiao1981/use-thunk'
+import * as DoModule from '../thunks/module'
+registerThunk(DoModule)
 .
 .
 .
@@ -182,8 +177,8 @@ with the following features:
 For example, the example [in the redux link](https://redux.js.org/recipes/structuring-reducers/normalizing-state-shape) is represented as:
 
 ```ts
-classStatePost = {
-  myClass: 'post',
+moduleStatePost = {
+  name: 'post',
   nodes: {
     [uuid-post1] : {
       id: uuid-post1,
@@ -202,7 +197,7 @@ classStatePost = {
       }
     }
   },
-  defaultID,
+  defaultID,s
   defaultState,
 }
 ```
@@ -210,8 +205,8 @@ classStatePost = {
 and:
 
 ```ts
-classStateComment = {
-  myClass: 'comment',
+moduleStateComment = {
+  myClass: 'module',
   nodes: {
     [uuid-comment1] : {
       id: uuid-comment1,
@@ -256,8 +251,8 @@ classStateComment = {
 
 and:
 ```ts
-classStateUser = {
-  myClass: 'user',
+moduleStateUser = {
+  name: 'user',
   nodes: {
     [uuid-user1] : {
       id: uuid-user1,
@@ -288,52 +283,124 @@ classStateUser = {
 
 ## [APIs](https://github.com/chhsiao1981/use-thunk/blob/main/src/index.d.ts)
 
-### Basic
+#### Types
 
-##### `useThunk(theDo: ThunkModuleFunc): [ClassState, DispatchedFuncMap]`
+##### `type Thunk`
 
-Similar to `React.useReducer`, but we use `useThunk`, and we also bind the actions with dispatch (similar concept as `mapDispatchToProps`).s
+`Thunk` is defined as:
 
-return: `[ClassState<S>, DispatchedFuncMap<S, R>]`
+```ts
+export type Thunk<S extends State> = (
+  set: set<S>,
+  get: (id?: string) => S,
+  getOrNull: (id?: string) => S | null | undefined,
+  dispatch: dispatch<S>,
+  getModuleState: () => ModuleState<S>,
+) => void
+```
+
+We generally use only `set` and `get`.
+
+##### `ThunkModule<S extends State>`
+
+```ts
+export type ThunkModule<S extends State> = {
+  name: string
+  defaultState: S
+
+  // The rest of the variables are doModule.
+  // Specifying index-signatures to include all the variables.
+  [action: string]: ThunkFunc<S> | string | S
+}
+```
 
-##### `init({myID, parentID, doParent, state}, myuuidv4?)`
+##### `doModule<S extends State>`
 
-initializing the react-object.
+```ts
+export interface doModule<S extends State> {
+  [action: string]: ThunkFunc<S>
+}
+```
 
-##### `setData(myID, data)`
+##### `ThunkFunc<S extends State>`
 
-set the data to myID.
+```ts
+export type ThunkFunc<S extends State> = (...params: any[]) => Thunk<S>
+```
 
-##### `remove(myID, isFromParent=false)`
+#### RegisterThunk / ThunkContext / useThunk
 
-remove the react-object.
+##### `registerThunk(module: ThunkModule)`
 
-##### `genUUID(myuuidv4?: () => string): string`
+register a thunk module.
 
-generate uuid for react-object.
+##### `<ThunkContext>{children}</ThunkContext>`
 
-### State
+Rendering thunk context.
 
-##### `getState(state: ClassState, myID?: string): State | null`
+##### `useThunk(theDo: ThunkModule): UseThunk`
 
-Get the state of `myID`. Get the state of `defaultID` if `myID` is not present. Return `null` if not available.
+Similar to `React.useReducer`, but we use `useThunk`, and we also bind the actions with `set` (similar concept as `mapDispatchToProps`).
 
-##### `mustGetState(state: ClassState, myID?: string): State`
+return: `UseThunk`
 
-Get the state of `myID`. Get the state of `defaultID` if `myID` is not present. Return `defaultState` if not available.
+#### State
 
-##### `mustGetStateByThunk(theUseThunk: UseThunk, myID?: string): [State, DispatchedActionMap, theID]`
+##### `getState(theUseThunk: UseThunk, myID?: string): [state, doModule, theID]`
 
 Get the state of `myID` by `UseThunk`. Get the state of `defaultID` if `myID` is not present. Return `defaultState` if not available.
 
-return: `[S, DispatchedFuncMap<S, R>, theID]`
+return: `[state, doModule, theID]`
+o
+### Advanced Usage
+
+#### types
+
+##### `UseThunk`
+
+```ts
+export type UseThunk<S extends State, R extends doModule<S>> = [Readonly<ModuleState<S>>, setMap<S, R>]
+```
+
+##### `setMap`
+
+```ts
+export type setMap<S extends State, T extends doModule<S>> = {
+  [action in keyof T]: VoidReturnType<T[action]>
+} & Omit<DefaultSetMap, keyof T>
+```
 
-##### `getDefaultID(state: ClassState): string`
+#### Default Thunk Functions.
+
+##### `init({myID, parentID, doParent, state})`
+
+initialize the state.
+
+##### `update(myID, data)`
+
+update the data to myID.
+
+##### `upsert(myID, data)`
+
+initialize the state if it does not exist, and update the data to myID.
+
+##### `remove(myID)`
+
+remove the state.
+
+#### State
+
+##### `getStateOrNullByModule(moduleState: ModuleState, myID?: string): state | null`
+
+Get the state of `myID`. Get the state of `defaultID` if `myID` is not present. Return `null` if not available.
+
+##### `getStateByModule(moduleState: ModuleState, myID?: string): state`
+
+Get the state of `myID`. Get the state of `defaultID` if `myID` is not present. Return `defaultState` if not available.
 
-get the default id.
+#### Misc
 
-### NodeState
+##### `genID(): string`
 
-##### `getNode(state: ClassState, myID?: string): NodeState`
+generate id for the state.
 
-Get the node of `myID`. Get the node of `defaultID` if `myID` is not present.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chhsiao1981/use-thunk",
-  "version": "11.0.0",
+  "version": "13.0.0",
   "type": "module",
   "description": "A framework easily using useThunk to manage the data-state.",
   "homepage": "https://github.com/chhsiao1981/use-thunk",
@@ -36,28 +36,22 @@
   },
   "license": "MIT",
   "devDependencies": {
-    "@codecov/vite-plugin": "^1.9.1",
-    "@eslint/js": "^9.39.4",
-    "@types/node": "^25.5.0",
+    "@codecov/vite-plugin": "^2.0.1",
+    "@types/node": "^25.9.3",
     "@types/react": ">=18.3.1",
     "@types/react-dom": ">=18.3.1",
-    "@vitejs/plugin-react-swc": "^4.3.0",
-    "@vitest/coverage-v8": "^4.1.0",
-    "eslint": "^9.39.4",
-    "eslint-plugin-react-hooks": "^7.0.1",
-    "eslint-plugin-react-refresh": "^0.5.2",
-    "globals": "^17.4.0",
-    "happy-dom": "^20.8.4",
-    "jiti": "^2.6.1",
+    "@vitejs/plugin-react-swc": "^4.3.1",
+    "@vitest/coverage-v8": "^4.1.8",
+    "globals": "^17.6.0",
+    "happy-dom": "^20.10.2",
+    "jiti": "^2.7.0",
     "react-dom": ">=18.3.1",
     "rimraf": "^6.1.3",
     "typescript": "~5.9.3",
-    "typescript-eslint": "^8.57.1",
     "vite": "^6.4.1",
-    "vitest": "^4.1.0"
+    "vitest": "^4.1.8"
   },
   "peerDependencies": {
-    "react": ">=18.3.1",
-    "uuid": "^14.0.0"
+    "react": ">=18.3.1"
   }
 }

package/src/action/ActionOrThunk.ts

@@ -1,4 +1,4 @@
-import type { State } from '../stateTypes'
+import type { State } from '../states'
 import type BaseAction from './baseAction'
 import type { Thunk } from './thunk'
 

package/src/action/index.ts

@@ -1,4 +1,4 @@
-import type { ModuleState, State } from '../stateTypes'
+import type { ModuleState, State } from '../states'
 import type { ActionOrThunk } from './ActionOrThunk'
 import type BaseAction from './baseAction'
 import type { Thunk } from './thunk'
@@ -12,5 +12,5 @@ export type ActionFunc<S extends State> = (...params: any[]) => ActionOrThunk<S>
 // biome-ignore lint/suspicious/noExplicitAny: params can by any type.
 export type ThunkFunc<S extends State> = (...params: any[]) => Thunk<S>
 
-// GetModuleState
-export type GetModuleState<S extends State> = () => ModuleState<S>
+// getModuleState
+export type getModuleState<S extends State> = () => ModuleState<S>

package/src/action/thunk.ts

@@ -1,5 +1,13 @@
+import type { dispatch } from '../dispatch'
+import type { get, getOrNull } from '../get'
 import type { set } from '../set'
-import type { ModuleState, State } from '../stateTypes'
+import type { ModuleState, State } from '../states'
 
 // Thunk
-export type Thunk<S extends State> = (set: set<S>, getModuleState: () => ModuleState<S>) => void
+export type Thunk<S extends State> = (
+  set: set<S>,
+  get: get<S>,
+  getOrNull: getOrNull<S>,
+  dispatch: dispatch<S>,
+  getModuleState: () => ModuleState<S>,
+) => void

package/src/defaultThunks/index.ts

@@ -0,0 +1,15 @@
+// default thunks will be used in thunkModule/defaultDoModule and defaultReduceMap
+import { INIT, type InitParams, init, reduceInit } from './init'
+export { INIT, type InitParams, init, reduceInit }
+
+import { reduceUpdate, UPDATE, update } from './update'
+export { reduceUpdate, UPDATE, update }
+
+import { REMOVE, reduceRemove, remove } from './remove'
+export { REMOVE, reduceRemove, remove }
+
+import { reduceUpsert, UPSERT, upsert } from './upsert'
+export { UPSERT, upsert, reduceUpsert }
+
+import { reduceSetDefaultID, SET_DEFAULT_ID, setDefaultID } from './setDefaultID'
+export { SET_DEFAULT_ID, setDefaultID, reduceSetDefaultID }

package/src/defaultThunks/init/index.ts

@@ -0,0 +1,27 @@
+import type { Thunk } from '../../action'
+import type { State } from '../../states'
+import { genID } from '../../utils'
+import { setDefaultID } from '../setDefaultID'
+import initCore, { INIT, reduceInit } from './initCore'
+export { INIT, reduceInit }
+
+// InitParams
+export interface InitParams<S extends State> {
+  myID?: string
+  state: S
+}
+
+export const init = <S extends State>(params: InitParams<S>): Thunk<S> => {
+  return (set, _get, _getOrNull, _dispatch, getModuleState) => {
+    const myID = params.myID ?? genID()
+
+    const { state } = params
+    set(initCore(myID, state))
+
+    const { defaultID } = getModuleState()
+
+    if (!defaultID) {
+      set(setDefaultID(myID))
+    }
+  }
+}

package/src/{init → defaultThunks/init}/initCore.ts

@@ -1,5 +1,5 @@
-import type BaseAction from '../action/baseAction'
-import type { ModuleState, NodeState, NodeStateMap, State } from '../stateTypes'
+import type { BaseAction } from '../../action'
+import type { ModuleState, NodeState, NodeStateMap, State } from '../../states'
 
 export interface InitAction<S extends State> extends BaseAction {
   state: S

package/src/{remove.ts → defaultThunks/remove.ts}

@@ -1,5 +1,5 @@
-import type BaseAction from './action/baseAction'
-import type { ModuleState, NodeStateMap, State } from './stateTypes'
+import type { BaseAction } from '../action'
+import type { ModuleState, NodeStateMap, State } from '../states'
 
 export const REMOVE = '@chhsiao1981/use-thunk/REMOVE'
 export const remove = (myID: string): BaseAction => ({

package/src/{setDefaultID.ts → defaultThunks/setDefaultID.ts}

@@ -1,5 +1,5 @@
-import type BaseAction from './action/baseAction'
-import type { ModuleState, State } from './stateTypes'
+import type { BaseAction } from '../action'
+import type { ModuleState, State } from '../states'
 
 export const SET_DEFAULT_ID = '@chhsiao1981/use-thunk/SET_DEFAULT_ID'
 export const setDefaultID = (myID: string): BaseAction => ({
@@ -13,5 +13,6 @@ export const reduceSetDefaultID = <S extends State>(
 ): ModuleState<S> => {
   const { myID } = action
 
-  return Object.assign({}, moduleState, { defaultID: myID })
+  const toUpdate: Partial<ModuleState<S>> = { defaultID: myID, isInitDefaultID: true }
+  return Object.assign({}, moduleState, toUpdate)
 }

package/src/{update.ts → defaultThunks/update.ts}

@@ -1,5 +1,5 @@
-import type BaseAction from './action/baseAction'
-import type { ModuleState, State } from './stateTypes'
+import type { BaseAction } from '../action'
+import type { ModuleState, State } from '../states'
 
 export const UPDATE = '@chhsiao1981/use-thunk/UPDATE'
 export const update = <S extends State>(myID: string, data: Partial<S>): BaseAction => ({
@@ -8,11 +8,6 @@ export const update = <S extends State>(myID: string, data: Partial<S>): BaseAct
   data,
 })
 
-export const setData = <S extends State>(myID: string, data: Partial<S>): BaseAction => {
-  console.warn('setData will be deprecated in the next version.')
-  return update(myID, data)
-}
-
 export const reduceUpdate = <S extends State>(
   moduleState: ModuleState<S>,
   action: BaseAction,

package/src/defaultThunks/upsert.ts

@@ -0,0 +1,27 @@
+import type { BaseAction } from '../action'
+import type { ModuleState, NodeState, State } from '../states'
+import { deepCopy } from '../utils'
+
+export const UPSERT = '@chhsiao1981/use-thunk/UPSERT'
+export const upsert = <S extends State>(myID: string, data: Partial<S>): BaseAction => ({
+  myID,
+  type: UPSERT,
+  data,
+})
+
+export const reduceUpsert = <S extends State>(
+  moduleState: ModuleState<S>,
+  action: BaseAction,
+): ModuleState<S> => {
+  const { myID, data } = action
+
+  const myNode = moduleState.nodes[myID]
+  const node: NodeState<S> = myNode ?? { id: myID, state: deepCopy(moduleState.defaultState) }
+
+  const newState = Object.assign({}, node.state, data)
+  const newNode = Object.assign({}, node, { state: newState })
+  const newNodes = Object.assign({}, moduleState.nodes, { [myID]: newNode })
+  const newModuleState = Object.assign({}, moduleState, { nodes: newNodes })
+
+  return newModuleState
+}

package/src/dispatch.ts

@@ -0,0 +1,7 @@
+import type { Dispatch } from 'react'
+// XXX requiring to import directly from action/ActionOrThunk, or it will cause looping.
+import type { ActionOrThunk } from './action'
+import type { State } from './states'
+
+// dispatch
+export type dispatch<S extends State> = Dispatch<ActionOrThunk<S>>

package/src/get.ts

@@ -0,0 +1,4 @@
+import type { State } from './states'
+
+export type get<S extends State> = (id?: string) => S
+export type getOrNull<S extends State> = (id?: string) => S | null | undefined