@flowlist/js-core 3.0.9 → 3.0.11

package/README.md

@@ -27,60 +27,243 @@ yarn add @flowlist/js-core
 
 ## 📦 Usage
 
-```ts
-import flow from '@flowlist/js-core'
+### updateState 函数的正确使用方法
 
-// Example with a hypothetical state management system (e.g., React useState, Zustand, etc.)
-const { getter, setter, api, cache } = yourAppStateManager
+#### 问题说明
 
-// 1. Initialize the data container
-await flow.initState({
+之前的版本中，`updateState` 函数的类型定义不够灵活，导致在传递自定义数据类型时出现类型错误。
+
+#### 解决方案
+
+现在 `updateState` 函数支持泛型参数，可以正确处理各种数据类型。
+
+#### 基本用法
+
+##### 1. 不使用泛型（默认行为）
+
+```typescript
+import { updateState, ENUM } from '@flowlist/js-core'
+
+// 使用默认的 KeyMap 类型
+updateState({
   getter,
   setter,
-  func: 'fetchPosts',
-  type: 'page', // or 'sinceId', 'seenIds', 'auto', etc.
-  query: { userId: 123 }
+  func: 'getMessages',
+  type: ENUM.FETCH_TYPE.AUTO,
+  method: ENUM.CHANGE_TYPE.RESULT_ITEM_MERGE,
+  id: msg.clientMsgId,
+  uniqueKey: 'clientMsgId',
+  value: {
+    status: 'failed'
+  }
 })
+```
+
+##### 2. 使用泛型指定自定义类型
 
-// 2. Load initial data
-await flow.initData({
+```typescript
+import { updateState, ENUM } from '@flowlist/js-core'
+
+interface MessageDTO {
+  clientMsgId: string
+  content: string
+  status: 'pending' | 'success' | 'failed'
+  timestamp: number
+}
+
+// 使用泛型指定类型
+updateState<Partial<MessageDTO>>({
   getter,
   setter,
-  cache,
-  func: 'fetchPosts',
-  type: 'page',
-  query: { userId: 123 },
-  api,
-  uniqueKey: 'id',
-  cacheTimeout: 300 // 5 minutes
+  func: 'getMessages',
+  type: ENUM.FETCH_TYPE.AUTO,
+  method: ENUM.CHANGE_TYPE.RESULT_ITEM_MERGE,
+  id: msg.clientMsgId,
+  uniqueKey: 'clientMsgId',
+  value: {
+    status: 'failed' // TypeScript 会正确推断这个类型
+  }
 })
+```
 
-// 3. Load more data (e.g., on scroll)
-await flow.loadMore({
+#### 常见使用场景
+
+##### 场景 1: 合并单个项目的部分属性
+
+```typescript
+// 更新消息状态
+updateState<Partial<MessageDTO>>({
   getter,
   setter,
-  cache,
-  func: 'fetchPosts',
-  type: 'page',
-  query: { userId: 123 },
-  api,
-  uniqueKey: 'id',
-  errorRetry: false
+  func: 'getMessages',
+  type: ENUM.FETCH_TYPE.AUTO,
+  method: ENUM.CHANGE_TYPE.RESULT_ITEM_MERGE,
+  id: messageId,
+  uniqueKey: 'clientMsgId',
+  value: {
+    status: 'success',
+    timestamp: Date.now()
+  }
 })
