@ad-execute-manager/helper

A collection of utility helper classes for JavaScript applications including EventEmitter, Logger, Storage, CountRecorder, PubSub, and SerializableError.

Installation

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

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

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

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

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

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

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. 应用状态管理

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. 应用配置管理

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. 广告展示次数限制

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. 应用日志系统

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. 微服务间通信

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. 错误处理与序列化

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

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

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

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

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

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

new SerializableError(message, options)

• message (String): 错误消息
• options (Object, optional): 配置选项
  • errMsg (String): 错误描述
  • errorCode (Number): 错误代码

Methods

• toJSON(): 返回可序列化的错误对象

License

MIT