@flowlist/js-core 2.3.1 → 3.0.1

package/README.md

@@ -1,114 +1,86 @@
 # @flowlist/js-core
 
-<p align="center">
-    <a target="_blank" href="https://travis-ci.org/github/flowlist/js-core">
-        <img alt="Build" src="https://travis-ci.org/flowlist/js-core.svg?branch=master" />
-    </a>
-    <a target="_blank" href="https://codecov.io/gh/flowlist/js-core">
-        <img alt="Coverage" src="https://codecov.io/gh/flowlist/js-core/branch/master/graph/badge.svg" />
-    </a>
-    <a target="_blank" href="https://www.npmjs.com/package/@flowlist/js-core">
-        <img alt="Version" src="https://badge.fury.io/js/%40flowlist%2Fjs-core.svg" />
-    </a>
-    <a target="_blank" href="https://github.com/flowlist/js-core/blob/master/LICENSE">
-        <img alt="License" src="https://gitlicense.com/badge/flowlist/js-core"/>
-    </a>
-</p>
+[![npm version](https://img.shields.io/npm/v/@flowlist/js-core.svg)](https://www.npmjs.com/package/@flowlist/js-core)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
 
-## 信息流业务通用容器的基础实现
+A lightweight, type-safe JavaScript core library for managing data flow in list-based UIs. It provides a unified interface for initializing, loading, paginating, and updating list data with built-in state management and caching support.
 
-### Download
+## ✨ Features
 
-``` bash
-yarn add @flowlist/js-core
-```
-
-### Import
-```javascript
-import flow from '@flowlist/js-core'
-```
-
-### Inject
-
-- getter：get state
-> 如 [Vuex.getter](https://github.com/flowlist/js-core/blob/master/tests/unit/env.js#L3)
-
-- setter：set state
-> 如：[React.setState](https://github.com/flowlist/js-core/blob/master/tests/unit/env.js#L8)
-
-- cache：cache instance
-> [包含 get<Promise>，set<Promise>，del 三个方法](https://github.com/flowlist/js-core/blob/master/tests/unit/env.js#L20)
-
-- api：named api list
-> [把需要调用的所有 API export 出来](https://github.com/flowlist/js-core/blob/master/tests/unit/api.js)
+- 🧠 **Declarative Data Flow**: Define how your list data is fetched and updated.
+- 📦 **Built-in State Management**: Handles loading, error, pagination, and cache states automatically.
+- 🔁 **Multiple Fetch Strategies**: Supports pagination, infinite scroll, since-id, seen-ids, and more.
+- 🔄 **Flexible Updates**: Add, remove, update, or merge list items with ease.
+- 💾 **Cache Ready**: Designed to work seamlessly with external cache layers.
+- 🧪 **TypeScript First**: Full TypeScript support with comprehensive type definitions.
+- 🧩 **Framework Agnostic**: Works with React, Vue, Svelte, or vanilla JS.
 
-### Methods
+## 🚀 Installation
 
-- `initState`
+```bash
+# Using npm
+npm install @flowlist/js-core
 
-> 初始化数据容器
-
-| 参数 | 类型 | 介绍 |
-| --- | --- | --- |
-| getter | Function | 设置 state 的函数 |
-| setter | Function | 读取 state 的函数 |
-| func | String | API层的函数名 |
-| type | String\<ListType\> | 列表的类型 |
-| query | Object | 需要额外透传给 API 层的数据 |
-
-- `initData`
-
-> 加载首屏数据
-
-| 参数 | 类型 | 介绍 |
-| --- | --- | --- |
-| getter | Function | 设置 state 的函数 |
-| setter | Function | 读取 state 的函数 |
-| cache | Object | 用于读写缓存的对象 |
-| func | String | API层的函数名 |
-| type | String\<ListType\> | 列表的类型 |
-| query | Object | 需要额外透传给 API 层的数据 |
-| api | Array\<API\> | 整个 API 层 |
-| cacheTimeout | Integer | 缓存持久化的时间（秒） |
-| uniqueKey | String | 列表里每个元素独一无二的 key |
-| callback | Function | 请求成功之后的回调函数 |
-
-- `loadMore`
-
-> 加载分页数据
-
-| 参数 | 类型 | 介绍 |
-| --- | --- | --- |
-| getter | Function | 设置 state 的函数 |
-| setter | Function | 读取 state 的函数 |
-| cache | Object | 用于读写缓存的对象 |
-| func | String | API层的函数名 |
-| type | String\<ListType\> | 列表的类型 |
-| query | Object | 需要额外透传给 API 层的数据 |
-| api | Array\<API\> | 整个 API 层 |
-| cacheTimeout | Integer | 缓存持久化的时间（秒） |
-| uniqueKey | String | 列表里每个元素独一无二的 key |
-| errorRetry | Boolean | 是否是重试 |
-| callback | Function | 请求成功之后的回调函数 |
+# Using yarn
+yarn add @flowlist/js-core
+```
 
-- `updateState`
+## 📦 Usage
 
-> 更新数据容器
+```ts
+import flow from '@flowlist/js-core'
 
-```javascript
-flow.updateState({ getter, setter, cache, type, func, query, method, value, id, uniqueKey, changeKey, cacheTimeout })
+// 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({
+  getter,
+  setter,
+  func: 'fetchPosts',
+  type: 'page', // or 'sinceId', 'seenIds', 'auto', etc.
+  query: { userId: 123 }
+})
+
+// 2. Load initial data
+await flow.initData({
+  getter,
+  setter,
+  cache,
+  func: 'fetchPosts',
+  type: 'page',
+  query: { userId: 123 },
+  api,
+  uniqueKey: 'id',
+  cacheTimeout: 300 // 5 minutes
+})
+
+// 3. Load more data (e.g., on scroll)
+await flow.loadMore({
+  getter,
+  setter,
+  cache,
+  func: 'fetchPosts',
+  type: 'page',
+  query: { userId: 123 },
+  api,
+  uniqueKey: 'id',
+  errorRetry: false
+})
+
+// 4. Update list data locally
+await flow.updateState({
+  getter,
+  setter,
+  cache,
+  func: 'fetchPosts',
+  type: 'page',
+  query: { userId: 123 },
+  method: 'push', // or 'delete', 'update', 'merge', etc.
+  value: newPost,
+  id: newPost.id,
+  uniqueKey: 'id',
+  changeKey: 'result',
+  cacheTimeout: 300
+})
 ```
-| 参数 | 类型 | 介绍 |
-| --- | --- | --- |
-| getter | Function | 设置 state 的函数 |
-| setter | Function | 读取 state 的函数 |
-| cache | Object | 用于读写缓存的对象 |
-| func | String | API层的函数名 |
-| type | String\<ListType\> | 列表的类型 |
-| query | Object | 需要额外透传给 API 层的数据 |
-| method | String | 需要调用的函数名 |
-| value | Any | 传值 |
-| id | String / Number | 用来索引的独一无二的 keyValue |
-| uniqueKey | String | 列表里每个元素独一无二的 keyName |
-| changeKey | String | 你想要修改的`field`是哪个字段，默认是`result` |
-| cacheTimeout | Integer | 缓存持久化的时间（秒） |

package/dist/index.d.mts

@@ -0,0 +1,263 @@
+/**
+ * 对象的唯一标识符类型
+ */
+type ObjectKey = string | number;
+/**
+ * 通用键值对映射（注意：尽管 ObjectKey 包含 number，
+ * 但在实际对象中，number 键会被转为 string。
+ * 此处使用 string 以符合 Record 的实际行为 [[3]]）
+ */
+type KeyMap = Record<string, unknown>;
+/**
+ * 形态数组
+ */
+type MorphArray = unknown[];
+/**
+ * 数据源类型：可以是 API 路径字符串，或返回 Promise 的函数
+ */
+type DataSource = string | ((params: unknown) => Promise<unknown>);
+/**
+ * 字段获取器：根据字段名获取状态对象
+ */
+type FieldGetter<T = unknown, E = unknown> = (key: string) => DefaultField<T, E> | undefined;
+/**
+ * 状态设置器函数类型
+ */
+type FieldSetter = (obj: SetterFuncParams) => void;
+/**
+ * 获取数据后的回调函数
+ */
+type FetchResultCallback = (obj: {
+    params: GenerateParamsResp;
+    data: unknown;
+    refresh: boolean;
+}) => void;
+/**
+ * 数据获取类型枚举
+ */
+type FetchType = 'jump' | 'sinceId' | 'page' | 'seenIds' | 'auto';
+/**
+ * 字段数据的关键字
+ */
+type FieldKeys = 'result' | 'noMore' | 'nothing' | 'loading' | 'error' | 'extra' | 'fetched' | 'page' | 'total';
+/**
+ * 生成字段名称的参数
+ */
+interface GenerateFieldProps {
+    func: DataSource;
+    type: FetchType;
+    query?: KeyMap;
+}
+/**
+ * 生成请求参数的输入
+ */
+interface GenerateParamsType {
+    field: DefaultField<unknown, unknown>;
+    uniqueKey?: string;
+    query?: KeyMap;
+    type: FetchType;
+}
+/**
+ * 生成请求参数的输出
+ */
+interface GenerateParamsResp {
+    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;
+}
+/**
+ * 默认字段数据结构，使用泛型 T 和 E 分别代表 result 和 extra 的类型
+ */
+interface DefaultField<T = unknown, E = unknown> {
+    result: T;
+    noMore: boolean;
+    nothing: boolean;
+    loading: boolean;
+    error: null | Error;
+    extra: E;
+    fetched: boolean;
+    page: number;
+    total: number;
+}
+/**
+ * API 响应结构，使用泛型 T 和 E
+ */
+interface ApiResponse<T = unknown, E = unknown> {
+    result: T;
+    extra?: E;
+    total?: number;
+    no_more?: boolean;
+}
+interface BaseFetchConfig {
+    getter: FieldGetter;
+    setter: FieldSetter;
+    func: DataSource;
+    type: FetchType;
+    query?: KeyMap;
+    api?: KeyMap;
+    uniqueKey?: string;
+    callback?: FetchResultCallback;
+}
+/**
+ * 初始化状态的参数
+ */
+interface InitStateType {
+    getter: FieldGetter;
+    setter: FieldSetter;
+    func: DataSource;
+    type: FetchType;
+    query?: KeyMap;
+    opts?: Partial<DefaultField<unknown, unknown>>;
+}
+/**
+ * 初始化数据的参数
+ */
+type InitDataType = BaseFetchConfig;
+/**
+ * 加载更多的参数
+ */
+interface LoadMoreType extends BaseFetchConfig {
+    errorRetry?: boolean;
+}
+/**
+ * 更新状态的参数
+ */
+interface UpdateStateType<T = unknown, E = unknown> {
+    getter: FieldGetter<T, E>;
+    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 SetDataType<T = unknown, E = unknown> {
+    getter: FieldGetter<T, E>;
+    setter: FieldSetter;
+    data: T | ApiResponse<T, E>;
+    fieldName: string;
+    type: FetchType;
+    page: number;
+    insertBefore: boolean;
+}
+/**
+ * 设置错误的参数
+ */
+interface SetErrorType {
+    setter: FieldSetter;
+    fieldName: string;
+    error: Error;
+}
+type ResultArrayType$1 = KeyMap[];
+type ResultObjectType$1 = Record<ObjectKey, KeyMap[]>;
+
+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>;
+
+/**
+ * 判断数据是否为对象结果（即没有 result 字段）
+ * 注意：这里我们假设 "对象结果" 指的是一个普通的对象，而不是 ApiResponse。
+ */
+declare const isObjectResult: (data: unknown) => data is Record<string, unknown>;
+/**
+ * 生成默认字段
+ */
+declare const generateDefaultField: <T = unknown, E = unknown>(opts?: Partial<DefaultField<T, E>>) => DefaultField<T, E>;
+/**
+ * 根据参数生成 field 的 namespace
+ */
+declare const generateFieldName: ({ func, type, query }: GenerateFieldProps) => 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 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: <T, E>(field: DefaultField<T, E>, 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 utils_combineArrayData: typeof combineArrayData;
+declare const utils_computeMatchedItemIndex: typeof computeMatchedItemIndex;
+declare const utils_computeResultLength: typeof computeResultLength;
+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_isArray: typeof isArray;
+declare const utils_isObjectResult: typeof isObjectResult;
+declare const utils_searchValueByKey: typeof searchValueByKey;
+declare const utils_setReactivityField: typeof setReactivityField;
+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_isObjectResult as isObjectResult, utils_searchValueByKey as searchValueByKey, utils_setReactivityField as setReactivityField, utils_updateObjectDeepValue as updateObjectDeepValue };
+}
+
+declare const _default: {
+    readonly SETTER_TYPE: {
+        readonly RESET: 0;
+        readonly MERGE: 1;
+    };
+    readonly FETCH_TYPE_ARRAY: readonly ["jump", "sinceId", "page", "seenIds", "auto"];
+    readonly FETCH_TYPE: {
+        readonly PAGINATION: "jump";
+        readonly SINCE_FIRST_OR_END_ID: "sinceId";
+        readonly SCROLL_LOAD_MORE: "page";
+        readonly HAS_LOADED_IDS: "seenIds";
+        readonly AUTO: "auto";
+    };
+    readonly CHANGE_TYPE: {
+        readonly SEARCH_FIELD: "search";
+        readonly RESET_FIELD: "reset";
+        readonly RESULT_UPDATE_KV: "update";
+        readonly RESULT_ADD_AFTER: "push";
+        readonly RESULT_ADD_BEFORE: "unshift";
+        readonly RESULT_REMOVE_BY_ID: "delete";
+        readonly RESULT_INSERT_TO_BEFORE: "insert-before";
+        readonly RESULT_INSERT_TO_AFTER: "insert-after";
+        readonly RESULT_LIST_MERGE: "patch";
+        readonly RESULT_ITEM_MERGE: "merge";
+    };
+    readonly FIELD_DATA: {
+        readonly RESULT_KEY: "result";
+        readonly EXTRA_KEY: "extra";
+    };
+    readonly DEFAULT_UNIQUE_KEY_NAME: "id";
+};
+
+export { type ApiResponse, type DefaultField, _default as ENUM, type FetchType, type FieldKeys, type GenerateFieldProps, type GenerateParamsResp, type GenerateParamsType, type InitDataType, type InitStateType, type KeyMap, type LoadMoreType, type MorphArray, type ObjectKey, type ResultArrayType$1 as ResultArrayType, type ResultObjectType$1 as ResultObjectType, type SetDataType, type SetErrorType, type SetterFuncParams, type UpdateStateType, initData, initState, loadMore, updateState, utils };