@pisell/core 0.0.2

package/lib/indexDB/index.d.ts

@@ -0,0 +1,296 @@
+import App from "../app";
+export declare const mockPromise: (data: any, timeout?: number) => Promise<unknown>;
+/**
+ * IndexDB 管理器模块
+ *
+ * 这个模块使用 Dexie.js 提供了对浏览器 IndexedDB 的简单封装，并在不支持 IndexedDB 的环境中
+ * 自动降级使用内存存储作为备选存储方案。
+ */
+/**
+ * 数据库配置选项接口
+ * @interface DBOptions
+ * @property {string} dbName - 数据库名称
+ * @property {number} version - 数据库版本号
+ * @property {Array} stores - 存储对象配置数组
+ * @property {string} stores[].name - 存储对象名称
+ * @property {string} stores[].keyPath - 主键路径
+ * @property {Array} [stores[].indexes] - 索引配置数组（可选）
+ * @property {string} stores[].indexes[].name - 索引名称
+ * @property {string} stores[].indexes[].keyPath - 索引键路径
+ * @property {IDBIndexParameters} [stores[].indexes[].options] - 索引选项（可选）
+ */
+export interface DBOptions {
+    dbName: string;
+    version: number;
+    stores: {
+        name: string;
+        keyPath: string;
+        indexes?: {
+            name: string;
+            keyPath: string;
+            options?: IDBIndexParameters;
+        }[];
+    }[];
+    timeout?: number;
+}
+/**
+ * IndexDB 管理器类
+ * 使用 Dexie.js 提供对 IndexedDB 的封装，支持自动降级到内存存储
+ * @class IndexDBManager
+ */
+declare class IndexDBManager {
+    /**
+     * 检查环境是否支持 IndexedDB
+     * @returns {boolean} 是否支持 IndexedDB
+     * @private
+     */
+    private static isSupported;
+    private db;
+    private dbName;
+    private version;
+    private stores;
+    private useIndexDB;
+    private app;
+    private memoryStorage;
+    private timeout;
+    private debouncedBuffers;
+    private debouncedTimers;
+    private debouncedFlushing;
+    private debouncedDelay;
+    private debouncedBatchSize;
+    private debouncedUpdateBuffers;
+    private debouncedUpdateTimers;
+    private debouncedUpdateFlushing;
+    private debouncedUpdateDelay;
+    private debouncedUpdateBatchSize;
+    /**
+     * 创建 IndexDBManager 实例
+     * @param {DBOptions} options - 数据库配置选项
+     */
+    constructor(app: App, options: DBOptions);
+    /**
+     * 超时包装器 - 为 Promise 添加超时控制
+     * @param {Promise<T>} promise - 需要包装的 Promise
+     * @param {string} operation - 操作名称（用于错误提示）
+     * @returns {Promise<T>} 带超时控制的 Promise
+     * @private
+     */
+    private withTimeout;
+    /**
+     * 初始化数据库连接
+     * 如果环境不支持 IndexedDB，将自动使用内存存储
+     * @returns {Promise<boolean>} 连接是否成功
+     */
+    connect(): Promise<boolean>;
+    /**
+     * 获取内存存储中指定 store 的 Map
+     * @param {string} storeName - 存储对象名称
+     * @returns {Map<string | number, any>} 存储 Map
+     * @private
+     */
+    private getMemoryStore;
+    /**
+   * 防抖合并 add（用于高频写入场景）
+   * @param storeName 存储对象名称
+   * @param data 数据
+   */
+    debouncedAdd<T>(storeName: string, data: T): void;
+    /**
+   * 立即 flush 指定 store 的防抖 add
+   */
+    flushDebouncedAdd(storeName: string): Promise<void>;
+    /**
+   * 防抖合并 update（同 key 自动合并）
+   */
+    debouncedUpdate<T extends Record<string, any>>(storeName: string, data: T): void;
+    /**
+     * flush 防抖 update
+     */
+    flushDebouncedUpdate(storeName: string): Promise<void>;
+    /**
+     * 添加数据到指定的存储对象
+     * @param {string} storeName - 存储对象名称
+     * @param {T} data - 要添加的数据
+   * * @param {boolean} [log=true] - 是否记录日志
+     * @returns {Promise<T>} 添加的数据
+     * @template T
+     */
+    add<T>(storeName: string, data: T, log?: boolean): Promise<T>;
+    /**
+     * 快速检查指定存储对象中的数据是否存在
+     * @param {string} storeName - 存储对象名称
+     * @param {string|number} key - 数据主键
+     * @returns {Promise<boolean>} 数据是否存在
+     */
+    exists(storeName: string, key: string | number): Promise<boolean>;
+    /**
+     * 获取指定存储对象中的数据
+     * @param {string} storeName - 存储对象名称
+     * @param {string|number} key - 数据主键
+     * * @param {boolean} [log=true] - 是否记录日志
+     * @returns {Promise<T|null>} 获取的数据，不存在则返回 null
+     * @template T
+     */
+    get<T>(storeName: string, key: string | number, log?: boolean): Promise<T | null>;
+    /**
+     * 更新指定存储对象中的数据
+     * @param {string} storeName - 存储对象名称
+     * @param {T} data - 要更新的数据
+     * * @param {boolean} [log=true] - 是否记录日志
+     * @returns {Promise<T>} 更新后的数据
+     * @template T
+     */
+    update<T>(storeName: string, data: T, log?: boolean): Promise<T>;
+    /**
+     * 删除指定存储对象中的数据
+     * @param {string} storeName - 存储对象名称
+     * @param {string|number} key - 数据主键
+     * @returns {Promise<boolean>} 删除是否成功
+     */
+    delete(storeName: string, key: string | number): Promise<boolean>;
+    /**
+     * 通过索引获取数据
+     * @param {string} storeName - 存储对象名称
+     * @param {string} indexName - 索引名称
+     * @param {string|number} indexValue - 索引值
+     * @returns {Promise<T|null>} 获取的数据，不存在则返回 null
+     * @template T
+     */
+    getByIndex<T>(storeName: string, indexName: string, indexValue: string | number): Promise<T | null>;
+    /**
+     * 通过索引检查数据是否存在
+     * @param {string} storeName - 存储对象名称
+     * @param {string} indexName - 索引名称
+     * @param {string|number} indexValue - 索引值
+     * @returns {Promise<boolean>} 数据是否存在
+     */
+    existsByIndex(storeName: string, indexName: string, indexValue: string | number): Promise<boolean>;
+    /**
+     * 通过索引获取多条数据
+     * @param {string} storeName - 存储对象名称
+     * @param {string} indexName - 索引名称
+     * @param {string|number} indexValue - 索引值
+     * @returns {Promise<T[]>} 数据数组
+     * @template T
+     */
+    getAllByIndex<T>(storeName: string, indexName: string, indexValue: string | number): Promise<T[]>;
+    /**
+     * 统计指定存储对象中的数据数量
+     * @param {string} storeName - 存储对象名称
+     * @returns {Promise<number>} 数据数量
+     */
+    count(storeName: string): Promise<number>;
+    /**
+     * 通过索引统计数据数量
+     * @param {string} storeName - 存储对象名称
+     * @param {string} indexName - 索引名称
+     * @param {string|number} indexValue - 索引值
+     * @returns {Promise<number>} 数据数量
+     */
+    countByIndex(storeName: string, indexName: string, indexValue: string | number): Promise<number>;
+    /**
+     * 获取指定存储对象中的所有数据
+     * @param {string} storeName - 存储对象名称
+     * @returns {Promise<T[]>} 数据数组
+     * @template T
+     */
+    getAll<T>(storeName: string): Promise<T[]>;
+    /**
+     * 清空指定存储对象中的所有数据
+     * @param {string} storeName - 存储对象名称
+     * @returns {Promise<boolean>} 清空是否成功
+     */
+    clear(storeName: string): Promise<boolean>;
+    /**
+     * 关闭数据库连接
+     * 在不再需要使用数据库时调用，释放资源
+     */
+    close(): void;
+    /**
+     * 获取当前使用的存储方式
+     * @returns {'indexDB'|'memory'} 当前使用的存储方式
+     */
+    getCurrentStorage(): 'indexDB' | 'memory';
+}
+/**
+ * 使用示例:
+ *
+ * // 1. 创建数据库配置
+ * const dbOptions: DBOptions = {
+ *   dbName: 'myApp',
+ *   version: 1,
+ *   stores: [
+ *     {
+ *       name: 'users',
+ *       keyPath: 'id',
+ *       indexes: [
+ *         { name: 'email', keyPath: 'email', options: { unique: true } },
+ *         { name: 'department', keyPath: 'department', options: { unique: false } }
+ *       ]
+ *     },
+ *     {
+ *       name: 'products',
+ *       keyPath: 'id'
+ *     }
+ *   ]
+ * };
+ *
+ * // 2. 创建并连接数据库
+ * const db = new IndexDBManager(app, dbOptions);
+ * await db.connect();
+ *
+ * // 3. 添加数据
+ * const user = { id: '1', name: '张三', email: 'zhangsan@example.com', department: 'IT' };
+ * await db.add('users', user);
+ *
+ * // 4. 获取数据
+ * const retrievedUser = await db.get('users', '1');
+ *
+ * // 5. 快速检查数据是否存在（推荐用法）
+ * const userExists = await db.exists('users', '1'); // 返回 true/false，比 get 更高效
+ *
+ * // 6. 通过索引获取数据
+ * const userByEmail = await db.getByIndex('users', 'email', 'zhangsan@example.com');
+ *
+ * // 7. 通过索引检查数据是否存在
+ * const emailExists = await db.existsByIndex('users', 'email', 'zhangsan@example.com');
+ *
+ * // 8. 通过索引获取多条数据
+ * const itUsers = await db.getAllByIndex('users', 'department', 'IT');
+ *
+ * // 9. 统计数据数量
+ * const totalUsers = await db.count('users');
+ * const itUserCount = await db.countByIndex('users', 'department', 'IT');
+ *
+ * // 10. 更新数据
+ * user.name = '张三 (已更新)';
+ * await db.update('users', user);
+ *
+ * // 11. 获取所有数据
+ * const allUsers = await db.getAll('users');
+ *
+ * // 12. 删除数据
+ * await db.delete('users', '1');
+ *
+ * // 13. 清空存储对象
+ * await db.clear('users');
+ *
+ * // 14. 关闭数据库连接
+ * db.close();
+ *
+ * // 15. 检查当前使用的存储方式
+ * const storageType = db.getCurrentStorage(); // 'indexDB' 或 'memory'
+ *
+ * // 性能优化建议：
+ * // - 使用 exists() 而不是 get() 来检查数据是否存在
+ * // - 为常用查询字段创建索引
+ * // - 使用索引查询方法来提高查询效率
+ * // - 批量操作时使用事务（可以考虑后续扩展）
+ *
+ * // 降级方案说明：
+ * // - 当浏览器不支持 IndexedDB 时，会自动使用内存存储 (Map) 作为降级方案
+ * // - 内存存储的数据在页面刷新后会丢失，仅适合临时数据存储
+ * // - 内存存储支持所有 IndexedDB API，包括索引查询
+ * // - 对于需要持久化的数据，请确保浏览器支持 IndexedDB
+ */
+export default IndexDBManager;