@ad-execute-manager/helper 2.0.0-alpha.2 → 2.0.0

package/README.md

@@ -1,115 +1,453 @@
-# @singcl/helper
-
-A collection of utility helper classes for JavaScript applications including EventEmitter, Logger, Storage, CountRecorder, PubSub, and SerializableError.
-
-## Installation
-
-```bash
-npm install @singcl/helper
-```
-
-## Features
-
-- **EventEmitter**: A powerful event emitter with support for once events, max listeners, and event queuing
-- **Logger**: A flexible logging utility with multiple log levels and customizable prefixes
-- **Storage**: A storage wrapper with expiration support, including "today" expiration for daily data
-- **CountRecorder**: A utility for tracking and managing counts with expiration
-- **PubSub**: A simple publish-subscribe pattern implementation
-- **SerializableError**: An error class that can be serialized to JSON
-
-## Usage
-
-### EventEmitter
-
-```javascript
-import { EventEmitter } from '@singcl/helper';
-
-const emitter = new EventEmitter({ maxListeners: 10 });
-
-emitter.on('event', (data) => {
-  console.log('Received:', data);
-});
-
-emitter.emit('event', { message: 'Hello' });
-```
-
-### Logger
-
-```javascript
-import { Logger } from '@singcl/helper';
-
-const logger = new Logger({ prefix: 'MyApp', level: 'info' });
-
-logger.info('Application started');
-logger.error('Something went wrong');
-```
-
-### Storage
-
-```javascript
-import { Storage } from '@singcl/helper';
-
-const storage = new Storage({ prefix: 'myapp_' });
-
-// Set data that expires at end of day
-storage.setItem('dailyTask', { completed: false }, 'today');
-
-// Set data with custom expiration (2 hours)
-storage.setItem('tempData', { value: 123 }, 2 * 60 * 60 * 1000);
-
-// Get data
-const data = storage.getItem('dailyTask');
-```
-
-### CountRecorder
-
-```javascript
-import { CountRecorder } from '@singcl/helper';
-
-const recorder = CountRecorder.new({
-  local_sign: 'daily_ads',
-  total: 5,
-  expire: 'today',
-  userId: 'user123'
-});
-
-console.log(recorder.remain()); // Remaining count
-recorder.updateToday(); // Increment today's count
-```
-
-### PubSub
-
-```javascript
-import { PubSub } from '@singcl/helper';
-
-const pubsub = new PubSub();
-
-const unsubscribe = pubsub.on('topic', (data) => {
-  console.log('Received:', data);
-});
-
-pubsub.emit('topic', { message: 'Hello' });
-
-unsubscribe();
-```
-
-### SerializableError
-
-```javascript
-import { SerializableError } from '@singcl/helper';
-
-const error = new SerializableError('Something went wrong', {
-  errorCode: 500,
-  errMsg: 'Internal server error'
-});
-
-console.log(error.toJSON());
-```
-
-## API
-
-See individual class documentation for detailed API information.
-
-## License
-
-MIT
+# @ad-execute-manager/helper
+
+A collection of utility helper classes for JavaScript applications including EventEmitter, Logger, Storage, CountRecorder, PubSub, and SerializableError.
+
+## Installation
+
+```bash
+npm install @ad-execute-manager/helper
+```
+
+## Features
+
+- **EventEmitter**: A powerful event emitter with support for once events, max listeners, and event queuing
+- **Logger**: A flexible logging utility with multiple log levels and customizable prefixes
+- **Storage**: A storage wrapper with expiration support, including "today" expiration for daily data
+- **CountRecorder**: A utility for tracking and managing counts with expiration
+- **PubSub**: A simple publish-subscribe pattern implementation
+- **SerializableError**: An error class that can be serialized to JSON
+
+## Usage
+
+### EventEmitter
+
+```javascript
+import { EventEmitter } from '@ad-execute-manager/helper';
+
+const emitter = new EventEmitter({ maxListeners: 10 });
+
+emitter.on('event', (data) => {
+  console.log('Received:', data);
+});
+
+emitter.emit('event', { message: 'Hello' });
+```
+
+### Logger
+
+```javascript
+import { Logger } from '@ad-execute-manager/helper';
+
+const logger = new Logger({ prefix: 'MyApp', level: 'info' });
+
+logger.info('Application started');
+logger.error('Something went wrong');
+```
+
+### Storage
+
+```javascript
+import { Storage } from '@ad-execute-manager/helper';
+
+const storage = new Storage({ prefix: 'myapp_' });
+
+// Set data that expires at end of day
+storage.setItem('dailyTask', { completed: false }, 'today');
+
+// Set data with custom expiration (2 hours)
+storage.setItem('tempData', { value: 123 }, 2 * 60 * 60 * 1000);
+
+// Get data
+const data = storage.getItem('dailyTask');
+```
+
+### CountRecorder
+
+```javascript
+import { CountRecorder } from '@ad-execute-manager/helper';
+
+const recorder = CountRecorder.new({
+  local_sign: 'daily_ads',
+  total: 5,
+  expire: 'today',
+  userId: 'user123'
+});
+
+console.log(recorder.remain()); // Remaining count
+recorder.updateToday(); // Increment today's count
+```
+
+### PubSub
+
+```javascript
+import { PubSub } from '@ad-execute-manager/helper';
+
+const pubsub = new PubSub();
+
+const unsubscribe = pubsub.on('topic', (data) => {
+  console.log('Received:', data);
+});
+
+pubsub.emit('topic', { message: 'Hello' });
+
+unsubscribe();
+```
+
+### SerializableError
+
+```javascript
+import { SerializableError } from '@ad-execute-manager/helper';
+
+const error = new SerializableError('Something went wrong', {
+  errorCode: 500,
+  errMsg: 'Internal server error'
+});
+
+console.log(error.toJSON());
+```
+
+## Examples
+
+### 实际应用场景示例
+
+#### 1. 应用状态管理
+
+```javascript
+import { EventEmitter } from '@ad-execute-manager/helper';
+
+// 创建一个全局事件总线
+const eventBus = new EventEmitter();
+
+// 组件 A 订阅状态更新
+eventBus.on('userLoggedIn', (userData) => {
+  console.log('User logged in:', userData);
+  // 更新组件状态
+});
+
+// 组件 B 触发登录事件
+function handleLogin(userData) {
+  // 登录逻辑
+  eventBus.emit('userLoggedIn', userData);
+}
+```
+
+#### 2. 应用配置管理
+
+```javascript
+import Storage from '@ad-execute-manager/helper';
+
+// 创建配置存储
+const configStorage = Storage.new({ prefix: 'app_config_' });
+
+// 保存用户偏好设置
+function saveUserPreferences(preferences) {
+  configStorage.setItem('userPreferences', preferences);
+}
+
+// 获取用户偏好设置
+function getUserPreferences() {
+  return configStorage.getItem('userPreferences') || {
+    theme: 'light',
+    notifications: true
+  };
+}
+```
+
+#### 3. 广告展示次数限制
+
+```javascript
+import { CountRecorder } from '@ad-execute-manager/helper';
+
+// 创建广告计数器
+const adCounter = CountRecorder.new({
+  local_sign: 'daily_ads',
+  total: 5, // 每天最多展示 5 次
+  expire: 'today',
+  userId: 'user123'
+});
+
+// 检查是否可以展示广告
+function canShowAd() {
+  return adCounter.remain() > 0;
+}
+
+// 展示广告并更新计数
+function showAd() {
+  if (canShowAd()) {
+    console.log('Showing ad...');
+    adCounter.updateToday();
+    return true;
+  } else {
+    console.log('Ad limit reached for today');
+    return false;
+  }
+}
+```
+
+#### 4. 应用日志系统
+
+```javascript
+import { Logger } from '@ad-execute-manager/helper';
+
+// 创建应用日志器
+const appLogger = new Logger({ 
+  prefix: 'MyApp',
+  level: process.env.NODE_ENV === 'production' ? 'info' : 'debug'
+});
+
+// 记录应用启动
+appLogger.info('Application started');
+
+// 记录错误
+function handleError(error) {
+  appLogger.error('Error occurred:', error);
+  // 错误处理逻辑
+}
+```
+
+#### 5. 微服务间通信
+
+```javascript
+import PubSub from '@ad-execute-manager/helper';
+
+// 创建消息总线
+const messageBus = new PubSub();
+
+// 服务 A 订阅消息
+messageBus.on('orderCreated', (orderData) => {
+  console.log('Processing order:', orderData.id);
+  // 处理订单逻辑
+});
+
+// 服务 B 发布消息
+function createOrder(orderData) {
+  // 创建订单逻辑
+  messageBus.emit('orderCreated', orderData);
+}
+```
+
+#### 6. 错误处理与序列化
+
+```javascript
+import { SerializableError } from '@ad-execute-manager/helper';
+
+// 处理 API 错误
+async function fetchData() {
+  try {
+    const response = await fetch('/api/data');
+    if (!response.ok) {
+      throw new SerializableError('API request failed', {
+        errorCode: response.status,
+        errMsg: response.statusText
+      });
+    }
+    return await response.json();
+  } catch (error) {
+    if (error instanceof SerializableError) {
+      // 序列化错误以便传输
+      console.log('Serialized error:', error.toJSON());
+      // 发送错误到监控系统
+    }
+    throw error;
+  }
+}
+```
+
+## API
+
+### EventEmitter
+
+#### Constructor
+
+```javascript
+new EventEmitter(options)
+```
+
+- **options** (Object): 配置选项
+  - **maxListeners** (Number): 最大监听器数量，默认 5
+  - **maxQueueSize** (Number): 最大队列大小，默认 1
+  - **maxOnceEvents** (Number): 最大一次性事件数量，默认 5
+
+#### Methods
+
+- **on(event, listener)**
+  - **event** (String): 事件名称
+  - **listener** (Function): 事件监听器函数
+  - 注册一个事件监听器
+
+- **once(event, listener)**
+  - **event** (String): 事件名称
+  - **listener** (Function): 事件监听器函数
+  - 注册一个只执行一次的事件监听器
+
+- **emit(event, ...args)**
+  - **event** (String): 事件名称
+  - **...args** (Any): 传递给监听器的参数
+  - 触发一个事件
+
+- **off(event, listenerToRemove)**
+  - **event** (String): 事件名称
+  - **listenerToRemove** (Function): 要移除的监听器函数
+  - 移除一个事件监听器
+
+- **removeAllListeners(event)**
+  - **event** (String, optional): 事件名称，不提供则移除所有事件的监听器
+  - 移除所有事件监听器
+
+- **static geInstance(args)**
+  - **args** (Object): 构造函数参数
+  - 返回 EventEmitter 的单例实例
+
+### Logger
+
+#### Constructor
+
+```javascript
+new Logger(options)
+```
+
+- **options** (Object): 配置选项
+  - **prefix** (String): 日志前缀，默认 'Logger'
+  - **level** (String): 日志级别，可选值: 'error', 'warn', 'info', 'log', 'debug'，默认 'log'
+  - **enabled** (Boolean): 是否启用日志，默认 true
+
+#### Methods
+
+- **enable()**: 启用日志
+- **disable()**: 禁用日志
+- **isEnabled()**: 返回日志是否启用
+- **setLevel(level)**: 设置日志级别
+  - **level** (String): 日志级别
+- **error(message, ...args)**: 输出错误日志
+- **warn(message, ...args)**: 输出警告日志
+- **info(message, ...args)**: 输出信息日志
+- **log(message, ...args)**: 输出普通日志
+- **debug(message, ...args)**: 输出调试日志
+
+### Storage
+
+#### Constructor
+
+```javascript
+new Storage(options)
+```
+
+- **options** (Object): 配置选项
+  - **prefix** (String): 存储键前缀，默认 'storage_'
+  - **expire** (Number|null): 默认过期时间（毫秒），null 表示永不过期
+  - **userId** (String|Number): 用户 ID
+
+#### Methods
+
+- **setItem(key, value, expire)**
+  - **key** (String): 存储键
+  - **value** (Any): 存储值
+  - **expire** (Number|'today', optional): 过期时间（毫秒）或 'today' 表示当天有效
+  - 设置存储项
+
+- **getItem(key)**
+  - **key** (String): 存储键
+  - 返回存储的值，如果过期或不存在则返回 null
+
+- **getUserItem(key)**
+  - **key** (String): 存储键
+  - 返回用户维度的存储值，如果过期或不存在则返回 null
+
+- **setUserItem(key, value, expire)**
+  - **key** (String): 存储键
+  - **value** (Any): 存储值
+  - **expire** (Number|'today', optional): 过期时间（毫秒）或 'today' 表示当天有效
+  - 设置用户维度的存储项
+
+- **removeItem(key)**
+  - **key** (String): 存储键
+  - 删除存储项
+
+- **clear()**: 清空所有存储项
+
+- **keys()**: 返回所有未过期的存储键数组
+
+- **static new(args)**
+  - **args** (Object): 构造函数参数
+  - 返回 Storage 的新实例
+
+### CountRecorder
+
+#### Constructor
+
+```javascript
+new CountRecorder(args)
+```
+
+- **args** (Object): 配置选项
+  - **local_sign** (String): 本地存储标识
+  - **total** (Number, optional): 总次数
+  - **expire** (Number|'today', optional): 过期时间（毫秒）或 'today' 表示当天有效
+  - **userId** (String|Number): 用户 ID
+
+#### Methods
+
+- **updateToday()**: 更新当天计数
+
+- **remain()**: 返回剩余次数
+
+- **static new(args)**
+  - **args** (Object): 构造函数参数
+  - 返回 CountRecorder 的新实例
+
+### PubSub
+
+#### Constructor
+
+```javascript
+new PubSub()
+```
+
+#### Methods
+
+- **on(eventName, callback)**
+  - **eventName** (String): 事件名称
+  - **callback** (Function): 事件回调函数
+  - 注册一个事件监听器，返回一个取消订阅函数
+
+- **off(eventName, callback)**
+  - **eventName** (String): 事件名称
+  - **callback** (Function): 要移除的回调函数
+  - 移除一个事件监听器
+
+- **emit(eventName, ...args)**
+  - **eventName** (String): 事件名称
+  - **...args** (Any): 传递给回调的参数
+  - 触发一个事件
+
+- **once(eventName, callback)**
+  - **eventName** (String): 事件名称
+  - **callback** (Function): 事件回调函数
+  - 注册一个只执行一次的事件监听器
+
+- **listenerCount(eventName)**
+  - **eventName** (String): 事件名称
+  - 返回事件的监听器数量
+
+- **removeAllListeners()**: 移除所有事件监听器
+
+### SerializableError
+
+#### Constructor
+
+```javascript
+new SerializableError(message, options)
+```
+
+- **message** (String): 错误消息
+- **options** (Object, optional): 配置选项
+  - **errMsg** (String): 错误描述
+  - **errorCode** (Number): 错误代码
+
+#### Methods
+
+- **toJSON()**: 返回可序列化的错误对象
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ad-execute-manager/helper",
-  "version": "2.0.0-alpha.2",
+  "version": "2.0.0",
   "description": "A collection of utility helper classes for JavaScript applications including EventEmitter, Logger, Storage, CountRecorder, PubSub, and SerializableError.",
   "type": "module",
   "exports": {
@@ -21,7 +21,7 @@
     "url": "https://github.com/singcl"
   },
   "license": "MIT",
-  "homepage": "https://npmjs.com/package/@singcl/helper",
+  "homepage": "https://npmjs.com/package/@ad-execute-manager/helper",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/singcl/ad-execute-manager.git"