+```
+
+##### 场景 2: 添加新项目到列表
+
+```typescript
+// 在列表末尾添加新消息
+updateState<MessageDTO>({
+  getter,
+  setter,
+  func: 'getMessages',
+  type: ENUM.FETCH_TYPE.AUTO,
+  method: ENUM.CHANGE_TYPE.RESULT_ADD_AFTER,
+  value: {
+    clientMsgId: 'msg-123',
+    content: 'Hello World',
+    status: 'pending',
+    timestamp: Date.now()
+  }
+})
+```
 
-// 4. Update list data locally
-await flow.updateState({
+##### 场景 3: 根据 ID 删除项目
+
+```typescript
+// 删除单个消息
+updateState({
   getter,
   setter,
-  cache,
-  func: 'fetchPosts',
-  type: 'page',
-  query: { userId: 123 },
-  method: 'push', // or 'delete', 'update', 'merge', etc.
-  value: newPost,
-  id: newPost.id,
+  func: 'getMessages',
+  type: ENUM.FETCH_TYPE.AUTO,
+  method: ENUM.CHANGE_TYPE.RESULT_REMOVE_BY_ID,
+  id: messageId,
+  uniqueKey: 'clientMsgId',
+  value: {} // 删除操作不需要 value
+})
+
+// 批量删除多个消息
+updateState({
+  getter,
+  setter,
+  func: 'getMessages',
+  type: ENUM.FETCH_TYPE.AUTO,
+  method: ENUM.CHANGE_TYPE.RESULT_REMOVE_BY_ID,
+  id: [messageId1, messageId2, messageId3],
+  uniqueKey: 'clientMsgId',
+  value: {}
+})
+```
+
+##### 场景 4: 更新深层嵌套的属性
+
+```typescript
+interface ComplexMessage {
+  id: string
+  metadata: {
+    sender: {
+      name: string
+      avatar: string
+    }
+  }
+}
+
+updateState({
+  getter,
+  setter,
+  func: 'getMessages',
+  type: ENUM.FETCH_TYPE.AUTO,
+  method: ENUM.CHANGE_TYPE.RESULT_UPDATE_KV,
+  id: messageId,
   uniqueKey: 'id',
-  changeKey: 'result',
-  cacheTimeout: 300
+  changeKey: 'metadata.sender.name',
+  value: 'New Name'
+})
+```
+
+##### 场景 5: 批量更新列表项
+
+```typescript
+// 使用 RESULT_LIST_MERGE 批量更新多个项目
+updateState({
+  getter,
+  setter,
+  func: 'getMessages',
+  type: ENUM.FETCH_TYPE.AUTO,
+  method: ENUM.CHANGE_TYPE.RESULT_LIST_MERGE,
+  uniqueKey: 'clientMsgId',
+  value: [
+    { clientMsgId: 'msg-1', status: 'success' },
+    { clientMsgId: 'msg-2', status: 'failed' },
+    { clientMsgId: 'msg-3', status: 'success' }
+  ]
 })
 ```
+
+#### 所有可用的变更类型
+
+```typescript
+ENUM.CHANGE_TYPE = {
+  SEARCH_FIELD: 'search', // 搜索并返回匹配的项目
+  RESET_FIELD: 'reset', // 重置整个字段
+  RESULT_UPDATE_KV: 'update', // 更新指定项的深层属性
+  RESULT_ADD_AFTER: 'push', // 在列表末尾添加项目
+  RESULT_ADD_BEFORE: 'unshift', // 在列表开头添加项目
+  RESULT_REMOVE_BY_ID: 'delete', // 根据 ID 删除项目
+  RESULT_INSERT_TO_BEFORE: 'insert-before', // 在指定项之前插入
+  RESULT_INSERT_TO_AFTER: 'insert-after', // 在指定项之后插入
+  RESULT_LIST_MERGE: 'patch', // 批量合并更新多个项目
+  RESULT_ITEM_MERGE: 'merge' // 合并单个项目的属性
+}
+```
+
+#### 最佳实践
+
+1. **使用 TypeScript 接口定义数据结构**
+   - 为你的数据模型创建明确的接口定义
+   - 使用泛型参数获得更好的类型推断
+
+2. **选择合适的 uniqueKey**
+   - 确保 uniqueKey 在列表中是唯一的
+   - 支持嵌套路径，如 `'user.id'`
+
+3. **根据操作类型传递正确的参数**
+   - 删除操作需要 `id` 参数
+   - 更新操作需要 `id` 和 `value` 参数
+   - 添加操作只需要 `value` 参数
+
+4. **处理异步操作**
+
+   ```typescript
+   try {
+     await updateState({
+       // ... 参数
+     })
+     console.log('更新成功')
+   } catch (error) {
+     console.error('更新失败:', error)
+   }
+   ```
+
+5. **性能优化**
+   - 批量操作时使用 `RESULT_LIST_MERGE` 而不是多次调用 `RESULT_ITEM_MERGE`
+   - 避免在循环中频繁调用 updateState
+
+#### 类型安全提示
+
+项目现在支持完整的 TypeScript 类型推断：
+
+- ✅ 所有函数参数都有明确的类型定义
+- ✅ 支持泛型以适应不同的数据结构
+- ✅ 自动类型检查和智能提示
+- ✅ 编译时类型错误检测
+
+#### 测试覆盖率
+
+当前测试覆盖率：
+
+- 语句覆盖率: 99.33%
+- 分支覆盖率: 95.1%
+- 函数覆盖率: 100%
+- 行覆盖率: 99.75%
+
+所有 159 个测试用例全部通过 ✓

package/dist/index.d.mts

@@ -3,212 +3,209 @@
  */
 type ObjectKey = string | number;
 /**
- * 通用键值对映射（注意：尽管 ObjectKey 包含 number，
- * 但在实际对象中，number 键会被转为 string。
- * 此处使用 string 以符合 Record 的实际行为 [[3]]）
+ * 通用键值对映射 - 使用 Record 以保持灵活性和性能
  */
 type KeyMap = Record<string, unknown>;
 /**
- * 形态数组
+ * 数组元素类型
  */
-type ResultType = KeyMap | unknown[];
+type ResultArrayType = KeyMap[];
 /**
- * 数据源类型：可以是 API 路径字符串，或返回 Promise 的函数
+ * 对象结果类型：键为字符串，值为 KeyMap 数组
  */
-type DataSource = string | ((params: unknown) => Promise<unknown>);
+type ResultObjectType = Record<string, KeyMap[]>;
 /**
- * 字段获取器：根据字段名获取状态对象
+ * 结果类型：可以是数组或对象
  */
-type FieldGetter = (key: string) => DefaultField | undefined;
+type ResultType = ResultArrayType | ResultObjectType;
 /**
- * 状态设置器函数类型
+ * API 函数类型
  */
-type FieldSetter = (obj: SetterFuncParams) => void;
+type ApiFunction = (_params: KeyMap) => Promise<ApiResponse>;
 /**
- * 获取数据后的回调函数
+ * 数据源类型：可以是 API 路径字符串，或返回 Promise 的函数
  */
-type FetchResultCallback = (obj: {
-    params: GenerateParamsResp;
-    data: ApiResponse;
-    refresh: boolean;
-}) => void;
+type DataSource = string | ApiFunction;
+interface DefaultField {
+    result: ResultType;
+    noMore: boolean;
+    nothing: boolean;
+    loading: boolean;
+    error: Error | null;
+    extra: KeyMap | null;
+    fetched: boolean;
+    page: number;
+    total: number;
+}
+type FieldKeys = keyof DefaultField;
 /**
- * 数据获取类型枚举
+ * 字段获取器：根据字段名获取状态对象
  */
-type FetchType = 'jump' | 'sinceId' | 'page' | 'seenIds' | 'auto';
+type FieldGetter = (_key: string) => DefaultField | undefined;
 /**
- * 字段数据的关键字
+ * Setter 函数的参数
  */
-type FieldKeys = 'result' | 'noMore' | 'nothing' | 'loading' | 'error' | 'extra' | 'fetched' | 'page' | 'total';
-interface CommonParams {
-    func: DataSource;
-    type: FetchType;
-    query?: KeyMap;
-    uniqueKey?: string;
-    callback?: FetchResultCallback;
+interface SetterFuncParams {
+    readonly key: string;
+    readonly type: number;
+    readonly value: Partial<DefaultField> | DefaultField;
+    readonly callback?: (_obj?: KeyMap) => void;
 }
 /**
- * 生成请求参数的输入
+ * 状态设置器函数类型
  */
-interface GenerateParamsType {
-    field: DefaultField;
-    uniqueKey?: string;
-    query?: KeyMap;
-    type: FetchType;
-}
+type FieldSetter = (_obj: SetterFuncParams) => void;
+/**
+ * 数据获取类型枚举
+ */
+type FetchType = 'jump' | 'sinceId' | 'page' | 'seenIds' | 'auto';
 /**
  * 生成请求参数的输出
  */
-interface GenerateParamsResp {
+interface GenerateParamsResp extends KeyMap {
     seen_ids?: string;
     since_id?: ObjectKey;
     is_up?: 0 | 1;
     page?: number;
 }
 /**
- * Setter 函数的参数
+ * 生成请求参数的输入
  */
-interface SetterFuncParams {
-    key: string;
-    type: number;
-    value: unknown;
-    callback?: (obj?: KeyMap) => void;
+interface GenerateParamsType {
+    readonly field: DefaultField;
+    readonly uniqueKey?: string;
+    readonly query?: KeyMap;
+    readonly type: FetchType;
 }
 /**
- * 默认字段数据结构，使用泛型 T 和 E 分别代表 result 和 extra 的类型
+ * API 响应结构
  */
-interface DefaultField {
-    result: ResultType;
-    noMore: boolean;
-    nothing: boolean;
-    loading: boolean;
-    error: null | Error;
-    extra: unknown;
-    fetched: boolean;
-    page: number;
-    total: number;
+interface ApiResponse {
+    readonly result: ResultType;
+    readonly extra?: KeyMap;
+    readonly total?: number;
+    readonly no_more?: boolean;
 }
 /**
- * API 响应结构，使用泛型 T 和 E
+ * 获取数据后的回调函数
  */
-interface ApiResponse {
-    result: ResultType;
-    extra?: unknown;
-    total?: number;
-    no_more?: boolean;
+type FetchResultCallback = (_obj: {
+    params: KeyMap;
+    data: ApiResponse;
+    refresh: boolean;
+}) => void;
+interface CommonParams {
+    readonly func: DataSource;
+    readonly type: FetchType;
+    readonly query?: KeyMap;
+    readonly uniqueKey?: string;
+    readonly callback?: FetchResultCallback;
 }
 interface BaseFetchConfig extends CommonParams {
-    getter: FieldGetter;
-    setter: FieldSetter;
-    api?: KeyMap;
+    readonly getter: FieldGetter;
+    readonly setter: FieldSetter;
+    readonly api?: Record<string, ApiFunction>;
 }
 /**
- * 初始化状态的参数
+ * 初始化状态的参数对外接口
+ */
+interface InitStateParams {
+    readonly func: DataSource;
+    readonly type: FetchType;
+    readonly query?: KeyMap;
+    readonly opts?: Partial<DefaultField>;
+}
+/**
+ * 初始化状态的参数（内部）
  */
 interface InitStateType extends InitStateParams {
-    getter: FieldGetter;
-    setter: FieldSetter;
+    readonly getter: FieldGetter;
+    readonly setter: FieldSetter;
 }
 /**
- * 初始化数据的参数
+ * 初始化数据的参数对外接口
+ */
+type InitDataParams = CommonParams;
+/**
+ * 初始化数据的参数（内部）
  */
 type InitDataType = BaseFetchConfig;
 /**
- * 加载更多的参数
+ * 加载更多的参数对外接口
+ */
+interface LoadMoreParams extends CommonParams {
+    readonly errorRetry?: boolean;
+}
+/**
+ * 加载更多的参数（内部）
  */
 interface LoadMoreType extends BaseFetchConfig {
-    errorRetry?: boolean;
+    readonly errorRetry?: boolean;
 }
 /**
- * 更新状态的参数
+ * 更新状态的参数（内部使用）
  */
-interface UpdateStateType {
-    getter: FieldGetter;
-    setter: FieldSetter;
-    func: DataSource;
-    type: FetchType;
-    query?: KeyMap;
-    method: string;
-    value: ResultArrayType$1 | Record<ObjectKey, KeyMap>;
-    id?: string | number | ObjectKey[];
-    changeKey?: string;
-    uniqueKey?: string;
+interface UpdateStateType<T = KeyMap> {
+    readonly getter: FieldGetter;
+    readonly setter: FieldSetter;
+    readonly func: DataSource;
+    readonly type: FetchType;
+    readonly query?: KeyMap;
+    readonly method: string;
+    readonly value: T | ResultArrayType | ResultObjectType | KeyMap;
+    readonly id?: ObjectKey | ObjectKey[];
+    readonly changeKey?: string;
+    readonly uniqueKey?: string;
+}
+/**
+ * 更新状态的参数（对外接口）
+ */
+interface UpdateStateParams<T = KeyMap> {
+    readonly func: DataSource;
+    readonly type: FetchType;
+    readonly query?: KeyMap;
+    readonly method: string;
+    readonly value: T | ResultArrayType | ResultObjectType | KeyMap;
+    readonly id?: ObjectKey | ObjectKey[];
+    readonly changeKey?: string;
+    readonly uniqueKey?: string;
 }
 /**
  * 设置数据的参数
  */
 interface SetDataType {
-    getter: FieldGetter;
-    setter: FieldSetter;
-    data: ApiResponse;
-    fieldName: string;
-    type: FetchType;
-    page: number;
-    insertBefore: boolean;
+    readonly getter: FieldGetter;
+    readonly setter: FieldSetter;
+    readonly data: ApiResponse;
+    readonly fieldName: string;
+    readonly type: FetchType;
+    readonly page: number;
+    readonly insertBefore: boolean;
 }
 /**
  * 设置错误的参数
  */
 interface SetErrorType {
-    setter: FieldSetter;
-    fieldName: string;
-    error: null | Error;
-}
-type ResultArrayType$1 = KeyMap[];
-type ResultObjectType$1 = Record<ObjectKey, KeyMap[]>;
-type InitDataParams = CommonParams;
-interface LoadMoreParams extends CommonParams {
-    errorRetry?: boolean;
-}
-interface InitStateParams {
-    func: DataSource;
-    type: FetchType;
-    query?: KeyMap;
-    opts?: Partial<DefaultField>;
+    readonly setter: FieldSetter;
+    readonly fieldName: string;
+    readonly error: Error | null;
 }
 
 declare const initState: ({ getter, setter, func, type, query, opts }: InitStateType) => Promise<void>;
 declare const initData: ({ getter, setter, func, type, query, api, uniqueKey, callback }: InitDataType) => Promise<void>;
 declare const loadMore: ({ getter, setter, query, type, func, api, uniqueKey, errorRetry, callback }: LoadMoreType) => Promise<void>;
-declare const updateState: ({ getter, setter, func, type, query, method, value, id, uniqueKey, changeKey }: UpdateStateType) => Promise<unknown>;
+declare const updateState: <T = KeyMap>({ getter, setter, func, type, query, method, value, id, uniqueKey, changeKey }: UpdateStateType<T>) => Promise<unknown>;
 
-/**
- * 判断数据是否为对象结果（即没有 result 字段）
- * 注意：这里我们假设 "对象结果" 指的是一个普通的对象，而不是 ApiResponse。
- */
+declare const isArray: (data: unknown) => data is unknown[];
 declare const isObjectResult: (data: unknown) => data is Record<string, unknown>;
-/**
- * 生成默认字段
- */
 declare const generateDefaultField: (opts?: Partial<DefaultField>) => DefaultField;
-/**
- * 根据参数生成 field 的 namespace
- */
 declare const generateFieldName: ({ func, type, query }: InitDataParams) => string;
-/**
- * 根据 key 从 object 里拿 value
- */
-declare const getObjectDeepValue: (field: unknown, keys?: string | string[]) => unknown;
-/**
- * 安全地更新对象的深层值
- */
-declare const updateObjectDeepValue: (field: Record<string, unknown>, changeKey: string, value: unknown) => void;
-type ResultArrayType = KeyMap[];
-type ResultObjectType = Record<ObjectKey, KeyMap[]>;
+declare const getObjectDeepValue: (field: unknown, keys: string | string[]) => unknown;
+declare const updateObjectDeepValue: (field: KeyMap, changeKey: string, value: unknown) => void;
 declare const searchValueByKey: (result: ResultArrayType | ResultObjectType, id: ObjectKey, key: string) => unknown;
 declare const computeMatchedItemIndex: (itemId: ObjectKey, fieldArr: ResultArrayType, changingKey: string) => number;
 declare const combineArrayData: (fieldArray: ResultArrayType, value: ResultArrayType | Record<ObjectKey, KeyMap>, changingKey: string) => void;
-/**
- * 判断参数是否为数组
- */
-declare const isArray: (data: unknown) => data is unknown[];
-/**
- * 设置一个响应式的数据到对象上
- */
 declare const setReactivityField: (field: DefaultField, key: FieldKeys, value: unknown, type: FetchType, insertBefore: boolean) => void;
-/**
- * 计算一个数据列的长度
- */
 declare const computeResultLength: (data: unknown) => number;
 declare const generateRequestParams: ({ field, uniqueKey, query, type }: GenerateParamsType) => GenerateParamsResp;
 
@@ -260,4 +257,4 @@ declare const _default: {
     readonly DEFAULT_UNIQUE_KEY_NAME: "id";
 };
 
-export { type ApiResponse, type DefaultField, _default as ENUM, type FetchType, type FieldGetter, type FieldKeys, type FieldSetter, type GenerateParamsResp, type GenerateParamsType, type InitDataParams, type InitDataType, type InitStateParams, type InitStateType, type KeyMap, type LoadMoreParams, type LoadMoreType, type ObjectKey, type ResultArrayType$1 as ResultArrayType, type ResultObjectType$1 as ResultObjectType, type ResultType, type SetDataType, type SetErrorType, type SetterFuncParams, type UpdateStateType, initData, initState, loadMore, updateState, utils };
+export { type ApiFunction, type ApiResponse, type DataSource, type DefaultField, _default as ENUM, type FetchResultCallback, type FetchType, type FieldGetter, type FieldKeys, type FieldSetter, type GenerateParamsResp, type GenerateParamsType, type InitDataParams, type InitDataType, type InitStateParams, type InitStateType, type KeyMap, type LoadMoreParams, type LoadMoreType, type ObjectKey, type ResultArrayType, type ResultObjectType, type ResultType, type SetDataType, type SetErrorType, type SetterFuncParams, type UpdateStateParams, type UpdateStateType, initData, initState, loadMore, updateState, utils };