@taicode/common-base 1.0.2 → 1.1.0

package/source/error/error.test.ts

@@ -0,0 +1,293 @@
+import { describe, it, expect } from 'vitest'
+import { UserError, SystemError, UnknownError } from './error'
+
+describe('UserError', () => {
+  describe('constructor', () => {
+    it('应该正确创建UserError实例', () => {
+      const type = 'VALIDATION_ERROR'
+      const message = '输入验证失败'
+      const error = new UserError(type, message)
+
+      expect(error).toBeInstanceOf(Error)
+      expect(error).toBeInstanceOf(UserError)
+      expect(error.name).toBe('UserError')
+      expect(error.type).toBe(type)
+      expect(error.message).toBe(message)
+    })
+
+    it('应该支持ErrorOptions参数', () => {
+      const type = 'VALIDATION_ERROR'
+      const message = '输入验证失败'
+      const cause = new Error('原始错误')
+      const error = new UserError(type, message, { cause })
+
+      expect(error.cause).toBe(cause)
+    })
+
+    it('应该正确设置错误堆栈信息', () => {
+      const error = new UserError('TEST_ERROR', '测试错误')
+      expect(error.stack).toBeDefined()
+      expect(error.stack).toContain('UserError')
+    })
+  })
+
+  describe('is', () => {
+    it('应该正确识别UserError实例', () => {
+      const error = new UserError('TEST_ERROR', '测试错误')
+      expect(UserError.is(error)).toBe(true)
+    })
+
+    it('应该正确识别非UserError实例', () => {
+      const regularError = new Error('普通错误')
+      const systemError = new SystemError('SYSTEM_ERROR', '系统错误')
+      const unknownError = new UnknownError('未知错误')
+
+      expect(UserError.is(regularError)).toBe(false)
+      expect(UserError.is(systemError)).toBe(false)
+      expect(UserError.is(unknownError)).toBe(false)
+      expect(UserError.is(null)).toBe(false)
+      expect(UserError.is(undefined)).toBe(false)
+      expect(UserError.is('字符串')).toBe(false)
+      expect(UserError.is(123)).toBe(false)
+      expect(UserError.is({})).toBe(false)
+    })
+
+    it('应该支持类型守卫功能', () => {
+      const error: unknown = new UserError('TEST_ERROR', '测试错误')
+      
+      if (UserError.is(error)) {
+        // 在类型守卫内部，error的类型应该被正确推断
+        expect(error.type).toBe('TEST_ERROR')
+        expect(error.message).toBe('测试错误')
+        expect(error.name).toBe('UserError')
+      }
+    })
+  })
+
+  describe('继承行为', () => {
+    it('应该正确继承Error的所有属性和方法', () => {
+      const error = new UserError('TEST_ERROR', '测试错误')
+      
+      expect(error.toString()).toContain('测试错误')
+      expect(error.toString()).toContain('UserError')
+      expect(error instanceof Error).toBe(true)
+    })
+
+    it('应该支持Error的标准用法', () => {
+      const error = new UserError('TEST_ERROR', '测试错误')
+      
+      try {
+        throw error
+      } catch (caught) {
+        expect(caught).toBe(error)
+        expect(caught).toBeInstanceOf(UserError)
+      }
+    })
+  })
+})
+
+describe('SystemError', () => {
+  describe('constructor', () => {
+    it('应该正确创建SystemError实例', () => {
+      const type = 'DATABASE_ERROR'
+      const message = '数据库连接失败'
+      const error = new SystemError(type, message)
+
+      expect(error).toBeInstanceOf(Error)
+      expect(error).toBeInstanceOf(SystemError)
+      expect(error.name).toBe('SystemError')
+      expect(error.type).toBe(type)
+      expect(error.message).toBe(message)
+    })
+
+    it('应该支持ErrorOptions参数', () => {
+      const type = 'NETWORK_ERROR'
+      const message = '网络请求失败'
+      const cause = new Error('连接超时')
+      const error = new SystemError(type, message, { cause })
+
+      expect(error.cause).toBe(cause)
+    })
+
+    it('应该正确设置错误堆栈信息', () => {
+      const error = new SystemError('FILE_ERROR', '文件读取失败')
+      expect(error.stack).toBeDefined()
+      expect(error.stack).toContain('SystemError')
+    })
+  })
+
+  describe('is', () => {
+    it('应该正确识别SystemError实例', () => {
+      const error = new SystemError('TEST_ERROR', '测试错误')
+      expect(SystemError.is(error)).toBe(true)
+    })
+
+    it('应该正确识别非SystemError实例', () => {
+      const regularError = new Error('普通错误')
+      const userError = new UserError('USER_ERROR', '用户错误')
+      const unknownError = new UnknownError('未知错误')
+
+      expect(SystemError.is(regularError)).toBe(false)
+      expect(SystemError.is(userError)).toBe(false)
+      expect(SystemError.is(unknownError)).toBe(false)
+      expect(SystemError.is(null)).toBe(false)
+      expect(SystemError.is(undefined)).toBe(false)
+      expect(SystemError.is('字符串')).toBe(false)
+      expect(SystemError.is(123)).toBe(false)
+      expect(SystemError.is({})).toBe(false)
+    })
+
+    it('应该支持类型守卫功能', () => {
+      const error: unknown = new SystemError('DATABASE_ERROR', '数据库错误')
+      
+      if (SystemError.is(error)) {
+        // 在类型守卫内部，error的类型应该被正确推断
+        expect(error.type).toBe('DATABASE_ERROR')
+        expect(error.message).toBe('数据库错误')
+        expect(error.name).toBe('SystemError')
+      }
+    })
+  })
+
+  describe('继承行为', () => {
+    it('应该正确继承Error的所有属性和方法', () => {
+      const error = new SystemError('TEST_ERROR', '测试错误')
+      
+      expect(error.toString()).toContain('测试错误')
+      expect(error.toString()).toContain('SystemError')
+      expect(error instanceof Error).toBe(true)
+    })
+
+    it('应该支持Error的标准用法', () => {
+      const error = new SystemError('TEST_ERROR', '测试错误')
+      
+      try {
+        throw error
+      } catch (caught) {
+        expect(caught).toBe(error)
+        expect(caught).toBeInstanceOf(SystemError)
+      }
+    })
+  })
+})
+
+describe('UnknownError', () => {
+  describe('constructor', () => {
+    it('应该正确创建UnknownError实例', () => {
+      const message = '发生了未知错误'
+      const error = new UnknownError(message)
+
+      expect(error).toBeInstanceOf(Error)
+      expect(error).toBeInstanceOf(UnknownError)
+      expect(error.name).toBe('UnknownError')
+      expect(error.message).toBe(message)
+    })
+
+    it('应该支持ErrorOptions参数', () => {
+      const message = '未知错误'
+      const cause = new Error('原始未知错误')
+      const error = new UnknownError(message, { cause })
+
+      expect(error.cause).toBe(cause)
+    })
+
+    it('应该正确设置错误堆栈信息', () => {
+      const error = new UnknownError('测试未知错误')
+      expect(error.stack).toBeDefined()
+      expect(error.stack).toContain('UnknownError')
+    })
+  })
+
+  describe('is', () => {
+    it('应该正确识别UnknownError实例', () => {
+      const error = new UnknownError('测试错误')
+      expect(UnknownError.is(error)).toBe(true)
+    })
+
+    it('应该正确识别非UnknownError实例', () => {
+      const regularError = new Error('普通错误')
+      const userError = new UserError('USER_ERROR', '用户错误')
+      const systemError = new SystemError('SYSTEM_ERROR', '系统错误')
+
+      expect(UnknownError.is(regularError)).toBe(false)
+      expect(UnknownError.is(userError)).toBe(false)
+      expect(UnknownError.is(systemError)).toBe(false)
+      expect(UnknownError.is(null)).toBe(false)
+      expect(UnknownError.is(undefined)).toBe(false)
+      expect(UnknownError.is('字符串')).toBe(false)
+      expect(UnknownError.is(123)).toBe(false)
+      expect(UnknownError.is({})).toBe(false)
+    })
+  })
+
+  describe('继承行为', () => {
+    it('应该正确继承Error的所有属性和方法', () => {
+      const error = new UnknownError('测试错误')
+      
+      expect(error.toString()).toContain('测试错误')
+      expect(error instanceof Error).toBe(true)
+    })
+
+    it('应该支持Error的标准用法', () => {
+      const error = new UnknownError('测试错误')
+      
+      try {
+        throw error
+      } catch (caught) {
+        expect(caught).toBe(error)
+        expect(caught).toBeInstanceOf(UnknownError)
+      }
+    })
+  })
+})
+
+describe('错误类型区分', () => {
+  it('三种错误类型应该是不同的类', () => {
+    const userError = new UserError('USER_ERROR', '用户错误')
+    const systemError = new SystemError('SYSTEM_ERROR', '系统错误')
+    const unknownError = new UnknownError('未知错误')
+
+    // 每种错误只能被自己的类型检查函数识别
+    expect(UserError.is(userError)).toBe(true)
+    expect(SystemError.is(userError)).toBe(false)
+    expect(UnknownError.is(userError)).toBe(false)
+
+    expect(UserError.is(systemError)).toBe(false)
+    expect(SystemError.is(systemError)).toBe(true)
+    expect(UnknownError.is(systemError)).toBe(false)
+
+    expect(UserError.is(unknownError)).toBe(false)
+    expect(SystemError.is(unknownError)).toBe(false)
+    expect(UnknownError.is(unknownError)).toBe(true)
+  })
+
+  it('所有错误类型都应该是Error的实例', () => {
+    const userError = new UserError('USER_ERROR', '用户错误')
+    const systemError = new SystemError('SYSTEM_ERROR', '系统错误')
+    const unknownError = new UnknownError('未知错误')
+
+    expect(userError instanceof Error).toBe(true)
+    expect(systemError instanceof Error).toBe(true)
+    expect(unknownError instanceof Error).toBe(true)
+  })
+})
+
+describe('泛型类型支持', () => {
+  it('UserError应该支持字符串字面量类型', () => {
+    type ValidationErrorType = 'REQUIRED_FIELD' | 'INVALID_FORMAT' | 'OUT_OF_RANGE'
+    
+    const error = new UserError<ValidationErrorType>('REQUIRED_FIELD', '字段必填')
+    
+    expect(error.type).toBe('REQUIRED_FIELD')
+    expect(UserError.is<ValidationErrorType>(error)).toBe(true)
+  })
+
+  it('SystemError应该支持字符串字面量类型', () => {
+    type SystemErrorType = 'DATABASE_ERROR' | 'NETWORK_ERROR' | 'FILE_ERROR'
+    
+    const error = new SystemError<SystemErrorType>('DATABASE_ERROR', '数据库连接失败')
+    
+    expect(error.type).toBe('DATABASE_ERROR')
+    expect(SystemError.is<SystemErrorType>(error)).toBe(true)
+  })
+})

