@iss-ai/easy-web-store 0.0.1 → 0.0.2

package/README.md

@@ -1,15 +1,17 @@
 # @iss-ai/easy-web-store
 
-一个简单高效的 Web 应用状态管理库，基于 Dexie.js 封装 IndexedDB，提供便捷的 CRUD 操作。
+一个简单高效的 Web 应用数据存储库，提供多种存储方式（IndexedDB、localStorage、sessionStorage、Cookies、内存），支持完整的 CRUD 操作和丰富的查询条件。
 
 ## ✨ 特性
 
 - 🚀 **简单易用**：直观的 API 设计，快速上手
-- 💾 **持久化存储**：基于 IndexedDB，数据持久保存在浏览器
+- 💾 **多种存储方式**：支持 IndexedDB、localStorage、sessionStorage、Cookies、内存存储
 - 🔧 **TypeScript 支持**：完整的类型定义
-- 📦 **零依赖**：仅依赖 Dexie.js
+- 📦 **轻量级**：零依赖（IndexedDB 版本仅依赖 Dexie.js）
 - 🌐 **跨浏览器**：支持现代浏览器（Last 2 versions, > 5%, not IE <= 9）
 - 📄 **完整 CRUD**：提供保存、查询、更新、删除等完整数据操作
+- 🔍 **丰富查询**：支持多种查询操作符（$eq, $neq, $gt, $lt, $in, $like, $regexp 等）
+- 📃 **分页支持**：内置分页功能
 
 ## 📦 安装
 
@@ -32,280 +34,310 @@ pnpm add @iss-ai/easy-web-store
 import { EasyDexieStore } from '@iss-ai/easy-web-store';
 
 // 定义数据类型
