@flowlist/js-core 4.0.4-beta.0 → 4.0.6-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,145 +98,102 @@ 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> {
+interface SetDataType {
     readonly getter: FieldGetter;
     readonly setter: FieldSetter;
+    readonly data: BaseApiResponse;
+    readonly fieldName: string;
+    readonly type: FetchType;
+    readonly page: number;
+    readonly insertBefore: boolean;
 }
-/**
- * 初始化状态的参数对外接口
- */
-interface InitStateParams<P = RequestParams, R = ResultType> {
-    readonly func: ApiContract<P, R>;
-    readonly query?: P;
-    readonly opts?: Partial<DefaultField>;
-}
-/**
- * 初始化状态的参数（内部）
- */
-interface InitStateType<P = RequestParams, R = ResultType> extends InitStateParams<P, R> {
-    readonly getter: FieldGetter;
+interface SetErrorType {
     readonly setter: FieldSetter;
+    readonly fieldName: string;
+    readonly error: Error | null;
 }
 /**
- * 初始化数据的参数对外接口
+ * 初始化状态的外部参数
  */
-type InitDataParams<P = RequestParams, R = ResultType> = CommonParams<P, R>;
-/**
- * 初始化数据的参数（内部）
- */
-type InitDataType<P = RequestParams, R = ResultType> = BaseFetchConfig<P, R>;
-/**
- * 加载更多的参数对外接口
- */
-interface LoadMoreParams<P = RequestParams, R = ResultType> extends CommonParams<P, R> {
-    readonly errorRetry?: boolean;
+interface InitStateParams<P extends RequestParams = RequestParams, R = any> {
+    readonly func: ApiContract<P, R>;
+    readonly query?: P;
+    readonly opts?: Partial<DefaultField<R>>;
 }
 /**
- * 加载更多的参数（内部）
+ * 初始化数据的外部参数
  */
-interface LoadMoreType<P = RequestParams, R = ResultType> extends BaseFetchConfig<P, R> {
-    readonly errorRetry?: boolean;
+interface InitDataParams<P extends RequestParams = RequestParams, R = any> {
+    readonly func: ApiContract<P, R>;
+    readonly query?: P;
+    readonly callback?: FetchResultCallback<P, R>;
 }
 /**
- * 更新状态的参数（内部使用）
+ * 加载更多的外部参数
  */
-interface UpdateStateType<P = RequestParams, R = ResultType, T = KeyMap> {
-    readonly getter: FieldGetter;
-    readonly setter: FieldSetter;
+interface LoadMoreParams<P extends RequestParams = RequestParams, R = any> {
     readonly func: ApiContract<P, R>;
     readonly query?: P;
-    readonly method: string;
-    readonly value: T | T[] | KeyMap | KeyMap[];
-    readonly id?: ObjectKey | ObjectKey[];
-    readonly changeKey?: string;
+    readonly errorRetry?: boolean;
+    readonly callback?: FetchResultCallback<P, R>;
 }
 /**
- * 更新状态的参数（对外接口）
+ * 更新状态的外部参数
  */
-interface UpdateStateParams<P = RequestParams, R = ResultType, T = KeyMap> {
+interface UpdateStateParams<P extends RequestParams = RequestParams, R = any> {
     readonly func: ApiContract<P, R>;
     readonly query?: P;
     readonly method: string;
-    readonly value: T | T[] | KeyMap | KeyMap[];
+    readonly value: any;
     readonly id?: ObjectKey | ObjectKey[];
     readonly changeKey?: string;
     readonly uniqueKey?: string;
 }
-/**
- * 设置数据的参数
- */
-interface SetDataType {
+interface InitStateType<P extends RequestParams, R> extends InitStateParams<P, R> {
     readonly getter: FieldGetter;
     readonly setter: FieldSetter;
-    readonly data: ApiResponse;
-    readonly fieldName: string;
-    readonly type: FetchType;
-    readonly page: number;
-    readonly insertBefore: boolean;
 }
-/**
- * 设置错误的参数
- */
-interface SetErrorType {
+interface InitDataType<P extends RequestParams, R> extends InitDataParams<P, R> {
+    readonly getter: FieldGetter;
     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[];
+interface LoadMoreType<P extends RequestParams, R> extends LoadMoreParams<P, R> {
+    readonly getter: FieldGetter;
+    readonly setter: FieldSetter;
 }
-declare function createApi<P = RequestParams, R = ResultType>(options: {
+interface UpdateStateType<P extends RequestParams, R> extends UpdateStateParams<P, R> {
+    readonly getter: FieldGetter;
+    readonly setter: FieldSetter;
+}
+
+declare const generateFieldName$1: <P extends RequestParams, R>({ func, query }: {
+    func: ApiContract<P, R>;
+    query?: P;
+}) => string;
+declare const createApi: <P extends RequestParams, R>(options: {
     id: string;
     type?: FetchType;
     uniqueKey?: string;
     paramsIgnore?: string[];
-    fetcher: (params: P) => Promise<ApiResponse<R>>;
-}): ApiContract<P, R>;
+    fetcher: (params: P) => Promise<BaseApiResponse<R>>;
+}) => ApiContract<P, R>;
+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 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>;
-
-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
  */
@@ -246,20 +210,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;
@@ -268,19 +236,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: {
@@ -315,4 +286,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 InitDataParams, type InitDataType, type InitStateParams, type InitStateType, type KeyMap, type LoadMoreParams, type LoadMoreType, type ObjectKey, type RequestParams, type SetDataType, type SetErrorType, type SetterFuncParams, type UpdateStateParams, type UpdateStateType, createApi, generateFieldName$1 as generateFieldName, initData, initState, loadMore, updateState, utils };