package/source/error/error.ts

@@ -0,0 +1,38 @@
+interface ErrorOptions {
+  cause?: unknown
+}
+
+/** 用户可见的错误 */
+export class UserError<T extends string> extends Error {
+  constructor(public type: T, public message: string, options?: ErrorOptions) {
+    super(message, options)
+    this.name = 'UserError'
+  }
+
+  static is<T extends string>(error: unknown): error is UserError<T> {
+    return error instanceof UserError
+  }
+}
+
+/** 系统错误 */
+export class SystemError<T extends string> extends Error {
+  constructor(public type: T, public message: string, options?: ErrorOptions) {
+    super(message, options)
+    this.name = 'SystemError'
+  }
+
+  static is<T extends string>(error: unknown): error is SystemError<T> {
+    return error instanceof SystemError
+  }
+}
+
+export class UnknownError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options)
+    this.name = 'UnknownError'
+  }
+
+  static is(error: unknown): boolean {
+    return error instanceof UnknownError
+  }
+}

package/source/error/index.ts

@@ -0,0 +1 @@
+export { UserError, SystemError, UnknownError } from './error'

package/source/event-emitter/event-emitter.test.ts

@@ -0,0 +1,247 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { EventEmitter } from './event-emitter'
+
+// 定义测试用的事件类型
+interface TestEvents {
+  'user-login': { userId: string; timestamp: number }
+  'user-logout': { userId: string }
+  'data-update': string
+  'error': Error
+}
+
+describe('EventEmitter', () => {
+  let emitter: EventEmitter<TestEvents>
+
+  beforeEach(() => {
+    emitter = new EventEmitter<TestEvents>()
+  })
+
+  describe('on 方法', () => {
+    it('应该注册监听器并返回一个关闭函数', () => {
+      const listener = vi.fn()
+      const off = emitter.on('data-update', listener)
+      
+      expect(typeof off).toBe('function')
+      
+      emitter.emit('data-update', 'test data')
+      expect(listener).toHaveBeenCalledWith('test data')
+    })
+
+    it('应该为同一事件注册多个监听器', () => {
+      const listener1 = vi.fn()
+      const listener2 = vi.fn()
+      
+      emitter.on('data-update', listener1)
+      emitter.on('data-update', listener2)
+      
+      emitter.emit('data-update', 'test data')
+      
+      expect(listener1).toHaveBeenCalledWith('test data')
+      expect(listener2).toHaveBeenCalledWith('test data')
+    })
+
+    it('应该允许同一监听器被多次注册', () => {
+      const listener = vi.fn()
+      
+      emitter.on('data-update', listener)
+      emitter.on('data-update', listener)
+      
+      emitter.emit('data-update', 'test data')
+      
+      expect(listener).toHaveBeenCalledTimes(2)
+    })
+  })
+
+  describe('off 方法', () => {
+    it('应该移除特定的监听器', () => {
+      const listener1 = vi.fn()
+      const listener2 = vi.fn()
+      
+      emitter.on('data-update', listener1)
+      emitter.on('data-update', listener2)
+      
+      emitter.off('data-update', listener1)
+      emitter.emit('data-update', 'test data')
+      
+      expect(listener1).not.toHaveBeenCalled()
+      expect(listener2).toHaveBeenCalledWith('test data')
+    })
+
+    it('应该在没有提供特定监听器时移除所有监听器', () => {
+      const listener1 = vi.fn()
+      const listener2 = vi.fn()
+      
+      emitter.on('data-update', listener1)
+      emitter.on('data-update', listener2)
+      
+      emitter.off('data-update')
+      emitter.emit('data-update', 'test data')
+      
+      expect(listener1).not.toHaveBeenCalled()
+      expect(listener2).not.toHaveBeenCalled()
+    })
+
+    it('应该优雅地处理移除不存在的监听器', () => {
+      const listener = vi.fn()
+      
+      // 不应该抛出错误
+      expect(() => {
+        emitter.off('data-update', listener)
+      }).not.toThrow()
+    })
+
+    it('应该与 on 方法返回的 off 函数配合使用', () => {
+      const listener = vi.fn()
+      const off = emitter.on('data-update', listener)
+      
+      off()
+      emitter.emit('data-update', 'test data')
+      
+      expect(listener).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('emit 方法', () => {
+    it('应该用正确的数据调用所有注册的监听器', () => {
+      const listener1 = vi.fn()
+      const listener2 = vi.fn()
+      const testData = { userId: 'user123', timestamp: Date.now() }
+      
+      emitter.on('user-login', listener1)
+      emitter.on('user-login', listener2)
+      
+      emitter.emit('user-login', testData)
+      
+      expect(listener1).toHaveBeenCalledWith(testData)
+      expect(listener2).toHaveBeenCalledWith(testData)
+    })
+
+    it('应该优雅地处理没有监听器的事件', () => {
+      expect(() => {
+        emitter.emit('data-update', 'test data')
+      }).not.toThrow()
+    })
+
+    it('应该处理抛出错误的监听器', () => {
+      const goodListener = vi.fn()
+      const badListener = vi.fn(() => {
+        throw new Error('Listener error')
+      })
+      
+      emitter.on('data-update', goodListener)
+      emitter.on('data-update', badListener)
+      
+      expect(() => {
+        emitter.emit('data-update', 'test data')
+      }).toThrow('Listener error')
+      
+      expect(goodListener).toHaveBeenCalledWith('test data')
+    })
+
+    it('应该创建监听器数组的副本以避免并发修改问题', () => {
+      const listeners: Array<() => void> = []
+      
+      // 创建一个监听器，它会在执行时移除自己
+      const selfRemovingListener = () => {
+        emitter.off('data-update', selfRemovingListener)
+      }
+      
+      // 创建其他监听器
+      const otherListener = vi.fn()
+      
+      emitter.on('data-update', selfRemovingListener)
+      emitter.on('data-update', otherListener)
+      
+      // 发射事件，这应该不会导致问题
+      expect(() => {
+        emitter.emit('data-update', 'test data')
+      }).not.toThrow()
+      
+      expect(otherListener).toHaveBeenCalledWith('test data')
+    })
+  })
+
+  describe('once 方法', () => {
+    it('应该注册一个只触发一次的监听器', () => {
+      const listener = vi.fn()
+      
+      emitter.once('data-update', listener)
+      
+      emitter.emit('data-update', 'first call')
+      emitter.emit('data-update', 'second call')
+      
+      expect(listener).toHaveBeenCalledTimes(1)
+      expect(listener).toHaveBeenCalledWith('first call')
+    })
+
+    it('应该处理复杂的事件数据', () => {
+      const listener = vi.fn()
+      const testData = { userId: 'user123', timestamp: Date.now() }
+      
+      emitter.once('user-login', listener)
+      
+      emitter.emit('user-login', testData)
+      emitter.emit('user-login', { userId: 'user456', timestamp: Date.now() })
+      
+      expect(listener).toHaveBeenCalledTimes(1)
+      expect(listener).toHaveBeenCalledWith(testData)
+    })
+  })
+
+  describe('cleanup 方法', () => {
+    it('应该移除所有监听器', () => {
+      const listener1 = vi.fn()
+      const listener2 = vi.fn()
+      
+      emitter.on('data-update', listener1)
+      emitter.on('user-login', listener2)
+      
+      emitter.cleanup()
+      
+      emitter.emit('data-update', 'test data')
+      emitter.emit('user-login', { userId: 'user123', timestamp: Date.now() })
+      
+      expect(listener1).not.toHaveBeenCalled()
+      expect(listener2).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('方法绑定', () => {
+    it('应该将方法正确绑定到实例', () => {
+      const { on, off, once, emit, cleanup } = emitter
+      
+      const listener = vi.fn()
+      
+      // 这些方法应该可以独立调用而不丢失上下文
+      expect(() => {
+        on('data-update', listener)
+        emit('data-update', 'test data')
+        off('data-update', listener)
+        once('data-update', listener)
+        cleanup()
+      }).not.toThrow()
+      
+      expect(listener).toHaveBeenCalledWith('test data')
+    })
+  })
+
+  describe('类型安全', () => {
+    it('应该处理不同的事件类型', () => {
+      const loginListener = vi.fn()
+      const logoutListener = vi.fn()
+      const errorListener = vi.fn()
+      
+      emitter.on('user-login', loginListener)
+      emitter.on('user-logout', logoutListener)
+      emitter.on('error', errorListener)
+      
+      emitter.emit('user-login', { userId: 'user123', timestamp: Date.now() })
+      emitter.emit('user-logout', { userId: 'user123' })
+      emitter.emit('error', new Error('Test error'))
+      
+      expect(loginListener).toHaveBeenCalledWith({ userId: 'user123', timestamp: expect.any(Number) })
+      expect(logoutListener).toHaveBeenCalledWith({ userId: 'user123' })
+      expect(errorListener).toHaveBeenCalledWith(expect.any(Error))
+    })
+  })
+})

package/source/{utils/event-emitter/index.ts → event-emitter/event-emitter.ts}

@@ -75,3 +75,5 @@ export class EventEmitter<Events extends object = object> {
     this.listeners = {}
   }
 }
+
+export type { OffFn, Listener }

package/source/event-emitter/index.ts

@@ -0,0 +1 @@
+export * from './event-emitter'

package/source/index.ts

@@ -0,0 +1,19 @@
+// === 资源管理 ===
+export * from './disposer'
+
+// === 事件系统 ===
+export * from './event-emitter'
+
+// === 日志系统 ===
+export * from './logger'
+
+// === 基础工具 ===
+export * from './string'
+export * from './color'
+export * from './object'
+export * from './number'
+export * from './catch'
+
+// === 函数增强 ===
+export * from './debounce'
+export * from './throttle'

package/source/logger/index.ts

@@ -0,0 +1,43 @@
+// 基础 Logger 实现，支持简单的日志输出和扩展能力
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+export interface LoggerOptions {
+  level?: LogLevel;
+  handler?: (level: LogLevel, ...args: any[]) => void;
+}
+
+export class Logger {
+  private level: LogLevel;
+  private handler: (level: LogLevel, ...args: any[]) => void;
+
+  constructor(options: LoggerOptions = {}) {
+    this.level = options.level || 'info';
+    this.handler = options.handler || this.defaultHandler;
+  }
+
+  private defaultHandler(level: LogLevel, ...args: any[]) {
+    const prefix = `[${level.toUpperCase()}]`;
+    // eslint-disable-next-line no-console
+    (console[level] || console.log)(prefix, ...args);
+  }
+
+  private shouldLog(level: LogLevel): boolean {
+    const order: LogLevel[] = ['debug', 'info', 'warn', 'error'];
+    return order.indexOf(level) >= order.indexOf(this.level);
+  }
+
+  debug(...args: any[]) {
+    if (this.shouldLog('debug')) this.handler('debug', ...args);
+  }
+  info(...args: any[]) {
+    if (this.shouldLog('info')) this.handler('info', ...args);
+  }
+  warn(...args: any[]) {
+    if (this.shouldLog('warn')) this.handler('warn', ...args);
+  }
+  error(...args: any[]) {
+    if (this.shouldLog('error')) this.handler('error', ...args);
+  }
+}
+
+export const logger = new Logger();

package/source/logger/logger.test.ts

@@ -0,0 +1,36 @@
+import { describe, it, expect, vi } from 'vitest';
+import { Logger } from './index';
+
+describe('Logger', () => {
+  it('应该默认记录 info 及以上级别', () => {
+    const handler = vi.fn();
+    const logger = new Logger({ handler });
+    logger.debug('debug');
+    logger.info('info');
+    logger.warn('warn');
+    logger.error('error');
+    expect(handler).not.toHaveBeenCalledWith('debug', 'debug');
+    expect(handler).toHaveBeenCalledWith('info', 'info');
+    expect(handler).toHaveBeenCalledWith('warn', 'warn');
+    expect(handler).toHaveBeenCalledWith('error', 'error');
+  });
+
+  it('应该遵守日志级别', () => {
+    const handler = vi.fn();
+    const logger = new Logger({ level: 'warn', handler });
+    logger.info('info');
+    logger.warn('warn');
+    logger.error('error');
+    expect(handler).not.toHaveBeenCalledWith('info', 'info');
+    expect(handler).toHaveBeenCalledWith('warn', 'warn');
+    expect(handler).toHaveBeenCalledWith('error', 'error');
+  });
+
+  it('应该允许自定义处理器', () => {
+    const logs: any[] = [];
+    const handler = (level: string, ...args: any[]) => logs.push([level, ...args]);
+    const logger = new Logger({ handler });
+    logger.error('err', 123);
+    expect(logs).toContainEqual(['error', 'err', 123]);
+  });
+});

package/source/number/index.ts

@@ -0,0 +1 @@
+export * from './number'