@flowlist/js-core 4.0.3-beta.0 → 4.0.5-beta.0

package/dist/index.d.mts

@@ -3,77 +3,84 @@
  */
 type ObjectKey = string | number;
 /**
- * 通用键值对映射 - 使用 Record 以保持灵活性和性能
- * 通过索引签名支持动态属性访问
+ * 通用对象结构 (仅用于内部弱类型处理，对外尽量使用泛型)
  */
-type KeyMap = Record<string, unknown>;
+type KeyMap = Record<string, any>;
 /**
- * 数组元素类型
+ * 所有的 API 响应都应该遵循这个基础结构
  */
-type ResultArrayType = KeyMap[];
-/**
- * 对象结果类型：键为字符串，值为 KeyMap 数组
- */
-type ResultObjectType = Record<string, KeyMap[]>;
-/**
- * 结果类型：可以是数组或对象
- */
-type ResultType = ResultArrayType | ResultObjectType;
-/**
- * API 函数类型
- */
-type ApiFunction = (_params: KeyMap) => Promise<ApiResponse>;
+interface BaseApiResponse<TData = any> {
+    readonly result: TData;
+    readonly extra?: any;
+    readonly total?: number;
+    readonly no_more?: boolean;
+}
 /**
- * 数据源类型：可以是 API 路径字符串，或返回 Promise 的函数
+ * 核心状态字段
+ * @template TData 具体的 result 数据类型 (e.g. User[] or Record<string, User[]>)
+ * @template TExtra extra 字段的类型
  */
