npm package: @ipeak/local-storage
Description: `LocalStorage` 是一个增强版的本地存储类，提供了数据存储、加密、过期处理、备份与恢复以及事件监听等功能。以下是详细的实现和使用说明。
Latest version: 0.1.0

# LocalStorage 文档

`LocalStorage` 是一个增强版的本地存储类，提供了数据存储、加密、过期处理、备份与恢复以及事件监听等功能。以下是详细的实现和使用说明。

## 1. 功能概述

### 1.1 数据存储

- 支持基本的数据存储和检索。
- 支持命名空间，避免数据冲突。
- 支持数据类型恢复（如字符串、数字、布尔值、日期、对象等）。

### 1.2 加密功能

- 支持数据加密和解密，确保数据安全。
- 使用 `CryptoService` 进行加密和解密操作。

### 1.3 过期机制

- 支持设置数据的过期时间。
- 自动清理过期数据。
- 使用 `ExpirationService` 管理过期数据。

### 1.4 备份与恢复

- 支持将存储的数据导出为 JSON 字符串。
- 支持从 JSON 字符串导入数据。
- 使用 `BackupService` 管理备份和恢复。

### 1.5 事件监听

- 支持事件监听和触发。
- 提供 `CHANGE`、`REMOVE` 和 `CLEAR` 事件。

## 2. 使用方法

### 2.1 初始化

```TypeScript
import LocalStorage from './LocalStorage';

const config = {
  namespace: 'app1', // 命名空间
  key: 'my-encryption-key' // 加密密钥
};
const storage = new LocalStorage(config);
```

### 2.2 存储数据

```TypeScript
storage.set('name', 'Kimi', { encrypt: true }); // 加密存储
storage.set('age', 25); // 普通存储
storage.set('date', new Date(), { expires: 30000 }); // 设置过期时间
```

### 2.3 获取数据

```TypeScript
const name = storage.get('name'); // 获取加密数据
const age = storage.get('age'); // 获取普通数据
const date = storage.get('date'); // 获取过期数据
```

### 2.4 删除数据

```TypeScript
storage.remove('name'); // 删除单个键
storage.clear(); // 清空所有数据
```

### 2.5 备份与恢复

```TypeScript
const backupData = storage.exportData(); // 导出数据
storage.importData(backupData); // 导入数据
```

### 2.6 事件监听

```TypeScript
storage.on(EventTypes.CHANGE, (key, value) => {
  console.log(`Data changed: ${key} = ${value}`);
});

storage.on(EventTypes.REMOVE, (key) => {
  console.log(`Data removed: ${key}`);
});

storage.on(EventTypes.CLEAR, () => {
  console.log('All data cleared');
});
```

## 3. 类定义

### 3.1 `LocalStorageConfig`

```TypeScript
export interface LocalStorageConfig {
  namespace?: string; // 命名空间
  key?: string; // 加密密钥
}
```

### 3.2 `StorageSetOptions`

```TypeScript
export interface StorageSetOptions {
  expires?: number; // 过期时间（毫秒）
  encrypt?: boolean; // 是否加密
}
```

### 3.3 `StorageData`

```TypeScript
export interface StorageData {
  value: string; // 序列化后的值
  type: string; // 数据类型
  expires?: number; // 过期时间戳
  encrypt?: boolean; // 是否加密
}
```

### 3.4 `EventTypes`

```TypeScript
export enum EventTypes {
  CHANGE = 'change',
  REMOVE = 'remove',
  CLEAR = 'clear'
}
```

## 4. 方法说明

### 4.1 `set` 方法

```TypeScript
set(key: string, value: any, options?: StorageSetOptions): void;
```

- 参数：
  - `key`：存储的键名。
  - `value`：存储的值。
  - `options`：可选参数，包含 `expires` 和 `encrypt`。
- 功能：
  - 序列化数据并存储到 `localStorage`。
  - 如果设置了 `encrypt`，则对数据进行加密。
  - 如果设置了 `expires`，则设置过期时间。
  - 触发 `CHANGE` 事件。

## 4.2 `get` 方法

```TypeScript
get(key: string): any;
```

- 参数：
  - key：存储的键名。
- 功能：
  - 从 `localStorage` 中获取数据。
  - 如果数据加密，则解密。
  - 根据存储的类型恢复数据。
  - 如果数据已过期，则清理并返回 null。

### 4.3 `remove` 方法

```TypeScript
remove(key: string): void;
```

- 参数：
  - key：存储的键名。
- 功能：
  - 从 `localStorage` 中删除指定的键。
  - 触发 REMOVE 事件。

### 4.4 `clear` 方法

```TypeScript
clear(): void;
```

- 功能：
  - 清空 `localStorage` 中的所有数据。
  - 触发 `CLEAR` 事件。

### 4.5 `exportData` 方法

```TypeScript
exportData(): string;
```

- 功能：
  - 导出所有存储的数据为 JSON 字符串。

### 4.6 `importData` 方法

```TypeScript
importData(data: string): void;
```

- 参数：
  - `data`：JSON 字符串。
- 功能：
  - 从 JSON 字符串导入数据到 `localStorage`。

### 4.7 `on` 方法

```TypeScript
on(event: string, listener: Listener): void;
```

- 参数：
  - `event`：事件类型。
  - `listener`：事件监听器。
- 功能：
  - 添加事件监听器。

### 4.8 `off` 方法

```TypeScript
off(event: string, listener: Listener): void;
```

- 参数：
  - event：事件类型。
  - listener：事件监听器。
- 功能：
  - 移除事件监听器。

## 5. 示例代码

### 5.1 存储和获取数据

```TypeScript
const storage = new LocalStorage({ namespace: 'app1', key: 'my-key' });

// 存储数据
storage.set('name', 'Kimi', { encrypt: true });
storage.set('age', 25);

// 获取数据
console.log(storage.get('name')); // 输出：Kimi
console.log(storage.get('age')); // 输出：25
```

### 5.2 备份与恢复

```TypeScript
// 导出数据
const backupData = storage.exportData();

// 清空存储
storage.clear();

// 导入数据
storage.importData(backupData);
```

### 5.3 事件监听

```TypeScript
storage.on(EventTypes.CHANGE, (key, value) => {
  console.log(`Data changed: ${key} = ${value}`);
});

storage.set('name', 'Kimi'); // 触发 CHANGE 事件
```

## 6. 注意事项

1. **加密密钥**：确保加密密钥的安全性，避免泄露。
2. **过期时间**：过期时间以毫秒为单位，例如 30000 表示 30 秒后过期。
3. **命名空间**：使用命名空间可以避免数据冲突，但需要确保命名空间的唯一性。

## 7. 依赖模块

- `CryptoService`：用于加密和解密。
- `ExpirationService`：用于管理过期数据。
- `BackupService`：用于备份和恢复数据。
- `EventEmitter`：用于事件监听和触发。

## 8. 兼容性

- 本库兼容现代浏览器，包括 Chrome、Firefox、Safari、Edge 等。
- 不支持 IE 浏览器。

## 9. 贡献

欢迎提交 issue 和 pull request，共同改进 LocalStorage 库。

## 10. 许可证

本项目采用 MIT 许可证。