@chhsiao1981/use-thunk 9.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Chuan-Heng Hsiao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,437 @@
+# use-thunk
+
+[![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.
+
+Adopted concept of [redux-thunk](https://redux.js.org/usage/writing-logic-thunks) and [redux-duck](https://github.com/PlatziDev/redux-duck)
+
+[src/thunk-reducer.ts](src/thunkReducer.ts) is adopted 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:
+
+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.
+
+### Breaking Changes
+
+* 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).
+
+## Install
+
+    npm install --save @chhsiao1981/use-thunk
+
+## Example
+
+Thunk module able to do increment (reducers/increment.ts):
+
+```ts
+import { init as _init, setData, createReducer, Thunk, getState, type State as rState, genUUID } from '@chhsiao1981/use-thunk'
+
+export const myClass = 'demo/Increment'
+
+export interface State extends rState {
+  count: number
+}
+
+export const defaultState: State = {
+  count: 0
+}
+
+export const init = (): Thunk<State> => {
+  const myID = genUUID()
+  return async (dispatch, getClassState) => {
+    dispatch(_init({myID, state: defaultState}))
+  }
+}
+
+export const increment = (myID: string): Thunk<State> => {
+  return async (dispatch, getClassState) => {
+    let classState = getClassState()
+    let me = getState(classState, myID)
+    if(!me) {
+      return
+    }
+
+    dispatch(setData(myID, { count: me.count + 1 }))
+  }
+}
+```
+
+App.tsx:
+
+```tsx
+import { type ThunkModuleToFunc, useThunk, getRootID, getState } from '@chhsiao1981/use-thunk'
+import * as DoIncrement from './reducers/increment'
+
+type TDoIncrement = ThunkModuleToFunc(typeof DoIncrement)
+
+type Props = {
+}
+
+export default (props: Props) => {
+  const [stateIncrement, doIncrement] = useThunk<DoIncrement.State, TDoIncrement>(DoIncrement, StateType.LOCAL)
+
+  //init
+  useEffect(() => {
+    doIncrement.init()
+  }, [])
+
+  // to render
+  const incrementID = getRootID(stateIncrement)
+  const increment = getState(stateIncrement)
+  if(!increment) {
+    return (<div styles={{display: 'none'}}></div>)
+  }
+
+  return (
+    <div>
+      <p>count: {increment.count}</p>
+      <button onClick={() => doIncrement.increment(incrementID)}>increase</button>
+    </div>
+  )
+}
+```
+
+### Must Included in a Thunk Module
+
+```ts
+import type { State as rState } from '@chhsiao1981/use-thunk'
+
+// reducer class name.
+export const myClass = ""
+
+// state definition of the reducer.
+export interface State extends rState {
+}
+
+.
+.
+.
+```
+
+### Must Included in a Top-level Component
+
+```ts
+import { type ThunkModuleToFunc, useThunk, getRootID, getState } from '@chhsiao1981/use-thunk'
+import * as DoModule from '../reducers/module'
+
+type TDoModule = ThunkModuleToFunc<typeof DoModule>
+
+const Component = () => {
+  const [stateModule, doModule] = useThunk<DoModule.State, TDoModule>(DoModule)
+
+  const moduleID = getRootID(stateModule)
+  const theModule = getState(stateModule)
+
+  .
+  .
+  .
+}
+```
+
+## Normalized State
+
+The general concept of normalized state can be found in [Normalizing State Shape](https://redux.js.org/recipes/structuring-reducers/normalizing-state-shape)
+with the following features:
+
+1. ClassState: the state of the class, including the nodes and the root of the class.
+2. NodeState: the state of a node, including the id, children, parent, links of the node, and the content (state) of the node.
+3. State: the content of the node, represented as a state.
+4. The concept of "parent" and "children" and "links" is embedded in the NodeState.
+    * remove (me):
+        - initiate "remove" for all the children.
+        - remove from the parent.
+        - remove from all the links.
+    * remove child:
+        - the child initiate "remove".
+    * remove link:
+        - the link initiate "remove link" on me.
+4. To avoid complication, currently there is only 1 parent.
+
+For example, the example [in the redux link](https://redux.js.org/recipes/structuring-reducers/normalizing-state-shape) is represented as:
+
+```ts
+statePost = {
+  myClass: 'post',
+  doMe: (DispatchedAction<Post>),
+  nodes: {
+    [uuid-post1] : {
+      id: uuid-post1,
+      state: {
+        author : uuid-user1,
+        body : "......",
+      },
+      _parent: {
+        id: uuid-user1,
+        do: doUser
+      },
+      _links: {
+        comment : {
+          list: [uuid-comment1, uuid-comment2],
+          do: doComment
+        }
+      }
+    },
+    [uuid-post2] : {
+      id : uuid-post2,
+      state: {
+        author : uuid-user2,
+        body : "......",
+      },
+      _parent: {
+        id: uuid-user2,
+        do: doUser
+      },
+      _links: {
+        comment : {
+          list: [uuid-comment3, uuid-comment4, uuid-comment5],
+          do: doComment
+        }
+      }
+    }
+  }
+}
+```
+
+and:
+
+```ts
+stateComment = {
+  myClass: 'comment',
+  doMe: (DispatchedAction<Comment>),
+  nodes: {
+    [uuid-comment1] : {
+      id: uuid-comment1,
+      state: {
+        author : uuid-user2,
+        comment : ".....",
+      },
+      _parent: {
+        id: uuid-user2,
+        do: doUser
+      },
+      _links: {
+        post: {
+          list: [uuid-post1],
+          do: doPost
+        }
+      }
+    },
+    [uuid-comment2] : {
+      id : uuid-comment2,
+      state: {
+        author : uuid-user3,
+        comment : ".....",
+      },
+      _parent: {
+        id: uuid-user3,
+        do: doUser
+      },
+      _links: {
+        post: {
+          list: [uuid-post1],
+          do: doPost
+        }
+      }
+    },
+    [uuid-comment3] : {
+      id : uuid-comment3,
+      state: {
+        author : uuid-user3,
+        comment : ".....",
+      },
+      _parent: {
+        id: uuid-user3,
+        do: doUser
+      },
+      _links: {
+        post: {
+          list: [uuid-post2],
+          do: doPost
+        }
+      }
+    },
+    [uuid-comment4] : {
+      id : uuid-comment4,
+      state: {
+        author : uuid-user1,
+        comment : ".....",
+      },
+      _parent: {
+        id: uuid-user1,
+        do: doUser
+      },
+      _links: {
+        post: {
+          list: [uuid-post2],
+          do: doPost
+        }
+      }
+    },
+    [uuid-comment5] : {
+      id : uuid-comment5,
+      state: {
+        author : uuid-user3,
+        comment : ".....",
+      },
+      _parent: {
+        id: uuid-user3,
+        do: doUser
+      },
+      _links: {
+        post: {
+          list: [uuid-post2],
+          do: doPost
+        }
+      }
+    },
+  }
+}
+```
+
+and:
+```ts
+stateUser = {
+  myClass: 'user',
+  doMe: (DispatchedAction<User>),
+  nodes: {
+    [uuid-user1] : {
+      id: uuid-user1,
+      state: {
+        username : "user1",
+        name : "User 1",
+      },
+      _children: {
+        post: {
+          list: [uuid-post1],
+          do: doPost,
+        },
+        comment: {
+          list: [uuid-comment4],
+          do: doComment,
+        }
+      }
+    },
+    [uuid-user2] : {
+      id: uuid-user2,
+      state: {
+        username : "user2",
+        name : "User 2",
+      },
+      _children: {
+        post: {
+          list: [uuid-post2],
+          do: doPost,
+        },
+        comment: {
+          list: [uuid-comment1],
+          do: doComment,
+        }
+      }
+    },
+    [uuid-user3] : {
+      id: uuid-user3,
+      state: {
+        username : "user3",
+        name : "User 3",
+      },
+      _children: {
+        post: {
+          list: [uuid-post1],
+          do: doPost,
+        },
+        comment: {
+          list: [uuid-comment2, uuid-comment3, uuid-comment5],
+          do: doComment,
+        }
+      }
+    }
+  }
+}
+```
+
+## [APIs](https://github.com/chhsiao1981/use-thunk/blob/main/src/index.d.ts)
+
+### Basic
+
+##### `useThunk(theDo: ThunkModuleFunc): [ClassState, DispatchedAction]`
+
+Similar to `React.useReducer`, but we use `useThunk`, and we also bind the actions with dispatch (similar concept as `mapDispatchToProps`).s
+
+return: `[ClassState<S>, DispatchedAction<S>]`
+
+##### `init({myID, parentID, doParent, state}, myuuidv4?)`
+
+initializing the react-object.
+
+##### `genUUID(myuuidv4?: () => string): string`
+
+generate uuid for react-object.
+
+##### `setData(myID, data)`
+
+set the data to myID.
+
+##### `remove(myID, isFromParent=false)`
+
+remove the react-object.
+
+### State
+
+##### `getState(state: ClassState, myID?: string): State`
+
+Get the state of `myID`. Get the state of `rootID` if `myID` is not present.
+
+##### `getRootID(state: ClassState): string`
+
+get the root id.
+
+### NodeState
+
+##### `getNode(state: ClassState, myID: string): NodeState`
+
+Get the node of `myID`. Get the node of `rootID` if `myID` is not present.s
+
+##### `getChildIDs(me: NodeState, childClass: string): string[]`
+
+get the child-ids of the childClass.
+
+##### `getChildID(me: NodeState, childClass: string): string`
+
+get the only child-id (`childIDs[0]`) of the childClass.
+
+
+##### `getLinkIDs(me: NodeState, linkClass string): string[]`
+
+get the link-ids of the linkClass.
+
+
+##### `getLinkID(me: NodeState, linkClass): string`
+
+get the only link-id (`linkIDs[0]`) of the linkClass.
+
+### Children
+
+##### `addChild(myID, child)`
+
+params:
+* child: `{id, theClass, do}`
+
+##### `removeChild(myID, childID, childClass, isFromChild=false)`
+
+remove the child (and delete the child) of `myID`.
+
+### Link
+
+##### `addLink(myID, link, isFromLink=false)`
+
+params:
+* link: `{id, theClass, do}`
+
+##### `removeLink(myID, linkID, linkClass, isFromLink=false)`
+
+remove the link of `myID` (and remove the link from linkID).

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@chhsiao1981/use-thunk",
+  "version": "9.0.0",
+  "type": "module",
+  "description": "A framework easily using useThunk to manage the data-state.",
+  "homepage": "https://github.com/chhsiao1981/use-thunk",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chhsiao1981/use-thunk"
+  },
+  "main": "src/index.ts",
+  "types": "types/index.d.ts",
+  "files": [
+    "src",
+    "dist",
+    "types"
+  ],
+  "author": {
+    "name": "Chuan-Heng Hsiao",
+    "email": "hsiao.chuanheng@gmail.com"
+  },
+  "keywords": [
+    "react",
+    "useThunk"
+  ],
+  "scripts": {
+    "clean:lib": "rimraf ./dist/* ./types/*",
+    "compile:lib": "vite build",
+    "build:lib": "npm run clean:lib && npm run types && npm run compile:lib",
+    "build": "npm run build:lib",
+    "lint": "biome lint --error-on-warnings",
+    "test": "vitest run",
+    "types": "tsc -b",
+    "coverage": "vitest run --coverage --reporter=junit --outputFile=test-report.junit.xml",
+    "tsd": "npx -p typescript tsc src/*.ts --declaration --allowJs --emitDeclarationOnly --strict --outDir types"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@codecov/vite-plugin": "^1.9.1",
+    "@eslint/js": "^9.33.0",
+    "@types/node": "^24.3.0",
+    "@types/react": ">=18.3.1",
+    "@types/react-dom": ">=18.3.1",
+    "@vitejs/plugin-react-swc": "^4.0.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "eslint": "^9.33.0",
+    "eslint-plugin-react-hooks": "^5.2.0",
+    "eslint-plugin-react-refresh": "^0.4.20",
+    "globals": "^16.3.0",
+    "happy-dom": "^20.0.0",
+    "jiti": "^2.5.1",
+    "react-dom": ">=18.3.1",
+    "rimraf": "^6.0.1",
+    "typescript": "~5.9.3",
+    "typescript-eslint": "^8.46.0",
+    "vite": "^6.3.6",
+    "vitest": "^3.2.4"
+  },
+  "dependencies": {
+    "react": ">=18.3.1",
+    "uuid": "^11.1.0"
+  }
+}

package/src/action.ts

@@ -0,0 +1,20 @@
+import type { ClassState, State } from './stateTypes'
+import type { ActionOrThunk as rActionOrThunk, Thunk as rThunk } from './thunkReducer'
+
+// BaseAction contains only object-based actions, no thunk-based actions.
+export interface BaseAction {
+  myID: string
+  type: string
+  [key: string]: unknown
+}
+// Thunk
+export type Thunk<S extends State> = rThunk<ClassState<S>, BaseAction>
+
+export type ActionOrThunk<S extends State> = rActionOrThunk<ClassState<S>, BaseAction>
+
+// ActionFunc
+// biome-ignore lint/suspicious/noExplicitAny: unknown requires same type in list. use any for possible different types.
+export type ActionFunc<S extends State> = (...params: any[]) => ActionOrThunk<S>
+
+// GetClassState
+export type GetClassState<S extends State> = () => ClassState<S>

package/src/addChild.ts

@@ -0,0 +1,13 @@
+import { type AddRelationAction, reduceAddRelation } from './addRelation'
+import { type ClassState, type NodeMeta, Relation, type State } from './stateTypes'
+
+export const ADD_CHILD = '@chhsiao1981/use-thunk/ADD_CHILD'
+export const addChild = (myID: string, child: NodeMeta): AddRelationAction => ({
+  myID,
+  type: ADD_CHILD,
+  relaton: child,
+})
+
+export const reduceAddChild = <S extends State>(state: ClassState<S>, action: AddRelationAction): ClassState<S> => {
+  return reduceAddRelation(state, action, Relation.CHILDREN)
+}

package/src/addLink.ts

@@ -0,0 +1,27 @@
+import type { Thunk } from './action'
+import { type AddRelationAction, reduceAddRelation } from './addRelation'
+import { type ClassState, type NodeMeta, Relation, type State } from './stateTypes'
+
+export const addLink = <S extends State>(myID: string, link: NodeMeta, isFromLink = false): Thunk<S> => {
+  return (dispatch, getClassState) => {
+    dispatch(addLinkCore(myID, link))
+
+    if (!isFromLink) {
+      // I connect to the other, would like the other to connect to me as well.
+      // @ts-expect-error XXX doMe is a hidden variable for links.
+      const { doMe, myClass } = getClassState()
+      link.do.addLink(link.id, { id: myID, theClass: myClass, do: doMe }, true)
+    }
+  }
+}
+
+export const ADD_LINK = '@chhsiao1981/use-thunk/ADD_LINK'
+const addLinkCore = (myID: string, link: NodeMeta): AddRelationAction => ({
+  myID,
+  type: ADD_LINK,
+  relaton: link,
+})
+
+export const reduceAddLink = <S extends State>(state: ClassState<S>, action: AddRelationAction): ClassState<S> => {
+  return reduceAddRelation(state, action, Relation.LINKS)
+}

package/src/addRelation.ts

@@ -0,0 +1,32 @@
+import type { BaseAction } from './action'
+import type { ClassState, NodeMeta, Relation, State } from './stateTypes'
+
+export interface AddRelationAction extends BaseAction {
+  relaton: NodeMeta
+}
+
+export const reduceAddRelation = <S extends State>(
+  state: ClassState<S>,
+  action: AddRelationAction,
+  relationName: Relation,
+): ClassState<S> => {
+  const { myID, relaton: relation } = action
+  const me = state.nodes[myID]
+  if (!me) {
+    return state
+  }
+
+  const { theClass, id: theID, do: theDo } = relation
+
+  const relations = me[relationName] ?? {}
+  const relationsByClass = relations[theClass] ?? { list: [] }
+  const relationIDs = relationsByClass.list ?? []
+  const newIDs = theID ? relationIDs.concat([theID]) : relationIDs
+
+  const newRelations = Object.assign({}, me[relationName], { [theClass]: { list: newIDs, do: theDo } })
+  const newMe = Object.assign({}, me, { [relationName]: newRelations })
+  const newNodes = Object.assign({}, state.nodes, { [myID]: newMe })
+  const newState = Object.assign({}, state, { nodes: newNodes })
+
+  return newState
+}

package/src/createReducer.ts

@@ -0,0 +1,24 @@
+import type { BaseAction } from './action'
+import { DEFAULT_REDUCE_MAP, type ReduceMap } from './reduceMap'
+import type { Reducer } from './reducer'
+
+import type { ClassState, State } from './stateTypes'
+
+export const createReducer = <S extends State>(reduceMap?: ReduceMap<S>): Reducer<S> => {
+  return (state: ClassState<S>, action: BaseAction): ClassState<S> => {
+    if (!action) {
+      return state
+    }
+
+    if (reduceMap?.[action.type]) {
+      return reduceMap[action.type](state, action)
+    }
+
+    const defaultReduceMap = DEFAULT_REDUCE_MAP<S>()
+    if (defaultReduceMap?.[action.type]) {
+      return defaultReduceMap[action.type](state, action)
+    }
+
+    return state
+  }
+}

package/src/dispatch.ts

@@ -0,0 +1,6 @@
+import type { Dispatch as rDispatch } from 'react'
+import type { ActionOrThunk } from './action'
+import type { State } from './stateTypes'
+
+// Dispatch
+export type Dispatch<S extends State> = rDispatch<ActionOrThunk<S>>

package/src/dispatchFuncMap.ts

@@ -0,0 +1,22 @@
+import type { State } from './stateTypes'
+import type { ThunkModuleFunc } from './thunk'
+import type { DefaultThunkModuleFuncMap } from './thunkModuleFuncMap'
+
+// biome-ignore lint/suspicious/noExplicitAny: unknown requires same type in list, use any for possible different types.
+type VoidReturnType<T extends (...params: any[]) => unknown> = (...params: Parameters<T>) => void
+
+export type DispatchFuncMap<S extends State, T extends ThunkModuleFunc<S>> = {
+  [action in keyof T]: VoidReturnType<T[action]>
+} & Omit<DefaultDispatchFuncMap, keyof T>
+
+export type DefaultDispatchFuncMap = {
+  [action in keyof DefaultThunkModuleFuncMap]: VoidReturnType<DefaultThunkModuleFuncMap[action]>
+}
+
+export interface DispatchFuncMapByClassMap<S extends State, T extends ThunkModuleFunc<S>> {
+  [className: string]: DispatchFuncMap<S, T>
+}
+
+export interface RefDispatchFuncMapByClassMap<S extends State, T extends ThunkModuleFunc<S>> {
+  current: DispatchFuncMapByClassMap<S, T>
+}