-type DataSource = string | ApiFunction;
-interface DefaultField {
-    result: ResultType;
+interface DefaultField<TData = any, TExtra = any> {
+    result: TData;
     noMore: boolean;
     nothing: boolean;
     loading: boolean;
     error: Error | null;
-    extra: KeyMap | null;
+    extra: TExtra | null;
     fetched: boolean;
     page: number;
     total: number;
 }
 type FieldKeys = keyof DefaultField;
 /**
- * 字段获取器：根据字段名获取状态对象
+ * 请求参数的基础约束
  */
-type FieldGetter = (_key: string) => DefaultField | undefined;
+interface RequestParams {
+    [key: string]: any;
+    __refresh__?: boolean;
+    __reload__?: boolean;
+    is_up?: 0 | 1 | boolean;
+    page?: number;
+    sinceId?: ObjectKey;
+}
 /**
- * Setter 函数的参数
- */
-interface SetterFuncParams {
-    readonly key: string;
-    readonly type: number;
-    readonly value: Partial<DefaultField> | DefaultField;
-    readonly callback?: (_obj?: KeyMap) => void;
+ * API 契约：核心类型
+ * @template TParams 请求参数类型
+ * @template TResponse 响应的 result 数据类型
+ */
+interface ApiContract<TParams extends RequestParams, TResponse> {
+    /**
+     * 调用函数
+     */
+    (params: TParams): Promise<BaseApiResponse<TResponse>>;
+    /**
+     * 静态属性
+     */
+    readonly id: string;
+    readonly type: FetchType;
+    readonly uniqueKey: string;
+    readonly paramsIgnore: string[];
 }
 /**
- * 状态设置器函数类型
+ * 数据获取策略类型
  */
-type FieldSetter = (_obj: SetterFuncParams) => void;
+type FetchType = 'jump' | 'sinceId' | 'page' | 'seenIds' | 'auto';
 /**
- * 数据获取类型枚举
+ * 字段获取器
  */
-type FetchType = 'jump' | 'sinceId' | 'page' | 'seenIds' | 'auto';
+type FieldGetter = (key: string) => DefaultField | undefined;
 /**
- * 请求参数的基础约束
+ * 字段设置器参数
  */
-interface RequestParams {
-    [key: string]: unknown;
-    __refresh__?: boolean;
-    __reload__?: boolean;
-    is_up?: 0 | 1 | boolean;
-    page?: number;
-    sinceId?: ObjectKey;
+interface SetterFuncParams {
+    readonly key: string;
+    readonly type: number;
+    readonly value: Partial<DefaultField> | DefaultField;
+    readonly callback?: (obj?: any) => void;
 }
+type FieldSetter = (obj: SetterFuncParams) => void;
 /**
- * 生成请求参数的输出
- * 继承自 RequestParams 以确保与 ApiContract 参数兼容
+ * 生成请求参数的返回值
  */
 interface GenerateParamsResp extends RequestParams {
     seen_ids?: string;
@@ -91,146 +98,91 @@ interface GenerateParamsType {
     readonly type: FetchType;
 }
 /**
- * API 响应结构
+ * 回调函数类型
  */
-interface ApiResponse<R = ResultType> {
-    readonly result: R;
-    readonly extra?: KeyMap;
-    readonly total?: number;
-    readonly no_more?: boolean;
-}
-/**
- * 获取数据后的回调函数
- */
-type FetchResultCallback<P, R> = (_obj: {
-    params: P;
-    data: ApiResponse<R>;
+type FetchResultCallback<TParams, TResponse> = (obj: {
+    params: TParams;
+    data: BaseApiResponse<TResponse>;
     refresh: boolean;
 }) => void;
-interface CommonParams<P = RequestParams, R = ResultType> {
-    readonly func: ApiContract<P, R>;
-    readonly type?: FetchType;
-    readonly query?: P;
-    readonly uniqueKey?: string;
-    readonly callback?: FetchResultCallback<P, R>;
-}
-interface BaseFetchConfig<P = RequestParams, R = ResultType> extends CommonParams<P, R> {
-    readonly getter: FieldGetter;
-    readonly setter: FieldSetter;
-}
-/**
- * 初始化状态的参数对外接口
- */
-interface InitStateParams<P = RequestParams, R = ResultType> {
-    readonly func: ApiContract<P, R>;
-    readonly query?: P;
-    readonly opts?: Partial<DefaultField>;
-}
 /**
- * 初始化状态的参数（内部）
+ * 通用 Action 参数约束
  */
-interface InitStateType<P = RequestParams, R = ResultType> extends InitStateParams<P, R> {
-    readonly getter: FieldGetter;
-    readonly setter: FieldSetter;
+interface ActionParams<TParams extends RequestParams, TResponse> {
+    getter: FieldGetter;
+    setter: FieldSetter;
+    func: ApiContract<TParams, TResponse>;
+    query?: TParams;
 }
 /**
- * 初始化数据的参数对外接口
- */
-type InitDataParams<P = RequestParams, R = ResultType> = CommonParams<P, R>;
-/**
- * 初始化数据的参数（内部）
+ * initData 参数
  */
-type InitDataType<P = RequestParams, R = ResultType> = BaseFetchConfig<P, R>;
-/**
- * 加载更多的参数对外接口
- */
-interface LoadMoreParams<P = RequestParams, R = ResultType> extends CommonParams<P, R> {
-    readonly errorRetry?: boolean;
+interface InitDataType<TParams extends RequestParams, TResponse> extends ActionParams<TParams, TResponse> {
+    callback?: FetchResultCallback<TParams, TResponse>;
 }
 /**
- * 加载更多的参数（内部）
+ * initState 参数
  */
-interface LoadMoreType<P = RequestParams, R = ResultType> extends BaseFetchConfig<P, R> {
-    readonly errorRetry?: boolean;
+interface InitStateType<TParams extends RequestParams, TResponse> extends ActionParams<TParams, TResponse> {
+    opts?: Partial<DefaultField<TResponse>>;
 }
 /**
- * 更新状态的参数（内部使用）
+ * loadMore 参数
  */
-interface UpdateStateType<P = RequestParams, R = ResultType, T = KeyMap> {
-    readonly getter: FieldGetter;
-    readonly setter: FieldSetter;
-    readonly func: ApiContract<P, R>;
-    readonly query?: P;
-    readonly method: string;
-    readonly value: T | T[] | KeyMap | KeyMap[];
-    readonly id?: ObjectKey | ObjectKey[];
-    readonly changeKey?: string;
+interface LoadMoreType<TParams extends RequestParams, TResponse> extends ActionParams<TParams, TResponse> {
+    errorRetry?: boolean;
+    callback?: FetchResultCallback<TParams, TResponse>;
 }
 /**
- * 更新状态的参数（对外接口）
- */
-interface UpdateStateParams<P = RequestParams, R = ResultType, T = KeyMap> {
-    readonly func: ApiContract<P, R>;
-    readonly type: FetchType;
-    readonly query?: P;
-    readonly method: string;
-    readonly value: T | T[] | KeyMap | KeyMap[];
-    readonly id?: ObjectKey | ObjectKey[];
-    readonly changeKey?: string;
-    readonly uniqueKey?: string;
+ * updateState 参数
+ * 这里的 TValue 尝试对更新的值进行约束
+ */
+interface UpdateStateType<TParams extends RequestParams, TResponse> {
+    getter: FieldGetter;
+    setter: FieldSetter;
+    func: ApiContract<TParams, TResponse>;
+    query?: TParams;
+    method: string;
+    value: any;
+    id?: ObjectKey | ObjectKey[];
+    changeKey?: string;
 }
-/**
- * 设置数据的参数
- */
 interface SetDataType {
     readonly getter: FieldGetter;
     readonly setter: FieldSetter;
-    readonly data: ApiResponse;
+    readonly data: BaseApiResponse;
     readonly fieldName: string;
     readonly type: FetchType;
     readonly page: number;
     readonly insertBefore: boolean;
 }
-/**
- * 设置错误的参数
- */
 interface SetErrorType {
     readonly setter: FieldSetter;
     readonly fieldName: string;
     readonly error: Error | null;
 }
-interface ApiContract<P = RequestParams, R = ResultType> {
-    (params: P): Promise<ApiResponse<R>>;
-    readonly id: string;
-    readonly type: FetchType;
-    readonly uniqueKey: string;
-    readonly paramsIgnore: string[];
-}
-declare function createApi<P = RequestParams, R = ResultType>(options: {
+
+declare const initState: <P extends RequestParams, R>({ getter, setter, func, query, opts }: InitStateType<P, R>) => Promise<void>;
+declare const initData: <P extends RequestParams, R>({ getter, setter, func, query, callback }: InitDataType<P, R>) => Promise<void>;
+declare const loadMore: <P extends RequestParams, R>({ getter, setter, query, func, errorRetry, callback }: LoadMoreType<P, R>) => Promise<void>;
+declare const updateState: <P extends RequestParams, R>({ getter, setter, func, query, method, id, value, changeKey }: UpdateStateType<P, R>) => Promise<unknown>;
+declare const createApi: <TParams extends RequestParams, TResponse>(options: {
     id: string;
     type?: FetchType;
     uniqueKey?: string;
     paramsIgnore?: string[];
-    fetcher: (params: P) => Promise<ApiResponse<R>>;
-}): ApiContract<P, R>;
-
-declare const initState: <P = RequestParams, R = ResultType>({ getter, setter, func, query, opts }: InitStateType<P, R>) => Promise<void>;
-declare const initData: <P = RequestParams, R = ResultType>({ getter, setter, func, query, callback }: InitDataType<P, R>) => Promise<void>;
-/**
- * 加载更多数据
- */
-declare const loadMore: <P = RequestParams, R = ResultType>({ getter, setter, query, func, errorRetry, callback }: LoadMoreType<P, R>) => Promise<void>;
-declare const updateState: <P = RequestParams, R = ResultType, T = KeyMap>({ getter, setter, func, query, method, id, value, changeKey }: UpdateStateType<P, R, T>) => Promise<unknown>;
+    fetcher: (params: TParams) => Promise<BaseApiResponse<TResponse>>;
+}) => ApiContract<TParams, TResponse>;
+declare const generateFieldName$1: <P extends RequestParams, R>({ func, query }: {
+    func: ApiContract<P, R>;
+    query?: P;
+}) => string;
 
-declare const isArray: (data: unknown) => data is unknown[];
-/**
- * 检查是否为数组
- */
-declare const isResultArray: (data: ResultType) => data is ResultArrayType;
+declare const isArray: (data: unknown) => data is any[];
 /**
  * 检查是否为对象结果
  */
-declare const isResultObject: (data: ResultType) => data is ResultObjectType;
+declare const isResultObject: (data: unknown) => data is Record<string, any>;
 /**
  * 检查是否为 ObjectKey
  */
@@ -247,20 +199,24 @@ declare const isKeyMapArray: (value: unknown) => value is KeyMap[];
  * 检查是否为 ObjectKey 数组
  */
 declare const isObjectKeyArray: (value: unknown) => value is ObjectKey[];
+declare const stableSerialize: (value: unknown) => string;
 declare const isObjectResult: (data: unknown) => data is Record<string, unknown>;
-declare const generateDefaultField: (opts?: Partial<DefaultField>) => DefaultField;
-declare const generateFieldName: <P = RequestParams, R = ResultType>({ func, query }: {
+declare const generateDefaultField: <T = any>(opts?: Partial<DefaultField<T>>) => DefaultField<T>;
+declare const generateFieldName: <P extends RequestParams, R>({ func, query }: {
     func: ApiContract<P, R>;
     query?: P;
 }) => string;
 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 searchValueByKey: (result: any[] | Record<string, any>, id: ObjectKey, key: string) => unknown;
+declare const computeMatchedItemIndex: (itemId: ObjectKey, fieldArr: any[], changingKey: string) => number;
+declare const combineArrayData: (fieldArray: any[], value: any[] | Record<ObjectKey, KeyMap>, changingKey: string) => void;
 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;
+declare const toObjectKey: (id: ObjectKey | ObjectKey[] | undefined) => ObjectKey | undefined;
+declare const getResultAsArray: (field: DefaultField) => any[] | null;
+declare const updateArrayItem: (arr: any[], index: number, updater: (item: KeyMap) => KeyMap) => void;
 
 declare const utils_combineArrayData: typeof combineArrayData;
 declare const utils_computeMatchedItemIndex: typeof computeMatchedItemIndex;
@@ -269,19 +225,22 @@ declare const utils_generateDefaultField: typeof generateDefaultField;
 declare const utils_generateFieldName: typeof generateFieldName;
 declare const utils_generateRequestParams: typeof generateRequestParams;
 declare const utils_getObjectDeepValue: typeof getObjectDeepValue;
+declare const utils_getResultAsArray: typeof getResultAsArray;
 declare const utils_isArray: typeof isArray;
 declare const utils_isKeyMap: typeof isKeyMap;
 declare const utils_isKeyMapArray: typeof isKeyMapArray;
 declare const utils_isObjectKey: typeof isObjectKey;
 declare const utils_isObjectKeyArray: typeof isObjectKeyArray;
 declare const utils_isObjectResult: typeof isObjectResult;
-declare const utils_isResultArray: typeof isResultArray;
 declare const utils_isResultObject: typeof isResultObject;
 declare const utils_searchValueByKey: typeof searchValueByKey;
 declare const utils_setReactivityField: typeof setReactivityField;
+declare const utils_stableSerialize: typeof stableSerialize;
+declare const utils_toObjectKey: typeof toObjectKey;
+declare const utils_updateArrayItem: typeof updateArrayItem;
 declare const utils_updateObjectDeepValue: typeof updateObjectDeepValue;
 declare namespace utils {
-  export { utils_combineArrayData as combineArrayData, utils_computeMatchedItemIndex as computeMatchedItemIndex, utils_computeResultLength as computeResultLength, utils_generateDefaultField as generateDefaultField, utils_generateFieldName as generateFieldName, utils_generateRequestParams as generateRequestParams, utils_getObjectDeepValue as getObjectDeepValue, utils_isArray as isArray, utils_isKeyMap as isKeyMap, utils_isKeyMapArray as isKeyMapArray, utils_isObjectKey as isObjectKey, utils_isObjectKeyArray as isObjectKeyArray, utils_isObjectResult as isObjectResult, utils_isResultArray as isResultArray, utils_isResultObject as isResultObject, utils_searchValueByKey as searchValueByKey, utils_setReactivityField as setReactivityField, utils_updateObjectDeepValue as updateObjectDeepValue };
+  export { utils_combineArrayData as combineArrayData, utils_computeMatchedItemIndex as computeMatchedItemIndex, utils_computeResultLength as computeResultLength, utils_generateDefaultField as generateDefaultField, utils_generateFieldName as generateFieldName, utils_generateRequestParams as generateRequestParams, utils_getObjectDeepValue as getObjectDeepValue, utils_getResultAsArray as getResultAsArray, utils_isArray as isArray, utils_isKeyMap as isKeyMap, utils_isKeyMapArray as isKeyMapArray, utils_isObjectKey as isObjectKey, utils_isObjectKeyArray as isObjectKeyArray, utils_isObjectResult as isObjectResult, utils_isResultObject as isResultObject, utils_searchValueByKey as searchValueByKey, utils_setReactivityField as setReactivityField, utils_stableSerialize as stableSerialize, utils_toObjectKey as toObjectKey, utils_updateArrayItem as updateArrayItem, utils_updateObjectDeepValue as updateObjectDeepValue };
 }
 
 declare const _default: {
@@ -316,4 +275,4 @@ declare const _default: {
     readonly DEFAULT_UNIQUE_KEY_NAME: "id";
 };
 
-export { type ApiContract, 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 RequestParams, type ResultArrayType, type ResultObjectType, type ResultType, type SetDataType, type SetErrorType, type SetterFuncParams, type UpdateStateParams, type UpdateStateType, createApi, initData, initState, loadMore, updateState, utils };
+export { type ApiContract, type BaseApiResponse, type DefaultField, _default as ENUM, type FetchResultCallback, type FetchType, type FieldGetter, type FieldKeys, type FieldSetter, type GenerateParamsResp, type GenerateParamsType, type InitDataType, type InitStateType, type KeyMap, type LoadMoreType, type ObjectKey, type RequestParams, type SetDataType, type SetErrorType, type SetterFuncParams, type UpdateStateType, createApi, generateFieldName$1 as generateFieldName, initData, initState, loadMore, updateState, utils };