Merge pull request #127 from heluxjs/doc

Optimize plugin type
heluxjs · Jan 14, 2024 · 28a124b · 28a124b
2 parents c52639e + e6d39fc
commit 28a124b
Show file tree

Hide file tree

Showing 22 changed files with 125 additions and 25 deletions.
diff --git a/docs/docs/guide/plugins.md b/docs/docs/guide/plugins.md
@@ -7,32 +7,58 @@ order: 5
 
 # 插件
 
-插件是一个普通对象，包含有`install`属性，其值对应一个函数，`helux`调用该函数后，会将一个插件上下文对象透传给用户，用户可使用该上下文监听来自`helux`内部的各种行为事件并做对应的处理，例如[helux-plugin-redux-devtoo](https://github.com/heluxjs/helux/tree/master/packages/helux-plugin-redux-devtool)插件接收状态已改变事件，并将其对应的快照写入到 redux 开发工具的状态中，方便用户可视化查看整个应用的状态树。
+插件是一个普通对象，包含有`install`属性，其值对应一个函数，`helux`调用该函数后，会将一个插件上下文对象透传给用户，用户可使用该上下文监听来自`helux`内部的各种行为事件并做对应的处理，例如[helux-plugin-devtool](https://github.com/heluxjs/helux/tree/master/packages/helux-plugin-devtool)插件接收状态已改变事件，并将其对应的快照写入到 redux 开发工具的状态中，方便用户可视化查看整个应用的状态树。
 
 ![](https://tnfe.gtimg.com/image/akpc29z24n_1699705611085.png)
 
 ### 开发插件
 
+基于`cst`变量导出事件名
+
 ```ts
-import { IPlugin } from 'helux';
+import { IPlugin, cst } from 'helux';
 
 const MyPlugin: IPlugin = {
-  install(ctx) {
-    ctx.on(EVENT_NAME.ON_DATA_CHANGED, (dataInfo) => {
+  install(pluginCtx) {
+    pluginCtx.on(cst.EVENT_NAME.ON_DATA_CHANGED, (dataInfo) => {
       // do some staff here
     });
-    ctx.on(EVENT_NAME.ON_SHARE_CREATED, (dataInfo) => {
+    pluginCtx.on(cst.EVENT_NAME.ON_SHARE_CREATED, (dataInfo) => {
       // do some staff here
     });
   },
   name: pluginName,
 };
 ```
 
+基于ts的类型提示感知事件名
+
+```ts
+const MyPlugin: IPlugin = {
+  install(pluginCtx) {
+    // 这里输入 '' 后将自动提示事件名
+    pluginCtx.on('', ()=>{ });
+  },
+  name: 'MyPlugin',
+};
+```
+
+![ev](https://tnfe.gtimg.com/image/cl5rps0ipu_1705203390745.png)
+
 ### 安装插件
 
 ```ts
 import { addPlugin } from 'helux';
 
 addPlugin(MyPlugin);
 ```
+
+### 事件名说明
+
+- ON_SHARE_CREATED，共享状态创建时的事件
+
+- ON_DATA_CHANGED，共享状态变化时的事件
+
+:::info
+若需要其他事件可以提[issue](https://github.com/heluxjs/helux/issues)让`helux-core`内部去实现
+:::
diff --git a/docs/package.json b/docs/package.json
@@ -52,7 +52,7 @@
     "animated-scroll-to": "^2.3.0",
     "classnames": "^2.5.0",
     "console-feed": "^3.5.0",
-    "helux": "4.1.4",
+    "helux": "4.1.5",
     "lodash": "^4.17.21",
     "lodash.throttle": "^4.1.1",
     "prism-react-renderer": "^2.3.1",

diff --git a/examples/react-web/src/addPluginAndMid.ts b/examples/react-web/src/addPluginAndMid.ts
@@ -5,3 +5,10 @@ addPlugin(HeluxPluginDevtool);
 addMiddleware((mid) => {
   // console.log(mid);
 });
+
+// const MyPlugin: IPlugin = {
+//   install(pluginCtx) {
+//     pluginCtx.on('', ()=>{ });
+//   },
+//   name: 'MyPlugin',
+// };
diff --git a/packages/helux-core/CHANGELOG.md b/packages/helux-core/CHANGELOG.md
@@ -1,5 +1,14 @@
 # @helux/core
 
+## 4.1.5
+
+### Patch Changes
+
+- dd2b873: build(4.1.5): optimize PluginCommonOn type
+  - @helux/hooks-impl@4.1.5
+  - @helux/types@4.1.5
+  - @helux/utils@4.1.5
+
 ## 4.1.4
 
 ### Patch Changes

diff --git a/packages/helux-core/package.json b/packages/helux-core/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@helux/core",
-  "version": "4.1.4",
+  "version": "4.1.5",
   "description": "A state library core integrates atom, signal, collection dep, derive and watch, it supports all react like frameworks.",
   "bugs": {
     "url": "https://github.com/heluxjs/helux/issues"

diff --git a/packages/helux-core/src/consts/user.ts b/packages/helux-core/src/consts/user.ts
@@ -1,6 +1,6 @@
 import { VER as limuVer } from 'limu';
 
-export const VER = '4.1.3';
+export const VER = '4.1.5';
 
 export const LIMU_VER = limuVer;
 

diff --git a/packages/helux-core/src/factory/common/plugin.ts b/packages/helux-core/src/factory/common/plugin.ts
@@ -24,15 +24,15 @@ export function emitDataChanged(internal: TInternal, mutateCtx: IMutateCtx) {
   const { bus } = getRootCtx();
   if (bus.canEmit(ON_DATA_CHANGED)) {
     const { from, desc } = mutateCtx;
-    const { sharedKey, moduleName, snap, usefulName, stateType } = internal;
+    const { forAtom, sharedKey, moduleName, snap, usefulName, stateType } = internal;
     let type;
     if (loadingTypes.includes(stateType)) {
       // 来自伴生的 loading 状态调用
       type = `${usefulName}/setState`;
     } else {
       type = `${usefulName}@${from || 'Api'}/${desc}`;
     }
-    bus.emit(ON_DATA_CHANGED, { snap, sharedKey, moduleName, type });
+    bus.emit(ON_DATA_CHANGED, { forAtom, snap, sharedKey, moduleName, usefulName, type });
   }
 }
 
@@ -42,9 +42,9 @@ export function emitDataChanged(internal: TInternal, mutateCtx: IMutateCtx) {
 export function emitShareCreated(internal: TInternal) {
   const { bus } = getRootCtx();
   if (bus.canEmit(ON_SHARE_CREATED)) {
-    const { snap, sharedKey, moduleName, usefulName } = internal;
+    const { forAtom, snap, sharedKey, moduleName, usefulName } = internal;
     const type = `${usefulName}@FactoryApi/createShared`;
-    bus.emit(ON_SHARE_CREATED, { snap, sharedKey, moduleName, type });
+    bus.emit(ON_SHARE_CREATED, { forAtom, snap, sharedKey, moduleName, usefulName, type });
   }
 }
 

diff --git a/packages/helux-core/src/types/api.d.ts b/packages/helux-core/src/types/api.d.ts
@@ -1,6 +1,6 @@
 /*
 |------------------------------------------------------------------------------------------------
-| helux-core@4.1.3
+| helux-core@4.1.5
 | A state library core that integrates atom, signal, collection dep, derive and watch,
 | it supports all react like frameworks ( including react 18 ).
 |------------------------------------------------------------------------------------------------
@@ -68,11 +68,13 @@ import type {
 } from './base';
 
 export declare const cst: {
-  VER: '4.1.3';
+  VER: '4.1.5';
   LIMU_VER: string;
   EVENT_NAME: {
-    ON_DATA_CHANGED: 'ON_DATA_CHANGED';
+    /** 共享状态创建时的事件 */
     ON_SHARE_CREATED: 'ON_SHARE_CREATED';
+    /** 共享状态变化时的事件 */
+    ON_DATA_CHANGED: 'ON_DATA_CHANGED';
   };
   RECORD_LOADING: {
     NO: NoRecord;

diff --git a/packages/helux-core/src/types/base.d.ts b/packages/helux-core/src/types/base.d.ts
@@ -459,7 +459,7 @@ export type DepsResult = { deps?: any[]; result: any };
 export type DepsResultDict = Dict<DepsResult>;
 
 export type MultiDeriveFn<DR extends DepsResultDict = DepsResultDict> = {
-  [K in keyof DR]: DeriveFn<DR[K]['result']> | IDeriveFnItem<DR[K]['result'], DR[K]['deps']>;
+  [K in keyof DR]: DeriveFn<DR[K]['result']> | IDeriveFnItem<DR[K]['result'], Exclude<DR[K]['deps'], undefined>>;
 };
 
 /** partial state or cb */
@@ -1737,8 +1737,17 @@ export interface IDataChangingInfo extends IChangeInfoBase {
   forAtom: boolean;
 }
 
-export interface IDataChangedInfo extends IChangeInfoBase {
+export interface IDataChangedInfo {
+  forAtom: boolean;
+  /** 内部为共享状态生成的唯一key */
+  sharedKey: number;
+  /** 内部计算出的可用名字，若模块名重复则是 sharedKey 字符串，不重复则是 moduleName */
+  usefulName: string;
+  /** 用户创建共享状态时传递的模块名称 */
+  moduleName: string;
+  /** 内部生成的用于表示动作的字符串 */
   type: string;
+  /** 快照 */
   snap: SharedState;
 }
 
@@ -1756,11 +1765,21 @@ export type Middleware = (midCtx: IMiddlewareCtx) => void;
 
 export type PluginStateChangedOnCb = (info: IDataChangedInfo) => void;
 
+export type PluginStateCreatedOnCb = (info: IDataChangedInfo) => void;
+
 export type PluginStateChangedOn = (cb: PluginStateChangedOnCb) => void;
 
 export type PluginCommonOnCb = (data: any) => void;
 
-export type PluginCommonOn = (heluxEventName: string, cb: PluginCommonOnCb) => void;
+// export type PluginCommonOn = (heluxEventName: string, cb: PluginCommonOnCb) => void;
+export interface PluginCommonOn {
+  /** 共享状态创建时的事件 */
+  (heluxEventName: 'ON_DATA_CHANGED', cb: PluginStateChangedOnCb): void;
+  /** 共享状态变化时的事件 */
+  (heluxEventName: 'ON_SHARE_CREATED', cb: PluginStateCreatedOnCb): void;
+  /** 若需要其他事件可以提 issue，然后内部去实现 */
+  (heluxEventName: string, cb: PluginCommonOnCb): void;
+}
 
 export type PluginCtx = { on: PluginCommonOn; onStateChanged: PluginStateChangedOn };
 

diff --git a/packages/helux-demo-utils/package.json b/packages/helux-demo-utils/package.json
@@ -33,7 +33,7 @@
   "dependencies": {
     "@types/react": ">=16.0.0",
     "@types/react-dom": ">=16.0.0",
-    "helux": "^4.1.4",
+    "helux": "^4.1.5",
     "react": ">=16.10.2",
     "react-dom": ">=16.10.2"
   },

diff --git a/packages/helux-hooks-impl/CHANGELOG.md b/packages/helux-hooks-impl/CHANGELOG.md
@@ -1,5 +1,12 @@
 # @helux/hooks-impl
 
+## 4.1.5
+
+### Patch Changes
+
+- @helux/types@4.1.5
+- @helux/utils@4.1.5
+
 ## 4.1.4
 
 ### Patch Changes

diff --git a/packages/helux-hooks-impl/package.json b/packages/helux-hooks-impl/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@helux/hooks-impl",
-  "version": "4.1.4",
+  "version": "4.1.5",
   "description": "helux hooks implement lib",
   "bugs": {
     "url": "https://github.com/heluxjs/helux/issues"

diff --git a/packages/helux-hooks/CHANGELOG.md b/packages/helux-hooks/CHANGELOG.md
@@ -1,5 +1,13 @@
 # @helux/hooks
 
+## 4.1.5
+
+### Patch Changes
+
+- @helux/hooks-impl@4.1.5
+- @helux/types@4.1.5
+- @helux/utils@4.1.5
+
 ## 4.1.4
 
 ### Patch Changes

diff --git a/packages/helux-hooks/package.json b/packages/helux-hooks/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@helux/hooks",
-  "version": "4.1.4",
+  "version": "4.1.5",
   "description": "helux hooks lib for react",
   "keywords": [
     "helux",

diff --git a/packages/helux-openinula/CHANGELOG.md b/packages/helux-openinula/CHANGELOG.md
@@ -1,5 +1,12 @@
 # @helux/openinula
 
+## 4.1.5
+
+### Patch Changes
+
+- Updated dependencies [dd2b873]
+  - @helux/core@4.1.5
+
 ## 4.1.4
 
 ### Patch Changes

diff --git a/packages/helux-openinula/package.json b/packages/helux-openinula/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@helux/openinula",
-  "version": "4.1.4",
+  "version": "4.1.5",
   "description": "State library for preact that integrates atom, signal, collection dep, derive and watch.",
   "bugs": {
     "url": "https://github.com/heluxjs/helux/issues"

diff --git a/packages/helux-types/CHANGELOG.md b/packages/helux-types/CHANGELOG.md
@@ -1,5 +1,7 @@
 # @helux/types
 
+## 4.1.5
+
 ## 4.1.4
 
 ## 4.1.3

diff --git a/packages/helux-types/package.json b/packages/helux-types/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@helux/types",
-  "version": "4.1.4",
+  "version": "4.1.5",
   "description": "helux common types lib",
   "keywords": [
     "helux",

diff --git a/packages/helux-utils/CHANGELOG.md b/packages/helux-utils/CHANGELOG.md
@@ -1,5 +1,11 @@
 # @helux/utils
 
+## 4.1.5
+
+### Patch Changes
+
+- @helux/types@4.1.5
+
 ## 4.1.4
 
 ### Patch Changes

diff --git a/packages/helux-utils/package.json b/packages/helux-utils/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@helux/utils",
-  "version": "4.1.4",
+  "version": "4.1.5",
   "description": "helux utils lib",
   "keywords": [
     "helux",

diff --git a/packages/helux/CHANGELOG.md b/packages/helux/CHANGELOG.md
@@ -1,5 +1,12 @@
 # helux
 
+## 4.1.5
+
+### Patch Changes
+
+- Updated dependencies [dd2b873]
+  - @helux/core@4.1.5
+
 ## 4.1.4
 
 ### Patch Changes

diff --git a/packages/helux/package.json b/packages/helux/package.json
@@ -1,6 +1,6 @@
 {
   "name": "helux",
-  "version": "4.1.4",
+  "version": "4.1.5",
   "description": "Official React bindings for helux-core",
   "bugs": {
     "url": "https://github.com/heluxjs/helux/issues"