@chhsiao1981/use-thunk 12.0.0 → 13.0.0

package/README.md

@@ -2,43 +2,26 @@
 
 [![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 [`12.0.0`](https://github.com/chhsiao1981/use-thunk/releases/tag/12.0.0): redefining the `getState` functions.
-    1. `getState` => `getStateOrNullByModule`, `mustGetState` => `getStateByModule`.
-    2. `mustGetStateByThunk` => `getState`.
-* Starting from [`11.0.0`](https://github.com/chhsiao1981/use-thunk/releases/tag/11.0.0):
-    1. `setData` => `update`, `registerThunk` => `createThunk`, `dispatch` => `set`, `ClassState` => `ModuleState`, and `ModuleState.myClass` => `ModuleState.name`.
-    2. `Thunk` is `(set, get, getModuleState) => {}`, where `get(id)` directly returns object-level state.
-* Starting from [`10.0.0`](https://github.com/chhsiao1981/use-thunk/releases/tag/10.0.0): The ClassState is shared globally, with `registerThunk` and `ThunkContext`.
-* Starting from [`9.0.0`](https://github.com/chhsiao1981/use-thunk/releases/tag/9.0.0): npm package is renamed as [@chhsiao1981/use-thunk](https://www.npmjs.com/package/%40chhsiao1981/use-thunk)
-* Starting from [`8.0.0`](https://github.com/chhsiao1981/use-thunk/releases/tag/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, update, Thunk, type State as rState, genUUID } from '@chhsiao1981/use-thunk'
+import { type Thunk, type State as rState, update } from '@chhsiao1981/use-thunk'
 
 export const name = 'demo/Increment'
 
@@ -50,51 +33,53 @@ export const defaultState: State = {
   count: 0
 }
 
-export const init = (): Thunk<State> => {
-  const myID = genUUID()
-  return async (set) => {
-    set(_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> => {
+// 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)
-    if(!me) {
-      return
-    }
     const {count} = me
 
-    set(update(myID, { count: count + 1 }))
+    set(update({ count: count + 2 }))
+  }
+}
+
+// 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, getState } from '@chhsiao1981/use-thunk'
-import * as DoIncrement from './reducers/increment'
+import * as DoIncrement from './thunks/increment'
 
-type TDoIncrement = ThunkModuleToFunc(typeof DoIncrement)
+type doIncrement = toDoModule(typeof DoIncrement)
 
-type Props = {
-}
-
-export default (props: Props) => {
-  const useIncrement = useThunk<DoIncrement.State, TDoIncrement>(DoIncrement, StateType.LOCAL)
+export default () => {
+  const useIncrement = useThunk<DoIncrement.State, doIncrement>(DoIncrement)
   const [increment, doIncrement, incrementID] = getState(useIncrement)
 
-  //init
-  useEffect(() => {
-    doIncrement.init()
-  }, [])
-
   // 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,13 +87,13 @@ export default (props: Props) => {
 
 main.tsx:
 ```tsx
-import { createThunk, ThunkContext } from "@chhsiao1981/use-thunk";
+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";
 
-createThunk(DoIncrement)
+registerThunk(DoIncrement)
 
 createRoot(document.getElementById("root")!).render(
   <StrictMode>
@@ -119,6 +104,11 @@ createRoot(document.getElementById("root")!).render(
 )
 ```
 
+## Introduction
+
+
+
+## Development Pattern
 ### Must Included in a Thunk Module
 
 ```ts
@@ -138,29 +128,30 @@ 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, 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 useModule = useThunk<DoModule.State, TDoModule>(DoModule)
+  const useModule = useThunk<DoModule.State, doModule>(DoModule)
   const [module, doModule, moduleID] = getState(useModule)
 
 .
-  .
-  .
+.
+.
 }
 ```
 
-### Must Included in main.tsx
+### Must Included in `main.tsx`
 
 ```tsx
-import { createThunk, ThunkContext } from '@chhsiao1981/use-thunk'
-createThunk(...)
+import { registerThunk, ThunkContext } from '@chhsiao1981/use-thunk'
+import * as DoModule from '../thunks/module'
+registerThunk(DoModule)
 .
 .
 .
@@ -292,47 +283,112 @@ moduleStateUser = {
 
 ## [APIs](https://github.com/chhsiao1981/use-thunk/blob/main/src/index.d.ts)
 
-### Basic
+#### Types
 
-##### `createThunk(theModule: ThunkModule)`
+##### `type Thunk`
 
-Create a module state for `theModule`.
+`Thunk` is defined as:
 
-##### `<ThunkContext>{children}</ThunkContext>`
+```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
+```
 
-Rendering Thunk context.
+We generally use only `set` and `get`.
 
-##### `useThunk(theDo: ThunkModule): UseThunk`
+##### `ThunkModule<S extends State>`
 
-Similar to `React.useReducer`, but we use `useThunk`, and we also bind the actions with set (similar concept as `mapDispatchToProps`).
+```ts
+export type ThunkModule<S extends State> = {
+  name: string
+  defaultState: S
 
-return: `UseThunk`
+  // The rest of the variables are doModule.
+  // Specifying index-signatures to include all the variables.
+  [action: string]: ThunkFunc<S> | string | S
+}
+```
 
-### Default Thunk functions.
+##### `doModule<S extends State>`
 
-##### `init({myID, parentID, doParent, state}, myuuidv4?)`
+```ts
+export interface doModule<S extends State> {
+  [action: string]: ThunkFunc<S>
+}
+```
 
-initializing the state.
+##### `ThunkFunc<S extends State>`
 
-##### `update(myID, data)`
+```ts
+export type ThunkFunc<S extends State> = (...params: any[]) => Thunk<S>
+```
 
-update the data to myID.
+#### RegisterThunk / ThunkContext / useThunk
 
-##### `remove(myID)`
+##### `registerThunk(module: ThunkModule)`
 
-remove the state.
+register a thunk module.
+
+##### `<ThunkContext>{children}</ThunkContext>`
 
-##### `genUUID(myuuidv4?: () => string): string`
+Rendering thunk context.
 
-generate uuid for the state.
+##### `useThunk(theDo: ThunkModule): UseThunk`
+
+Similar to `React.useReducer`, but we use `useThunk`, and we also bind the actions with `set` (similar concept as `mapDispatchToProps`).
+
+return: `UseThunk`
 
-### State
+#### State
 
 ##### `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: `[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>
+```
+
+#### 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`
 
@@ -341,3 +397,10 @@ Get the state of `myID`. Get the state of `defaultID` if `myID` is not present.
 ##### `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.
+
+#### Misc
+
+##### `genID(): string`
+
+generate id for the state.
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chhsiao1981/use-thunk",
-  "version": "12.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,9 +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>,
-  get: (id?: string) => S | null,
+  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 => ({

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

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

package/src/index.ts

@@ -1,42 +1,58 @@
-import type { GetModuleState, Thunk } from './action'
-import createThunk from './createThunk'
-import { genUUID } from './genUUID'
-import type { get } from './get'
-import { type InitParams, init } from './init'
-import { remove } from './remove'
-import type { set } from './set'
-import { setDefaultID } from './setDefaultID'
-import type { setMap } from './setMap'
-import { getDefaultID, getNode, getState, getStateByModule, getStateOrNullByModule } from './states'
-import type { ModuleState, State } from './stateTypes'
-import ThunkContext from './ThunkContext'
-import type { ThunkModule, ThunkModuleToFunc } from './thunkModule'
-import { update } from './update'
+import type { getModuleState, Thunk, ThunkFunc } from './action'
+import { type InitParams, init, remove, setDefaultID, update, upsert } from './defaultThunks'
+import type { dispatch } from './dispatch'
+import type { get, getOrNull } from './get'
+import registerThunk from './registerThunk'
+import type { set, setMap } from './set'
+import {
+  getDefaultID,
+  getNodeOrNull,
+  getState,
+  getStateByModule,
+  getStateOrNullByModule,
+  type ModuleState,
+  type State,
+} from './states'
+import { ThunkContext } from './thunkContext'
+import type { doModule, ThunkModule, toDoModule } from './thunkModule'
 import useThunk, { type UseThunk } from './useThunk'
+import { genID } from './utils'
 
 export {
-  createThunk,
+  // thunk definition.
+  type Thunk,
+  type set,
+  type get,
+  type getOrNull,
+  type dispatch,
+  type getModuleState,
+  // registerThunk / useThunk / ThunkContext
+  registerThunk,
   useThunk,
   type UseThunk,
   ThunkContext,
+  // state related.
   type State,
+  getState,
   type ModuleState,
-  type GetModuleState,
-  type Thunk,
+  // module related.
   type ThunkModule,
-  type ThunkModuleToFunc,
-  type set,
-  type setMap,
-  type get,
-  getNode,
-  getDefaultID,
-  getStateOrNullByModule,
-  getStateByModule,
-  getState,
+  type toDoModule,
+  type doModule,
+  type ThunkFunc,
+  // default thunks.
   init,
   type InitParams,
   update,
+  upsert,
   remove,
+  // genID
+  genID,
+  // advanced usage.
+  type setMap,
   setDefaultID,
-  genUUID,
+  getNodeOrNull,
+  getDefaultID,
+  getStateOrNullByModule,
+  getStateByModule,
 }

package/src/reducer/createReducer.ts

@@ -0,0 +1,18 @@
+import type { BaseAction } from '../action'
+import type { ModuleState, State } from '../states'
+import { DEFAULT_REDUCE_MAP } from './defaultReduceMap'
+import type { Reducer } from './index'
+
+export const createReducer = <S extends State>(): Reducer<S> => {
+  return (moduleState: ModuleState<S>, action: BaseAction): ModuleState<S> => {
+    if (!action) {
+      return moduleState
+    }
+
+    if (DEFAULT_REDUCE_MAP[action.type]) {
+      return DEFAULT_REDUCE_MAP[action.type](moduleState, action)
+    }
+
+    return moduleState
+  }
+}