-interface Product {
+interface User {
   id?: string | number;
   name: string;
-  price: number;
-  category: string;
+  email: string;
+  age: number;
   createTime?: Date;
   updateTime?: Date;
 }
 
-// 创建数据存储实例
-const productStore = new EasyDexieStore<Product>('products', 'my-db');
+// 创建数据存储实例（IndexedDB）
+const userStore = new EasyDexieStore<User>('users', 'my-app-db');
 
 // 保存数据
-await productStore.save({
-  name: 'iPhone 15',
-  price: 6999,
-  category: '电子产品'
+const user = await userStore.save({
+  name: 'John',
+  email: 'john@example.com',
+  age: 25
 });
 
 // 查询数据
-const products = await productStore.getList({
-  where: { category: '电子产品' },
-  sort: { price: -1 }
+const users = await userStore.getList({
+  where: { age: { $gt: 18 } },
+  sort: { createTime: -1 }
 });
 
-// 更新数据
-await productStore.update({ price: 6799 }, { name: 'iPhone 15' });
+// 更新数据（更新所有符合条件的记录）
+await userStore.update({ age: 26 }, { name: 'John' });
 
 // 删除数据
-await productStore.delete({ category: '电子产品' });
+await userStore.delete({ name: 'John' });
 ```
 
-## 📖 API 文档
-
-### EasyDexieStore 构造函数
+### 使用不同的存储方式
 
 ```typescript
-new EasyDexieStore<T>(tableName?: string, dbName?: string, tableSchema?: string)
-```
+import { 
+  EasyDexieStore,       // IndexedDB（推荐，容量大，支持复杂查询）
+  EasyMemoryStore,      // 内存存储（应用重启后数据丢失）
+  EasyLocalStorage,     // localStorage（持久化，约 5MB 容量）
+  EasySessionStorage,   // sessionStorage（页面关闭后数据丢失）
+  EasyCookiesStore      // Cookies（小数据量，支持过期时间）
+} from '@iss-ai/easy-web-store';
 
-| 参数 | 类型 | 默认值 | 描述 |
-|------|------|--------|------|
-| tableName | string | 'store' | 数据表名称 |
-| dbName | string | 'easy-store' | 数据库名称 |
-| tableSchema | string | undefined | 自定义表结构 |
+// 内存存储 - 适合临时数据
+const memoryStore = new EasyMemoryStore<User>('temp-users');
 
-### 核心方法
+// localStorage - 适合持久化数据
+const localStore = new EasyLocalStorage<User>('users');
 
-#### save() - 保存或更新单条数据
+// sessionStorage - 适合会话数据
+const sessionStore = new EasySessionStorage<User>('session-users');
 
-```typescript
-async save(data: Omit<T, 'id'> | T): Promise<T>
+// Cookies - 适合小数据量、需要与服务端交互的场景
+const cookiesStore = new EasyCookiesStore<User>('cookie-users');
 ```
 
-- **新增数据**：不指定 `id` 字段
-- **更新数据**：指定已有数据的 `id` 字段
-- 自动处理 `createTime` 和 `updateTime`
+## 📖 API 文档
 
-#### saveList() - 批量保存数据
+### 通用接口
 
-```typescript
-async saveList(dataList: Array<Omit<T, 'id'> | T>): Promise<T[]>
-```
+所有存储类都实现 `IEasyStore<T>` 接口，提供相同的方法：
 
-批量添加数据，返回保存后的完整数据列表。
+| 方法 | 描述 | 返回值 |
+|------|------|--------|
+| `save(data)` | 保存或更新单条数据 | `Promise<T>` |
+| `saveList(dataList)` | 批量保存数据 | `Promise<T[]>` |
+| `getList(condition?)` | 获取数据列表 | `Promise<T[]>` |
+| `getInfo(condition)` | 获取单条数据 | `Promise<T \| null>` |
+| `update(data, condition)` | 更新符合条件的数据 | `Promise<T \| null>` |
+| `delete(condition)` | 删除符合条件的数据 | `Promise<number>` |
+| `count(condition)` | 统计符合条件的数量 | `Promise<number>` |
+| `getPage(condition)` | 分页获取数据 | `Promise<IPage<T>>` |
+| `clear()` | 清空所有数据 | `Promise<void>` |
 
-#### getList() - 获取数据列表
+### 查询条件
 
 ```typescript
-async getList(condition?: IQueryCondition<T>): Promise<T[]>
+interface IQueryCondition<T> {
+  where?: Partial<T>;      // 查询条件
+  sort?: Record<string, 1 | -1>;  // 排序规则
+  page?: number;           // 页码（从 1 开始）
+  pageSize?: number;       // 每页数量
+  fields?: Partial<Record<keyof T, 1>>;  // 字段选择
+}
 ```
 
-支持以下查询方式：
+### 查询操作符
 
-- **获取全部**：无参数查询
-- **条件查询**：按字段值过滤
-- **排序查询**：按指定字段排序
-- **字段选择**：只返回指定字段
-- **复杂条件**：使用操作符（`$gt`, `$lt`, `$in`, `$like` 等）
-
-示例：
+| 操作符 | 说明 | 示例 |
+|--------|------|------|
+| `$eq` | 等于 | `{ age: { $eq: 18 } }` |
+| `$neq` | 不等于 | `{ age: { $neq: 18 } }` |
+| `$gt` | 大于 | `{ age: { $gt: 18 } }` |
+| `$gte` | 大于等于 | `{ age: { $gte: 18 } }` |
+| `$lt` | 小于 | `{ age: { $lt: 18 } }` |
+| `$lte` | 小于等于 | `{ age: { $lte: 18 } }` |
+| `$in` | 在数组中 | `{ age: { $in: [18, 25, 30] } }` |
+| `$nin` | 不在数组中 | `{ age: { $nin: [18, 25] } }` |
+| `$like` | 包含字符串 | `{ name: { $like: 'John' } }` |
+| `$likeIgnoreCase` | 包含字符串（忽略大小写） | `{ name: { $likeIgnoreCase: 'john' } }` |
+| `$startsWith` | 以指定字符串开头 | `{ name: { $startsWith: 'J' } }` |
+| `$startsWithIgnoreCase` | 以指定字符串开头（忽略大小写） | `{ name: { $startsWithIgnoreCase: 'j' } }` |
+| `$regexp` | 正则表达式匹配 | `{ email: { $regexp: /^[a-z]+@/ } }` |
+
+### 各类存储特点
+
+#### EasyDexieStore (IndexedDB)
+
+- **容量**：大容量（通常 50MB+）
+- **持久化**：是
+- **查询能力**：支持完整查询操作符
+- **适用场景**：大量数据存储、复杂查询
 
 ```typescript
-// 获取全部
-const all = await store.getList();
-
-// 条件查询
-const filtered = await store.getList({
-  where: { category: '电子产品' }
-});
-
-// 排序查询
-const sorted = await store.getList({
-  sort: { price: -1 } // -1 降序，1 升序
-});
-
-// 复杂条件
-const complex = await store.getList({
-  where: {
-    price: { $gt: 1000, $lt: 10000 }
-  }
-});
+const store = new EasyDexieStore<User>('users', 'my-db', 'id,createTime,updateTime,name,email');
 ```
 
-#### getInfo() - 获取单条信息
+#### EasyMemoryStore (内存)
+
+- **容量**：受限于浏览器内存
+- **持久化**：否（应用重启后丢失）
+- **查询能力**：支持完整查询操作符
+- **适用场景**：临时数据、缓存
 
 ```typescript
-async getInfo(condition: Partial<T>): Promise<T | null>
+const store = new EasyMemoryStore<User>('temp-data');
 ```
 
-根据条件获取第一条匹配的数据，不存在则返回 `null`。
+#### EasyLocalStorage (localStorage)
 
-#### update() - 更新数据
+- **容量**：约 5MB
+- **持久化**：是
+- **查询能力**：支持完整查询操作符
+- **适用场景**：中等数据量、需要持久化
 
 ```typescript
-async update(data: Record<string, any>, condition: Partial<T>): Promise<T | null>
+const store = new EasyLocalStorage<User>('user-preferences');
 ```
 
-根据条件查找数据并更新指定字段，自动更新 `updateTime`。
+#### EasySessionStorage (sessionStorage)
 
-#### delete() - 删除数据
+- **容量**：约 5MB
+- **持久化**：否（页面关闭后丢失）
+- **查询能力**：支持完整查询操作符
+- **适用场景**：会话数据、临时表单
 
 ```typescript
-async delete(condition: Partial<T>): Promise<number>
+const store = new EasySessionStorage<User>('session-data');
 ```
 
-根据条件删除匹配的数据，返回删除的记录数。
+#### EasyCookiesStore (Cookies)
 
-#### count() - 数据统计
+- **容量**：约 4KB
+- **持久化**：可设置过期时间
+- **查询能力**：支持完整查询操作符
+- **适用场景**：小数据量、需要与服务端共享
 
 ```typescript
-async count(condition: Partial<T>): Promise<number>
+const store = new EasyCookiesStore<User>('user-settings');
 ```
 
-统计符合条件的记录数，空条件统计全部。
+## 📝 使用示例
 
-#### getPage() - 分页查询
+### 完整 CRUD 示例
 
 ```typescript
-async getPage(condition: IQueryCondition<T>): Promise<IPage<T>>
-```
-
-返回分页结果：
+import { EasyDexieStore } from '@iss-ai/easy-web-store';
 
-```typescript
-{
-  list: T[],      // 数据列表
-  total: number,  // 总记录数
-  page: number,   // 当前页码
-  size: number,   // 每页数量
-  totalPages: number // 总页数
+interface Product {
+  id?: string;
+  name: string;
+  price: number;
+  category: string;
+  tags?: string[];
+  createTime?: Date;
+  updateTime?: Date;
 }
-```
 
-#### clear() - 清空所有数据
+const productStore = new EasyDexieStore<Product>('products', 'shop-db');
 
-```typescript
-async clear(): Promise<void>
-```
+// 创建
+await productStore.save({
+  name: 'iPhone 15',
+  price: 6999,
+  category: 'electronics',
+  tags: ['apple', 'smartphone']
+});
 
-清空表中所有数据。
+// 批量创建
+await productStore.saveList([
+  { name: 'MacBook Pro', price: 14999, category: 'electronics' },
+  { name: 'AirPods', price: 1299, category: 'electronics' }
+]);
 
-#### close() - 关闭数据库连接
+// 查询 - 简单条件
+const electronics = await productStore.getList({
+  where: { category: 'electronics' }
+});
 
-```typescript
-close(): void
-```
+// 查询 - 复杂条件
+const expensiveProducts = await productStore.getList({
+  where: {
+    price: { $gt: 5000 },
+    name: { $likeIgnoreCase: 'iphone' }
+  },
+  sort: { price: -1 }
+});
 
-关闭数据库连接。
+// 查询 - 正则表达式
+const appleProducts = await productStore.getList({
+  where: { name: { $regexp: /apple/i } }
+});
 
-## 🔍 查询操作符
+// 分页查询
+const page1 = await productStore.getPage({
+  where: { category: 'electronics' },
+  page: 1,
+  pageSize: 10,
+  sort: { createTime: -1 }
+});
 
-| 操作符 | 描述 | 示例 |
-|--------|------|------|
-| `$ne` | 不等于 | `{ price: { $ne: 100 } }` |
-| `$gt` | 大于 | `{ price: { $gt: 100 } }` |
-| `$gte` | 大于等于 | `{ price: { $gte: 100 } }` |
-| `$lt` | 小于 | `{ price: { $lt: 100 } }` |
-| `$lte` | 小于等于 | `{ price: { $lte: 100 } }` |
-| `$in` | 在数组中 | `{ category: { $in: ['A', 'B'] } }` |
-| `$nin` | 不在数组中 | `{ category: { $nin: ['C'] } }` |
-| `$like` | 包含字符串 | `{ name: { $like: 'phone' } }` |
+// 更新
+await productStore.update(
+  { price: 6799 },
+  { name: 'iPhone 15' }
+);
 
-## 📋 类型定义
+// 统计
+const count = await productStore.count({ category: 'electronics' });
 
-### IBase
+// 删除
+await productStore.delete({ category: 'electronics' });
 
-基础接口，所有数据类型都应继承此接口：
+// 清空
+await productStore.clear();
+```
+
+### 响应式数据同步示例
 
 ```typescript
-interface IBase {
-  id?: string | number;
+import { EasyLocalStorage } from '@iss-ai/easy-web-store';
+
+interface Todo {
+  id?: string;
+  title: string;
+  completed: boolean;
   createTime?: Date;
   updateTime?: Date;
 }
-```
 
-### IQueryCondition
+class TodoStore {
+  private store: EasyLocalStorage<Todo>;
+  private listeners: Set<() => void> = new Set();
 
-查询条件接口：
+  constructor() {
+    this.store = new EasyLocalStorage<Todo>('todos');
+  }
 
-```typescript
-interface IQueryCondition<T> {
-  where?: Partial<T>;     // 查询条件
-  sort?: Record<string, 1 | -1>; // 排序规则
-  page?: number;          // 分页页码（从 1 开始）
-  pageSize?: number;      // 每页数量
-  fields?: Partial<Record<keyof T, 1>>; // 字段选择
-}
-```
+  // 订阅数据变化
+  subscribe(listener: () => void) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  // 通知所有订阅者
+  private notify() {
+    this.listeners.forEach(listener => listener());
+  }
 
-### IPage
+  async addTodo(title: string) {
+    await this.store.save({ title, completed: false });
+    this.notify();
+  }
 
-分页结果接口：
+  async toggleTodo(id: string) {
+    const todo = await this.store.getInfo({ id });
+    if (todo) {
+      await this.store.update({ completed: !todo.completed }, { id });
+      this.notify();
+    }
+  }
 
-```typescript
-interface IPage<T> {
-  list: T[];        // 数据列表
-  total: number;    // 总记录数
-  page: number;     // 当前页码
-  size: number;     // 每页数量
-  totalPages: number; // 总页数
+  async getTodos() {
+    return await this.store.getList({ sort: { createTime: -1 } });
+  }
 }
 ```
 
-## 🛠️ 开发
-
-### 环境要求
-
-- Node.js >= 18.0.0
-- pnpm (推荐) 或 npm/yarn
-
-### 本地开发
+## 🔧 开发
 
 ```bash
-# 克隆仓库
-git clone https://github.com/your-repo/web-easy-store.git
-
-# 进入目录
-cd web-easy-store
-
 # 安装依赖
-pnpm install
+npm install
 
 # 构建
-pnpm build
-
-# 运行测试
-pnpm test
-```
+npm run build
 
-### 构建输出
+# 测试
+npm test
 
+# 类型检查
+npm run tsc
 ```
-lib/
-├── index.cjs.js    # CommonJS 模块
-├── index.esm.js    # ES 模块
-├── index.umd.js    # UMD 模块
-├── index.min.js    # 压缩版
-└── index.d.ts      # TypeScript 类型定义
-```
-
-## 📝 示例
-
-查看 [`example/`](example/) 目录获取更多使用示例。
 
 ## 📄 许可证
 
-MIT License - 详见 [`LICENSE`](LICENSE) 文件。
-
-## 🤝 贡献
-
-欢迎提交 Issue 和 Pull Request！
-
----
-
-Built with ❤️ using TypeScript and Dexie.js
+MIT License