@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 等）
• 📃 分页支持：内置分页功能

📦 安装

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

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

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

🚀 快速开始

基础用法

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: '[email protected]',
  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' });

使用不同的存储方式

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> |

查询条件

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+）
• 持久化：是
• 查询能力：支持完整查询操作符
• 适用场景：大量数据存储、复杂查询

const store = new EasyDexieStore<User>('users', 'my-db', 'id,createTime,updateTime,name,email');

EasyMemoryStore (内存)

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

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

EasyLocalStorage (localStorage)

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

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

EasySessionStorage (sessionStorage)

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

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

EasyCookiesStore (Cookies)

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

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

📝 使用示例

完整 CRUD 示例

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

响应式数据同步示例

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

🔧 开发

# 安装依赖
npm install

# 构建
npm run build

# 测试
npm test

# 类型检查
npm run tsc

📄 许可证

MIT License