npm package: @iss-ai/easy-web-store
Description: A simple and efficient state management library for web applications.
Latest version: 0.0.5

# @iss-ai/easy-web-store

一个简单高效的 Web 应用数据存储库，提供多种存储方式（IndexedDB、localStorage、sessionStorage、Cookies、内存），支持完整的 CRUD 操作和丰富的查询条件。

## ✨ 特性

- 🚀 **简单易用**：直观的 API 设计，快速上手
- 💾 **多种存储方式**：支持 IndexedDB、localStorage、sessionStorage、Cookies、内存存储
- 🔧 **TypeScript 支持**：完整的类型定义
- 📦 **轻量级**：零依赖（IndexedDB 版本仅依赖 Dexie.js）
- 🌐 **跨浏览器**：支持现代浏览器（Last 2 versions, > 5%, not IE <= 9）
- 📄 **完整 CRUD**：提供保存、查询、更新、删除等完整数据操作
- 🔍 **丰富查询**：支持多种查询操作符（$eq, $neq, $gt, $lt, $in, $like, $regexp 等）
- 📃 **分页支持**：内置分页功能

## 📦 安装

```bash
# npm
npm install @iss-ai/easy-web-store

# yarn
yarn add @iss-ai/easy-web-store

# pnpm
pnpm add @iss-ai/easy-web-store
```

## 🚀 快速开始

### 基础用法

```typescript
import { EasyDexieStore } from '@iss-ai/easy-web-store';

// 定义数据类型
interface User {
  id?: string | number;
  name: string;
  email: string;
  age: number;
  createTime?: Date;
  updateTime?: Date;
}

// 创建数据存储实例（IndexedDB）
const userStore = new EasyDexieStore<User>('users', 'my-app-db');

// 保存数据
const user = await userStore.save({
  name: 'John',
  email: 'john@example.com',
  age: 25
});

// 查询数据
const users = await userStore.getList({
  where: { age: { $gt: 18 } },
  sort: { createTime: -1 }
});

// 更新数据（更新所有符合条件的记录）
await userStore.update({ age: 26 }, { name: 'John' });

// 删除数据
await userStore.delete({ name: 'John' });
```

### 使用不同的存储方式

```typescript
import { 
  EasyDexieStore,       // IndexedDB（推荐，容量大，支持复杂查询）
  EasyMemoryStore,      // 内存存储（应用重启后数据丢失）
  EasyLocalStorage,     // localStorage（持久化，约 5MB 容量）
  EasySessionStorage,   // sessionStorage（页面关闭后数据丢失）
  EasyCookiesStore      // Cookies（小数据量，支持过期时间）
} from '@iss-ai/easy-web-store';

// 内存存储 - 适合临时数据
const memoryStore = new EasyMemoryStore<User>('temp-users');

// localStorage - 适合持久化数据
const localStore = new EasyLocalStorage<User>('users');

// sessionStorage - 适合会话数据
const sessionStore = new EasySessionStorage<User>('session-users');

// Cookies - 适合小数据量、需要与服务端交互的场景
const cookiesStore = new EasyCookiesStore<User>('cookie-users');
```

## 📖 API 文档

### 通用接口

所有存储类都实现 `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>` |

### 查询条件

```typescript
interface IQueryCondition<T> {
  where?: Partial<T>;      // 查询条件
  sort?: Record<string, 1 | -1>;  // 排序规则
  page?: number;           // 页码（从 1 开始）
  pageSize?: number;       // 每页数量
  fields?: Partial<Record<keyof T, 1>>;  // 字段选择
}
```

### 查询操作符

| 操作符 | 说明 | 示例 |
|--------|------|------|
| `$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 store = new EasyDexieStore<User>('users', 'my-db', 'id,createTime,updateTime,name,email');
```

#### EasyMemoryStore (内存)

- **容量**：受限于浏览器内存
- **持久化**：否（应用重启后丢失）
- **查询能力**：支持完整查询操作符
- **适用场景**：临时数据、缓存

```typescript
const store = new EasyMemoryStore<User>('temp-data');
```

#### EasyLocalStorage (localStorage)

- **容量**：约 5MB
- **持久化**：是
- **查询能力**：支持完整查询操作符
- **适用场景**：中等数据量、需要持久化

```typescript
const store = new EasyLocalStorage<User>('user-preferences');
```

#### EasySessionStorage (sessionStorage)

- **容量**：约 5MB
- **持久化**：否（页面关闭后丢失）
- **查询能力**：支持完整查询操作符
- **适用场景**：会话数据、临时表单

```typescript
const store = new EasySessionStorage<User>('session-data');
```

#### EasyCookiesStore (Cookies)

- **容量**：约 4KB
- **持久化**：可设置过期时间
- **查询能力**：支持完整查询操作符
- **适用场景**：小数据量、需要与服务端共享

```typescript
const store = new EasyCookiesStore<User>('user-settings');
```

## 📝 使用示例

### 完整 CRUD 示例

```typescript
import { EasyDexieStore } from '@iss-ai/easy-web-store';

interface Product {
  id?: string;
  name: string;
  price: number;
  category: string;
  tags?: string[];
  createTime?: Date;
  updateTime?: Date;
}

const productStore = new EasyDexieStore<Product>('products', 'shop-db');

// 创建
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' }
]);

// 查询 - 简单条件
const electronics = await productStore.getList({
  where: { category: 'electronics' }
});

// 查询 - 复杂条件
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 }
});

// 更新
await productStore.update(
  { price: 6799 },
  { name: 'iPhone 15' }
);

// 统计
const count = await productStore.count({ category: 'electronics' });

// 删除
await productStore.delete({ category: 'electronics' });

// 清空
await productStore.clear();
```

### 响应式数据同步示例

```typescript
import { EasyLocalStorage } from '@iss-ai/easy-web-store';

interface Todo {
  id?: string;
  title: string;
  completed: boolean;
  createTime?: Date;
  updateTime?: Date;
}

class TodoStore {
  private store: EasyLocalStorage<Todo>;
  private listeners: Set<() => void> = new Set();

  constructor() {
    this.store = new EasyLocalStorage<Todo>('todos');
  }

  // 订阅数据变化
  subscribe(listener: () => void) {
    this.listeners.add(listener);
    return () => this.listeners.delete(listener);
  }

  // 通知所有订阅者
  private notify() {
    this.listeners.forEach(listener => listener());
  }

  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();
    }
  }

  async getTodos() {
    return await this.store.getList({ sort: { createTime: -1 } });
  }
}
```

## 🔧 开发

```bash
# 安装依赖
npm install

# 构建
npm run build

# 测试
npm test

# 类型检查
npm run tsc
```

## 📄 许可证

MIT License